Introduction

HERE provides two authentication methods for the various APIs. The two approaches include: OAuth and traditional API Keys.

In this tutorial, we will show you how to use OAuth for authentication and authorization. To obtain OAuth credentials you need to create an account with developer.here.com.

For an overview of the tutorial below, checkout the video created by a member of the HERE Developer Relations team.

Understanding Authentication and Authorization

HERE APIs accept requests only from authorized applications. Authorized applications are required to provide an OAuth credential with each request. Requests from anonymous applications are rejected.

Generating HERE OAuth Credentials

To make HERE OAuth API requests, you will need to generate an “access token”. To generate access tokens, you will first need to generate HERE OAuth Credentials from the developer.here.com portal.

Go to developer.here.com and login with your credentials.

Once you’re logged in, navigate to the projects page developer.here.com/projects

In the image below you’ll see our project is named “Freemium 2020-03-31”. Next, we will select “Freemium 2020-03-31”.

Next, select Generate App to create a new REST credential.

Now, you should see the newly generated APP ID.

Click on the Create credentials button to generate an ACCESS KEY and SECRET. The Access Key and Secret are created and displayed in a pop-up window.

Now, click the “Download” button and save this file to a secure place on your local computer.

Please do not share your access key with anyone from HERE. We do not need it to administrate your account.

Now that you have the credentials, let’s learn how to use them to access the HERE APIs.

Access HERE APIs using OAuth

Request a Token

Once you have the access key and secret, you can request an Access Token. The Access Token is what you will include in your requests to the HERE APIs. The request includes the following elements:

Endpoint URL:

    https://account.api.here.com/oauth2/token

Example OAuth HTTP Header:

Content-Type: application/x-www-form-urlencoded
Authorization: OAuth
oauth_consumer_key="<Access Key>",
oauth_nonce="<Random string, uniquely generated for each request>",
oauth_signature="<Signature>",
oauth_signature_method="HMAC-SHA256",
oauth_timestamp="<Epoch seconds>",
oauth_version="1.0"

Request Body:

The request body must contain:
grant_type=client_credentials

Sample Response:

{
    "access_token":"VE5URXlJbjAuLmE4S0l4eVpQVE1zbHRwcnQyZ1BSVGcuS3RHT2V...",
    "token_type":"bearer",
    "expires_in":86399
}

Check out this link to know more about OAuth using Postman.

Now that we know what an example Request and Response should look like, lets go through an example implementation using NodeJS.

If you are not familiar with NodeJS, checkout the NodeJS website to get started.

Here is an example implementation using NodeJS:

Firstly, we will create the OAuth request by creating HTTP headers and a request body. Then, we will send the request to https://account.api.here.com/oauth2/token

The example code below uses OAuth-1.0a which is a node package that helps us to construct the headers required to make an OAuth request. The headers include the following: * consumer * signature method * hash function

We also use crypto since it is a dependency for the OAuth-1.0a package.

The following is the code for your reference:

//Import the below modules using "npm i -save request oauth-1.0a crypto"
const request = require('request')
const OAuth = require('oauth-1.0a')
const crypto = require('crypto') // depenency package for OAuth-1.0a

// Token request function
function generateToken() {
    // #1 Initialize OAuth with your HERE OAuth credentials from the credentials file that you downloaded above
    const oauth = OAuth({
        consumer: {
            key: 'your_key', //Access key
            secret: 'your_secret_key', //Secret key
        },
        signature_method: 'HMAC-SHA256',
        hash_function(base_string, key) {
            return crypto
                .createHmac('sha256', key)
                .update(base_string)
                .digest('base64')
        },
    });
    // #2 Building the request object.
    const request_data = {
        url: 'https://account.api.here.com/oauth2/token',
        method: 'POST',
        data: { grant_type: 'client_credentials' },
    };
    // #3 Sending the request to get the access token
    request(
        {
            url: request_data.url,
            method: request_data.method,
            form: request_data.data,
            headers: oauth.toHeader(oauth.authorize(request_data)),
        },
        function (error, response, body) {

            if (response.statusCode == 200) {
                result = JSON.parse(response.body);
                console.log('Token', result);
            }
        }
    );
}

// Calling this function to get the access token

generateToken();

Response:

    {
        "access_token":"VE5URXlJbjAuLmE4S0l4eVpQVE1zbHRwcnQyZ1BSVGcuS3RHT2V...",
        "token_type":"bearer",
        "expires_in":86399 // milliseconds 
    }

In Step #1 of the code above we start out by initializing the properties of the request and specifying the key, the secret and some configuration options for the request.

Step #2 constructs the request and in Step #3 we send the response while awaiting either an error or a new access_token with an expiration.

Tokens expire after 24 hours. Your application should plan on requesting new access tokens every day.

Now, that we have the access_token we can use it to access the HERE API.

Let’s try accessing the Geocoding API. Now using the newly create access_token, we will create a request using with following code.

var token = access_token; // passing the access_token 
var requestHeaders = { // Preparing the headers
    'Authorization': 'Bearer ' + token
};
var url = "https://geocode.search.hereapi.com/v1/geocode?q=5+Rue+Daunou%2C+75000+Paris%2C+France"

fetch(url, { // making a request 
        method: 'get',
        headers: requestHeaders
    })
    .then(function(response) {
        console.log('hooray');
    })
    .catch(function(e) {
        console.log('Error:', e);
    });

Response should look like this

{
  "items": [
    {
      "title": "5 Rue Daunou, 75002 Paris, France",
      "id": "here:af:streetsection:z42doZW8EyzEiPcuOd5MXB:CggIBCCi-9SPARABGgE1KGQ",
      "resultType": "houseNumber",
      "houseNumberType": "PA",
      "address": {
        "label": "5 Rue Daunou, 75002 Paris, France",
        "countryCode": "FRA",
        "countryName": "France",
        "state": "Île-de-France",
        "county": "Paris",
        "city": "Paris",
        "district": "2e Arrondissement",
        "street": "Rue Daunou",
        "postalCode": "75002",
        "houseNumber": "5"
      },
      "position": {
        "lat": 48.86926,
        "lng": 2.3321
      },
      "access": [
        {
          "lat": 48.86931,
          "lng": 2.33215
        }
      ],
      "mapView": {
        "west": 2.33073,
        "south": 48.86836,
        "east": 2.33347,
        "north": 48.87016
      }
    }
  ]
}

For an explanation of the response above, see the Geocoding & Search documentation.

Conclusion

After going through this tutorial you should have a basic level of understanding in the following:

• How to generate an access token using the OAuth credentials.
• How to use HERE APIs along with OAuth access tokens.

Next steps

• Learn more about HERE’s Geocoding API
• Explore more HERE REST APIs