GuidesAPI Reference
Guides
  1. HDGNSS And AGNSS Positioning Dev Guide

Get started with the HERE GNSS API

This section outlines how to get started quickly using the HERE GNSS Service on the HERE platform:

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.

Get client credentials

  1. Sign in to the HERE platform using your HERE account.
  2. Select the Access Manager from the launcher.
  3. Select the Apps tab and click Register new app.
  4. Enter a name for the app.
  5. Optional: Enter a description for the app.
  6. Click Register. The HERE platform creates a new app with a unique app ID.
  7. On the Credentials tab, select API Keys and then click Create API key to generate a maximum of two API Keys for your application authentication credentials. The API key is created and displayed.
📘

Note

HERE HD GNSS and A-GNSS Positioning is not included in the HERE Base Plan. Contact us to activate your API key for free trials and for pricing information.

Send a request

The following section provides example request information.

Building the protobuf request

HERE GNSS API uses the same URL for all requests:

   wss://gnss.hereapi.com:443/websocket/v1?apiKey={YOUR_API_KEY}

The request that is sent to the URL is always a protobuf Message defined in gnss.proto that has at least one requests, subscriptions, or unsubscriptions sub-message.

The response(s) is always a protobuf Message that has at least one data sub-message.

📘

Note

If you are not familiar with protobuf, here are some useful tutorials.

Example: Single shot request for GNSS assistance data

📘

Note

The contents of the protobuf messages are shown in a JSON-like format, but you must use the protobuf code that you generate from gnss.proto to create the actual messages.

When you want to make a single shot request for GNSS assistance data for GPS and Galileo constellations, the following Message is sent to the API:

{
  "requests": [
    {
      "data_type": DATATYPE_LPP_AGNSS_GPS
    },
    {
      "data_type": DATATYPE_LPP_AGNSS_GAL
    }
  ]
}

The response that you get back could be::

{
  "data": [
    {
      "data_type": DATATYPE_LPP_AGNSS_GPS,
      "payload": UPER encoded LPP 18.3.0 element <LPP-Message>
      "metadata": {
        "creation_timestamp": 1615295745
      }
    },
    {
      "data_type": DATATYPE_LPP_AGNSS_GAL,
      "payload": UPER encoded LPP 18.3.0 element <LPP-Message>
      "metadata": {
        "creation_timestamp": 1615295745
      }
    }
  ]
}

Alternatively, there could be two separate protobuf messages with one Data sub-message in each. In either way, each data sub-message contains assistance data in the format described in LPP 18.3.0 ASN.1 schema.

Example: Subscribe to GNSS correction data

If you want to subscribe to orbit and clock corrections for GPS and Beidou constellations, you should send the following Message to the API:

{
  "subscriptions": [
    {
      "data_type": DATATYPE_LPP_CLOCK_AND_ORBIT_GPS
    },
    {
      "data_type": DATATYPE_LPP_CLOCK_AND_ORBIT_BEI
    }
  ]
}

As a response, you start receiving protobuf messages where the data sub-messages contain correctional data in LPP-Message's child elements gnss-SSR-ClockCorrections-r15 and gnss-SSR-OrbitCorrections-r15. An example below shows updates to both constellations sent together in a single protobuf message (note that there could be also other elements related to other subscriptions).

{
  "data": [
    {
      "data_type": DATATYPE_LPP_CLOCK_AND_ORBIT_BEI,
      "payload": UPER encoded LPP 18.3.0 element <LPP-Message>
      "metadata": {
        "creation_timestamp": 1615295835
      }
    },
    {
      "data_type": DATATYPE_LPP_CLOCK_AND_ORBIT_GPS,
      "payload": UPER encoded LPP 18.3.0 element <LPP-Message>
      "metadata": {
        "creation_timestamp": 1615295835
      }
    }
  ]
}

Alternatively, there could be two separate protobuf messages with one Data sub-message related to this subscription in each (among other possible data sub-messages). You will receive correctional data until you unsubscribe from the data types or close the WebSocket connection.

Example: Subscribe to ionospheric correction data

If you want to subscribe to ionospheric corrections of certain constellations, for example, GPS, you should first determine the grid IDs of the corrections you need. Here, we describe the typical process of subscribing to ionospheric data using GPS constellation as an example.

For more details on the format of the ionospheric corrections and how to determine the necessary grid ID(s), see Ionospheric corrections details.

First, the following Message is sent to the API:

{
  "requests": [
    {
      "data_type": DATATYPE_LPP_IONO_GPS
    }
  ]
}

The response that you get back is a protobuf Message containing a number of Data sub-messages, each describing one grid in LPP-Message sub-element GNSS-SSR-CorrectionPoints.

{
  "data": [
    {
      "data_type": DATATYPE_LPP_IONO_GPS,
      "payload": UPER encoded LPP 18.3.0 element <LPP-Message>
      "metadata": {
        "creation_timestamp": 1615295745
      }
    },
  ...
    {
      "data_type": DATATYPE_LPP_IONO_GPS,
      "payload": UPER encoded LPP 18.3.0 element <LPP-Message>
      "metadata": {
        "creation_timestamp": 1615295745
      }
    }
  ]
}

