Geovisualization Developer's Guide

Geocoding

Geocoding jobs allow you to create columns with WGS-84 compliant latitude and longitude values from columns with street, postal code, city name and / or country information in a dataset.

Geocoding Workflow

The general workflow for requesting geocoding jobs is as follows:

  1. Determine which address information you wish to use to generate geocoder WGS-84 compliant latitude and longitude values.
  2. Make a geocode request with a request body that defines which columns provide the source for the geocoded information and the names of the new columns. You can also add a list of strings that Geovisualization appends to the input columns. This is useful if you have a list of street addresses from the same town or country, but no column for that data. Appending the strings helps further specify the correct location for the geocoder service.
  3. The processing of a geocode request may take some time, so the response to the request includes a unique ID that you can use to check the status of your request. Geocoder requests can have the following statuses:
    • pending
    • running
    • completed
    • failed
    Make a geocode job status request to determine the status of your geocoding request. (You can also cancel a working geocode request.)
  4. Once the geocode request job status is completed, you can use the new WGS-84 latitude and longitude in your dataset in visualizations.

    If you prefer to use a GUI, you can use the Geovisualization Data Manager to geocode a dataset.

Requesting a Geocoding Job

To request a new geocoding job, you first need to have a dataset available. For more information on how to load data, see Managing your Data.

Once you have an appropriate dataset, you define a JSON request body that specifies the columns in the dataset to convert to geocoordinates:

{
  "input_columns": ["column_1", "column_2", "column_3"],
  "lat_column": "lat",
  "lon_column": "lon"
}

You then send this in an authenticated POST request to:

https://datalens.api.here.com/v1/datasets/{DATASET_ID}/geocode?app_id={YOUR_APP_ID}&app_code={YOUR_APP_CODE}

You can also use the datasets/_ID_/geocode endpoint in the 10. Dataset Transformations folder of our Postman collection.

The response will look something like this:

{
  "status": "pending",
  "kind": "datalens#geocode_job",
  "created_at": "2016-06-23T16:52:46Z",
  "updated_at": "2016-06-23T16:52:46Z",
  "dataset": "87354ed28a66441385942f62e94282ea",
  "id": "c0d0f18e3c184ffd9167e4ddc8bfe133"
}

Example

Consider the following dataset, which has the dataset ID 87354ed28a66441385942f62e94282ea:

Germany;Berlin;Breitscheidplatz;One
Germany;Berlin;Friedrichstraße 44;Two
Germany;Berlin;Großer Stern;Three
Germany;Berlin;Pariser Platz;Four
Germany;Potsdam;Maulbeerallee;Five

You request geocoding based on the first three columns (country, city, and street). The correct geocode job request body is the following:

{
  "input_columns": ["country", "city", "street"],
  "lat_column": "lat",
  "lon_column": "lon"
}

Post this request body to the following resource:

https://datalens.api.here.com/v1/datasets/87354ed28a66441385942f62e94282ea/geocode?app_id={YOUR_APP_ID}&app_code={YOUR_APP_CODE}

The result will look similar to this:

{
  "status": "pending",
  "kind": "datalens#geocode_job",
  "created_at": "2016-06-23T16:52:46Z",
  "updated_at": "2016-06-23T16:52:46Z",
  "dataset": "87354ed28a66441385942f62e94282ea",
  "id": "c0d0f18e3c184ffd9167e4ddc8bfe133"
}
Note: The value for the id field is a unique identifier for the submitted geocoding request. You can use this ID to determine the status of the request, as discussed in the following topic.

Checking the Status of a Geocoding Job

Once you have made a geocode request for a dataset, you can check the job's status with a GET to the following resource, replacing {GEOCODE_JOB_ID} with the job id returned in the response to the geocode request. (In the example above, that id is c0d0f18e3c184ffd9167e4ddc8bfe133) :

https://datalens.api.here.com/v1/jobs/{GEOCODE_JOB_ID}?app_id={YOUR_APP_ID}&app_code={YOUR_APP_CODE}

You can also use the jobs/_ID_ endpoint in the 10. Dataset Transformations folder of our Postman collection.

After you send the GET request, the response will be similar to this:

{
  "status": "completed",
  "kind": "datalens#geocode_job",
  "stats": {
    "geocoded": 5,
    "processed": 5
  },
  "created_at": "2016-06-23T16:52:46Z",
  "updated_at": "2016-06-23T16:52:46Z",
  "dataset_id": "87354ed28a66441385942f62e94282ea",
  "id": "c0d0f18e3c184ffd9167e4ddc8bfe133"
}

New WGS-84 compliant latitude and longitude values are included in new columns in the dataset.

In the example above, the expanded dataset would look as follows:

{
  "kind": "datalens#dataset_sample",
  "rows": [
  [
    "Germany",
    "Berlin",
    "Breitscheidplatz",
    "One",
    52.5052109,
    13.3358698
  ],
  [
    "Germany",
    "Berlin",
    "Friedrichstraße 44",
    "Two",
    52.5071411,
    13.39046
  ],
  [
    "Germany",
    "Berlin",
    "Großer Stern",
    "Three",
    52.5143814,
    13.3511105
  ],
  [
    "Germany",
    "Berlin",
    "Pariser Platz",
    "Four",
    52.5158806,
    13.3789301
  ],
  [
    "Germany",
    "Berlin",
    "Maulbeerallee",
    "Five",
    52.4038315,
    13.0304804
  ]
  ],
  "columns": [
  "column_1",
  "column_2",
  "column_3",
  "column_4",
  "lat",
  "lon"
  ],
  "dataset": "87354ed28a66441385942f62e94282ea"
}

You cannot use this account to purchase a commercial plan on Developer Portal, as it is already associated to plans with different payment methods.

To purchase a commercial plan on Developer Portal, please register for or sign in with a different HERE Account.

Something took longer than expected.

The project should be available soon under your projects page.

Sorry, our services are not available in this region.

Something seems to have gone wrong. Please try again later.

We've detected that your account is set to Australian Dollars (AUD).
Unfortunately, we do not offer checkouts in AUD anymore.
You can continue using your current plan as normal, but to subscribe to one of our new plans,
please register for a new HERE account or contact us for billing questions on selfservesupport@here.com.