[Yandex Cloud documentation](../../index.md) > [Tutorials](../index.md) > [Data analysis and visualization](index.md) > DataLens > Working with geodata > Geocoding with the Yandex Maps API for data visualization in DataLens

# Geocoding with the Yandex Maps API for data visualization in DataLens


In this tutorial, you will learn how to convert addresses to geo-coordinates using the [Geocoder](https://yandex.com/maps-api/products/geocoder-api) API and visualize data in DataLens. Data is processed using Python scripts in Jupyter Notebooks in [Yandex DataSphere](../../datasphere/index.md).

We will use data from a [ClickHouse® demo database](../../datalens/quickstart.md#create-connection) as the data source.

1. [Get your cloud ready](#before-you-begin).
1. [Get the Geocoder API key](#get-key).
1. [Convert your data in DataSphere](#datasphere).
1. [Create a connection to the file in DataLens](#create-connection).
1. [Create a dataset based on the connection](#create-dataset).
1. [Create a chart](#create-chart).

If you no longer need the resources you created, [delete them](#clear-out).

## Getting started {#before-you-begin}

Before getting started, register in Yandex Cloud, set up a [community](../../datasphere/concepts/community.md), and link your [billing account](../../billing/concepts/billing-account.md) to it.
1. [On the DataSphere home page](https://datasphere.yandex.cloud), click **Try for free** and select an account to log in with: Yandex ID or your working account with the identity federation (SSO).
1. Select the [Yandex Identity Hub organization](../../organization/index.md) you are going to use in Yandex Cloud.
1. [Create a community](../../datasphere/operations/community/create.md).
1. [Link your billing account](../../datasphere/operations/community/link-ba.md) to the DataSphere community you are going to work in. Make sure you have a linked billing account and its [status](../../billing/concepts/billing-account-statuses.md) is `ACTIVE` or `TRIAL_ACTIVE`. If you do not have a billing account yet, create one in the DataSphere interface.

{% note tip %}

To use Yandex DataLens and Yandex DataSphere within the Yandex Cloud network, create their instances in the same organization.

{% endnote %}

### Required paid resources {#paid-resources}

The infrastructure deployment cost includes a fee for using [DataSphere computing resources](../../datasphere/pricing.md).

## Get the Geocoder API key {#get-key}

Get a key required to use the Geocoder API:

1. Go to the [Developer dashboard](https://developer.tech.yandex.com) and click **Connect APIs**.

   ![image](../../_assets/datalens/solution-geocoder/developer.png)

1. In the window that opens, select **JavaScript API and Geocoder HTTP API** and click **Continue**.
1. Fill out the form and click **Continue**.
1. In the window that opens, click **Go to API**.
1. Under **API keys**, copy the value of the key.

   ![image](../../_assets/datalens/solution-geocoder/developer-key.png)

## Convert your data in DataSphere {#datasphere}

### Create a project {#create-project}

1. Open the DataSphere [home page](https://datasphere.yandex.cloud).
1. In the left-hand panel, select ![image](../../_assets/console-icons/circles-concentric.svg) **Communities**.
1. Select the community where you want to create a project.
1. On the community page, click ![image](../../_assets/console-icons/folder-plus.svg) **Create project**.
1. In the window that opens, enter a name for the project. You can also add a description as needed.
1. Click **Create**.

### Create a secret {#create-secret}

Create a [secret](../../datasphere/concepts/secrets.md) to store the [Geocoder API key](#get-key):

1. Under **Project resources** on the project page, click ![secret](../../_assets/datasphere/jupyterlab/secret.svg)**Secret**.
1. Click **Create**.
1. In the **Name** field, enter the name for the secret: `API_KEY`.
1. In the **Value** field, enter the key value.
1. Click **Create**. You will see a page with detailed info on the secret you created.

### Create a notebook {#create-notebook}

1. Select the project in your community or on the DataSphere [home page](https://datasphere.yandex.cloud) in the **Recent projects** tab.
1. Click **Open project in JupyterLab** and wait for the loading to complete.
1. In the top panel of the project window, click **File** and select **New** → **Notebook**.
1. Select **DataSphere Kernel** and click **Select**.

   ![image](../../_assets/datalens/solution-geocoder/new-notebook.png)

### Install the dependencies {#dependencies}

1. Paste the code given below into the notebook cell and click ![run](../../_assets/datasphere/jupyterlab/run.svg):

   ```py
   %pip install requests
   %pip install clickhouse-driver
   ```

1. Restart the kernel by clicking **Kernel** → **Restart Kernel** in the top panel of the project window.

### Install the certificates {#certificates}

Install the certificates into the project's local storage:

```bash
#!:bash
mkdir --parents /home/jupyter/datasphere/project/Yandex/

wget "https://storage.yandexcloud.net/cloud-certs/RootCA.pem" \
     --output-document /home/jupyter/datasphere/project/Yandex/RootCA.crt

wget "https://storage.yandexcloud.net/cloud-certs/IntermediateCA.pem" \
     --output-document /home/jupyter/datasphere/project/Yandex/IntermediateCA.crt
```

### Upload and convert your data {#load-and-transform}

1. Create a class to work with the Geocoder API:

   ```py
   import requests
   from dataclasses import dataclass

   @dataclass
   class YandexGeocoder:
       api_key: str
       geocoder_url: str = 'https://geocode-maps.yandex.ru/1.x'

       def adress_to_geopoint(self, address: str) -> str:

           # Converting an address to geo-coordinates in DataLens format

           response = requests.get(self.geocoder_url, params={
               'apikey': self.api_key,
               'geocode': address,
               'format': 'json',
           })
           response.raise_for_status()

           result = response.json()['response']['GeoObjectCollection']['featureMember']
           if not result:
               return None

           lat, lon = result[0]['GeoObject']['Point']['pos'].split(' ')
           return self._to_datalens_format(lon, lat)

       def _to_datalens_format(self, lon, lat):
           return f'[{lon},{lat}]'
    ```

1. Connect to the ClickHouse® demo database:

   ```py
   from clickhouse_driver import Client

   ch_client = Client(
       host='rc1a-ckg8nrosr2lim5iz.mdb.yandexcloud.net',
       user='samples_ro',
       password='MsgfcjEhJk',
       database='samples',
       port=9440,
       secure=True,
       verify=True,
       ca_certs='/home/jupyter/datasphere/project/Yandex/RootCA.crt'
   )
   ```

1. Run a check using this command:

   ```py
   print(ch_client.execute('SELECT version()'))
   ```

   If the connection is successful, the terminal will display the ClickHouse® version number.

1. Export data from the table with shop addresses into the `ch_data` variable:

   ```py
   ch_data = ch_client.execute('SELECT ShopName, ShopAddress FROM MS_Shops')
   ch_data
   ```

1. Convert the addresses from the `ShopAddress` column into geo-coordinates:

   ```py
   import os

   geocoder = YandexGeocoder(api_key=os.environ['API_KEY'])

   encoded_data = [
       (name, geocoder.adress_to_geopoint(adress))
       for name, adress in ch_data
   ]
   encoded_data
   ```

1. Save the data to a file:

   ```py
   import csv
   import sys

   csv_writer = csv.writer(
       sys.stdout,
       delimiter=',',
       quotechar='"',
       quoting=csv.QUOTE_MINIMAL,
   )

   filename = 'encoded_data.csv'

   with open(filename, 'w') as f:
       csv_writer = csv.writer(
           f,
           delimiter=',',
           quotechar='"',
       )
       csv_writer.writerows(encoded_data)
   ```

   You will see the `encoded_data.csv` file in the left-hand panel.

   ![image](../../_assets/datalens/solution-geocoder/encoded-data.png)

1. Download the file: right-click it and select `Download`.

## Create a connection to the file in DataLens {#create-connection}

1. Go to the DataLens [home page](https://datalens.ru/?skipPromo=true).
1. In the left-hand panel, select ![image](../../_assets/console-icons/thunderbolt.svg) **Connections** and click **Create connection**.
1. Under **Files and services**, select the **Files** connection.
1. Click **Upload files** and specify the `encoded_data.csv` file.

   ![image](../../_assets/datalens/solution-geocoder/connection.png)

1. In the top-right corner, click **Create connection**.
1. Enter `geocoder_csv` for the connection name and click **Create**.

## Create a dataset based on the connection {#create-dataset}

1. In the top-right corner, click **Create dataset**.
1. Navigate to the **Fields** tab.
1. Rename the fields as follows:

   * `field1` to `Shop name`
   * `field2` to `Coordinates`

1. For the `Coordinates` field, change the data type to **Geopoint**.

   ![image](../../_assets/datalens/solution-geocoder/dataset.png)

1. In the top-right corner, click **Save**.
1. Enter `geocoder_data` for the dataset name and click **Create**.

## Create a chart {#create-chart}

1. In the top-right corner, click **Create chart**.
1. Select the **Map** visualization type.
1. Drag the `Coordinates` field to the **Points (Geopoints)** section.
1. Drag the `Shop name` field to the **Tooltips** section.

   ![image](../../_assets/datalens/solution-geocoder/chart.png)

1. In the top-right corner, click **Save**.
1. Enter the chart name and click **Save**.

## How to delete the resources you created {#clear-out}

If you no longer plan to use the DataSphere project, [delete it](../../datasphere/operations/projects/delete.md#delete-project).

_ClickHouse® is a registered trademark of [ClickHouse, Inc](https://clickhouse.com)._