From this data, you can determine necessary grid ID(s) for your location and then make a subscription for the ionospheric data. For example, for grid IDs 10 and 11, you should send the following Message to the API:

{
  "subscriptions": [
    {
      "data_type": DATATYPE_LPP_IONO_GPS,
      "params": {
        PARAMS_IONO_CORRECTIONS_GRID_IDS: "10,11"
      }
    }
}

The initial response to this request happens when there is a new definition for the grid and/or correction data. The example below includes both grid definitions and correction data (among possible other elements related to other subscriptions). Each LPP-Message element contains a child element GNSS-SSR-CorrectionPoints (grid definition), or child elements GNSS-SSR-STEC-Correction and GNSS-SSR-GriddedCorrection (actual corrections).

{
  "data": [
    {
      "data_type": DATATYPE_LPP_IONO_GPS,
      "payload": UPER encoded LPP 18.3.0 element <LPP-Message>, definition for grid 10
      "metadata": {
        "creation_timestamp": 1615295835
      }
    },
    ...
    {
      "data_type": DATATYPE_LPP_IONO_GPS,
      "payload": UPER encoded LPP 18.3.0 element <LPP-Message>, corrections for grid 10
      "metadata": {
        "creation_timestamp": 1615295835
      }
    },
    {
      "data_type": DATATYPE_LPP_IONO_GPS,
      "payload": UPER encoded LPP 18.3.0 element <LPP-Message>, definition for grid 11
      "metadata": {
        "creation_timestamp": 1615295840
      }
    },
    ...
    {
      "data_type": DATATYPE_LPP_IONO_GPS,
      "payload": UPER encoded LPP 18.3.0 element <LPP-Message>, corrections for grid 11
      "metadata": {
        "creation_timestamp": 1615295840
      }
    }
  ]
}

After that, updates to the subscribed grid definitions and correction data will be sent to the client when they do happen. You will receive ionospheric correctional data until you unsubscribe from the data types or close the WebSocket connection.

Example: request predicted GNSS assistance data

If you want to request one set of predicted GNSS assistance data for GPS constellation, you should send the following Message to the API:

{
  "requests": [
    {
      "data_type": DATATYPE_LPP_NAV_MODEL_PREDICTIONS_GPS
    }
  ]
}

As a response, you receive a protobuf Message where the Data sub-messages contain predicted assistance data for GPS constellation for the next 14 days.

{
  "data": [
    {
      "data_type": DATATYPE_LPP_NAV_MODEL_PREDICTIONS_GPS,
      "payload": UPER encoded LPP 18.3.0 element <LPP-Message>.
      "metadata": {
        "creation_timestamp": 1615295835
      }
    },
    ...
    {
      "data_type": DATATYPE_LPP_NAV_MODEL_PREDICTIONS_GPS,
      "payload": UPER encoded LPP 18.3.0 element <LPP-Message>.
      "metadata": {
        "creation_timestamp": 1615295835
      }
    }
  ]
}

Each LPP-Message element provides predicted navigation models for all the valid GPS satellites for a fixed length time period. The child element gnss-ReferenceTime tells the time the navigation models were calculated for, and gnss-NavigationModel defines the actual navigation models. The interval between navigation models is 2 hours and the GPS predictions are provided for 14 days, so in total, there are 14 * 12 = 168 separate Data elements in the message.

📘

Note

If you subscribe only to predicted GNSS assistance and / or GNSS assistance, GNSS Assistance

📘

Note

Data Service will send you new protobuf Message's very rarely. This happens because the assistance data changes slowly.

New predictions are sent once per 15 minutes and new assistance once per 30 - 60 minutes (depending on the constellation).

In this case, the service will send WebSocket ping messages about once per 50 seconds to keep the connection alive, even behind proxies, firewalls, and load balancers.

Your client must send back WebSocket pong messages, otherwise the connection will be closed. In practice, all WebSocket libraries send the pong messages automatically because the support for pong messages is a required feature in the WebSocket protocol.

Example: Unsubscribe from GNSS corrections

If you want to stop receiving the GNSS corrections to which you subscribed in the previous examples, send this Message to the API:

{
  "unsubscriptions": [
    {
      "data_type": 0
    }
  ]
}

Note that using data_type 0 cancels all subscriptions done in this connection.

🚧

Warning

When the WebSocket connection to HERE GNSS API URL is closed, all subscriptions are automatically closed.

You must subscribe to all data that you want to receive each time you open a WebSocket connection to API.

Use exponential backoff if you reconnect to HERE GNSS API after the connection breaks, for example, due to data connectivity issues.

Use Assistance Data

After you have received a response Message that contains assistance or correctional data from GNSS Assistance Data Service, you should decode the payload data, which is in UPER encoded LPP 18.3.0 format, see LPP 18.3.0 ASN.1 Schema.

Next steps

Updated 11 days ago