Geo-visualization Developer's Guide

Getting the Dataset

The first step in creating a visualization is to get an authentication token for communicating with the Geo-visualization REST API, which you will use to fetch and process data. Using this token and your app_id and app_code, you will initialize the starter pack of sample datasets from the Geo-visualization cloud and store them in your own account. Then, as an example of an API call, you can view some sample data from the earthquake dataset.

A Note about Postman

Postman is a Chrome plugin and desktop application that helps you interact with APIs and see the output. We use it throughout our documentation to illustrate making authenticated requests with the Geo-visualization REST API. Other similar tools are available, but we recommend Postman so you can better follow our examples.

Get an Access Token

To get an authentication token, send your HERE account credentials as a POST request to the Geo-visualization REST API including the email address and password associated with your HERE account in a JSON object and your app_id and app_code as URL parameters.

You can also use the sign_in endpoint in the 01. User Authentication folder of our Postman collection.

The response will include a value called access_token. Copy this token as you will add it to the Authorization parameter in future API requests.

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

{
  "email": "{your email address}",
  "password": "{your password}"
}
Note: A token is valid for one hour.

A Note about Authentication

You need a valid access token to be fully authenticated with Geo-visualization. You can make basic interactions with only your app_id and app_code. These include the following:

  • get an access token (authenticate)
  • execute public queries

While you are a fully authenticated user, you can do include the following:

  • create, read, update, and delete datasets in your account
  • define new queries on a dataset
  • publish queries to make them publicly available
  • execute your non-published queries
  • view the source code definition of queries (authentication is required also to view the definition of public queries)

A Note about Datasets

Geo-visualization processes data via structured datasets organized into rows and columns. Each column represents an attribute of the data (e.g. Region) and the rows represent samples of the data (e.g. Berlin, Utah, Wales). A Geo-visualization dataset will typically include columns for latitude and longitude for plotting data onto a map.

You upload your own data into Geo-visualization as comma-separated value (CSV) files, by loading the file directly or by specifying a URL that points to the file. For details about how to prepare your data, see Managing your Data and Data Format Guidelines.

Geo-visualization provides sample datasets that you can use for practice and training purposes; see the next section (or Loading the Starter Pack) for instructions on how to load them, and Sample Datasets for information about their data.

Get the Earthquake Dataset

In this tutorial, we will use a sample dataset containing information about recorded earthquakes. The dataset contains information about earthquake events, each represented by its location as a pair of geographical coordinates (latitude and longitude), as well as each earthquake's magnitude, depth and region. (The dataset actually contains more columns than these, but we select only some of the columns in our example query. For more information about this dataset, see Sample Datasets.)

To load the earthquake dataset into your Geo-visualization account, you call a special resource (starterpack) on the Geo-visualization REST API. You need to provide your authentication credentials (app_id and app_code) as URL parameters and your authentication token in the Authorization field of the header, appended to the string "Bearer ", as shown in the following figure:

Figure 1. Authorization String = Bearer + Token

Send this as a POST request, with an empty request body, to the Geo-visualization REST API:

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

You can also use the starterpack endpoint in the 02. Starter Pack folder of our Postman collection.

The JSON response body will include a property called datasets, which lists the IDs of all the sample datasets in the starter pack. The earthquake dataset that you will use in this tutorial has the ID:

90af668484394fa782cc103409cafe39

Get Sample Data from the Dataset

You can call the Geo-visualization REST API to return sample data from a dataset. If you wish, you can request sample data from the earthquake dataset to get an idea of the data this tutorial will be visualizing.

To do this, send a GET request to the Geo-visualization REST API with an empty request body:

https://datalens.api.here.com/v1/datasets/90af668484394fa782cc103409cafe39/sample?app_id={YOUR_APP_ID}&app_code={YOUR_APP_CODE}

You can also use the datasets endpoint in the 03. Datasets List/Search folder of our Postman collection.

Be sure to include your token in the Authorization field of the request header, as described above. The response includes a columns property that lists as strings all the column names in the dataset, and a rows property that lists the first 30 rows of data. For example:

Figure 2. Sample Data from the Dataset

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.