Device integration best practices

This section describes best practices for integrating the HERE GNSS Data API v2 into a device or application, to avoid common mistakes that can affect device and service operation.

Secure connection and authentication

The HERE GNSS Data API requires a secure HTTPS connection. Devices must:

Establish a secure HTTPS connection to the service.
Validate the service certificate.
Use credentials from the HERE platform.

Certificate validation

Devices should validate the service certificate using root Certificate Authorities (CAs) stored on the device.

The service root CA is not static and will change over time.

For example, the root CA provider and cryptographic algorithms may change. To prepare for these changes:

Store a set of well-known root CAs on the device.
Implement functionality to update root CAs on the device.

Credential management

There are two options to authenticate: API key or OAuth token.

API key: Static with undefined lifetime. A leaked or stolen API key must be revoked and cannot be recovered. For more information, see How to authorize with an API key.
OAuth token: Tokens are a safer approach, as they have a limited lifetime and must be renewed periodically. For more information, see How to authorize with OAuth 2.0.

Important

Devices must store authentication secrets in a safe, trusted store.

Query behavior

Devices should have logic to limit service queries to ensure solid operation for both the device and the server.

Avoid synchronized queries

Devices must not have logic that would trigger all devices to query data at the same time, as this will cause requests to fail because of rate limiting on the server.

For example:

Do not query assistance data at the exact time previous assistance data becomes invalid.
Do not schedule data queries at a fixed time with respect to UTC.

If devices need to get assistance data in continuous operation (when not receiving it from satellite broadcasts), spread server load by making queries at random times within a reasonable window (for example, within a 5-minute interval).

Request data on demand

For real-time A-GNSS data, make queries on a need basis at the time the data is needed. This is the recommended approach for most use cases.

Error handling

In case of error responses from the API, devices must:

Not retry on permanent client errors (400, 401, 403).
Implement exponential backoff for transient errors (429, 5xx) to avoid further rate limiting and unnecessary requests to the service.

Load testing

The production environment is shared by all API users and is not designed for load testing. Load testing is not allowed. Contact HERE to discuss options.

Reference location

The HERE GNSS Data API does not provide a reference location, which is needed for fast TTFF.

For reference location, see the HERE Network Positioning API.