Data Lens Developer's Guide

Getting the Dataset

The first step in creating a visualization is to get an authentication token for communicating with the Data Lens 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 Data Lens 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 third-party Chrome browser plug-in that is designed to communicate with a backend using a REST API. In this tutorial, we use Postman to communicate with the Data Lens backend using the Data Lens REST API. Of course, there are other similar tools you can use. For information on installing Postman, see Using Postman.

Get an access token

To get an authentication token so that you can access the Data Lens REST API, you need to send your HERE Account credentials to the backend. You include 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 will receive a response that includes an access token and a refresh token.

To get an access token, you need to include your HERE Account email address and password in the call's request body, defined as a JSON object as follows:

{
  "email": "<your email address>",
  "password": "<your password>"
}

When you have defined the request body, send it in a POST to the Data Lens backend as follows:

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

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

Note: A token is valid for one hour.

A note about authentication

You need a valid access token to be fully authenticated on Data Lens. However, you can do some basic interactions with only your app_id and app_code. While you are not fully authenticated in Data Lens, the actions you can do with the Data Lens REST API include the following:

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

While you are a fully authenticated user, the actions 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

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

You upload your own data into Data Lens as comma-separated value (CSV) files, either 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.

Data Lens also 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 example, 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 Data Lens account, you need to call a special resource (starterpack) on the Data Lens REST API to load the starter pack of sample datasets into your account. You need to provide your authentication credentials (app_id and app_code) as URL parameters. Also, you need to include 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

Now send this as a POST, with an empty request body, to the Data Lens REST API as follows:

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

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 Data Lens 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 Data Lens backend as follows:

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

with an empty request body. 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.