Geovisualization Developer's Guide

Authentication

In this step you will authenticate with the Geovisualization REST API and get an authentication token that will allow you to fetch and process data.

Using 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 Geovisualization 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 Geovisualization 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.

The Refresh Token

The response also includes a refresh_token. After the access token has expired, you can send the refresh token to the backend to receive a new pair of access and refresh tokens. You do this with a POST to the following endpoint:

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

Include your original access and refresh tokens in the request body as follows:

{
  "access_token": "{expired access token string}",
  "refresh_token": "{corresponding refresh token string}"
}

The response will include two new values for access_token and refresh_token.

Authenticated vs Unauthenticated Users

You need a valid access token to be fully authenticated with Geovisualization. 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)