GuidesAPI Reference
Guides
  1. Tracking API Dev Guide

Get started

This section outlines how to get started quickly using the HERE Tracking API. The API provides programmatic access to the Tracking backend platform.

📘

Note

All users of HERE APIs must obtain HERE authentication credentials. Then use these credentials to obtain an OAuth token. The credentials are assigned per user.

Get a HERE account

Obtain access to the HERE platform through your organization administrator's invitation or contact us to get started.

  • If your company has already established a HERE platform organization, contact your organization admin who can invite you to join the organization.
  • If your company hasn’t established a HERE platform organization yet, contact us.

Create a Tracking project

To start using the HERE Tracking API, you need to have a Tracking project. To create a Tracking project to your HERE platform organization, follow these steps:

  • Log in to your HERE platform organization in HERE platform portal.
  • Create a new project. Go to Launcher > Projects Manager > Create new project.
  • Open the project, and click the Allow access to resources outside of project toggle to the on position.
  • In the project settings, go to Resources > Services, click Link a service, and select HERE Tracking Prd. Note that the Tracking service is not part of the HERE Base Plan. To obtain a license for the Tracking service, contact your HERE Account Executive.
📘

Note

After the project has been created and the service linked to it, it can take a few minutes before Tracking API accepts requests for the project.

  • Initialize the Tracking project by obtaining a project scoped token for a project user who has ProjectAdmin role and sending a GET request to the /registry/v2/licenses endpoint. For more information on this endpoint, see the API Reference. The response to this request contains an appId which you can use to provision devices for the project.

    tcHost="tracking.hereapi.com"
userEmail="<user's email in the organization>"
userPassword="<user's password>"
realm="<organization ID>"  # Example: "org000000000"
projectHrn="<project HRN>" # Example: "hrn:here:authorization::org000000000:project/assettracking"

# Get unscoped user token:
curl -X POST "https://${tcHost}/users/v2/login" \
	-H 'Content-Type: application/json' \
	-d '{"email":"'"${userEmail}"'","password":"'"${userPassword}"'","realm":"'"${realm}"'"}'
userToken="<accessToken from the response>"

# Get project scoped user token:
curl -X POST "https://${tcHost}/users/v2/tokenExchange" \
	-H 'Content-Type: application/json' \
	-d '{"accessToken":"'"${userToken}"'","scope":"'"${projectHrn}"'"}'
userScopedToken="<accessToken from the response>"

# Initialize tracking project using project scoped token:
curl -X GET "https://${tcHost}/registry/v2/licenses" \
	-H 'Content-Type: application/json' \
	-H 'Authorization: Bearer '"${userScopedToken}"

Project membership

After a Tracking project is created and intialized, you can manage project members through the HERE platform portal. Authorization for the Tracking API requests is based on project membership. Only requests sent with a token scoped for the project are valid.

To learn more about managing projects, see the Identity and Access Management Developer Guide.

Date of birth precondition

To get a valid user token, every new member invited to the organization must set their birth day. If a user doesn't set their birth day and sends a POST request to the /users/v2/login endpoint, the response is 412 Precondition Failed.

Get an OAuth token

All requests to the API must be authorized by providing a valid OAuth token. You get an OAuth token from a dedicated authentication endpoint. In the API, there are separate authentication endpoints for users and for devices.

  • Users get unscoped user OAuth tokens from the /users/v2/login endpoint by passing their email and password. For more information on this endpoint, see the API Reference.
  • Users get project-scoped user OAuth tokens from the /users/v2/tokenExchange endpoint by passing their unscoped user OAuth token (accessToken) and a HERE platform project HRN (scope). For more information on this endpoint, see the API Reference. For more information on project HRN and how to obtain it it, see HRN.
  • Devices get device OAuth tokens from the /v2/token endpoint passing a deviceId and a deviceSecret. For more information on this endpoint, see the API Reference. Device tokens are used with the Ingestion API

Tokens for applications

A HERE platform project can also have applications as members. You can get tokens for applications using the OLP CLI tool. Run this command to get a project-scoped client token:

olp api token get --credentials PATH-TO-FILE --scope PROJECT-HRN

Send a request

The HERE Tracking API hostname for HERE platform projects is tracking.hereapi.com. These projects can be used only with project-scoped tokens. The projectId query parameter isn't required in the requests sent with project-scoped tokens.

Legacy Tracking projects that don't belong to any HERE platform organization use the tracking.api.here.com hostname. Legacy projects can be used only with non-project scoped tokens.

📘

Note

The HERE Tracking API Developer Guide refers to {tcHost} variable, which should substituted with an applicable API hostname.

This is a sample request to the /health endpoint:

curl -X GET 'https://{tcHost}/registry/v2/health'

If the service is up and running, the system returns the following response:

{
    "message": "healthy"
}

Next steps

Updated 23 days ago