Request GNSS Data

Building protobuf request

HERE GNSS API uses the same URL for all requests:

   wss://gnss.hereapi.com:443/websocket/v1/?app_id={YOUR_APP_ID}

For more information on how to get your App ID or Oath 2.0 token, see Get Credentials.

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.

Info

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 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_AGNSS_GPS
    },
    {
      "data_type": DATATYPE_AGNSS_GLO
    }
  ]
}

The response that you get back consists of two separate WebSocket messages that both contain a protobuf Message. One of these messages has assistance data for GPS and the other - for GLONASS. The assistance data is received in the data sub-message. The format of the assistance data is described in GNSS Assistance data LPP schema.

{
  "data": [
    {
      "data_type": DATATYPE_AGNSS_GPS,
      "payload": BER encoded LPP data, root element <A-GNSS-ProvideAssistanceData>,
      "metadata": {
        "creation_timestamp": 1615295745
      }
    }
  ]
}

{
  "data": [
    {
      "data_type": DATATYPE_AGNSS_GLO,
      "payload": BER encoded LPP data, root element <A-GNSS-ProvideAssistanceData>,
      "metadata": {
        "creation_timestamp": 1615295745
      }
    }
  ]
}

Example: subscribe to GNSS correction data

When you want to subscribe to all GNSS corrections for GPS and BEIDOU constellations, the following Message is sent to the API:

{
  "subscriptions": [
    {
      "data_type": DATATYPE_GPS_CLOCKS
    },
    {
      "data_type": DATATYPE_BEI_CLOCKS
    },
    {
      "data_type": DATATYPE_GPS_ORBITS
    },
    {
      "data_type": DATATYPE_GLO_ORBITS
    }
  ]
}

As a response, you start receiving WebSocket messages that contain a protobuf Message where the data sub-message contains one of the correctional data types you subscribed to.

Note that the clock and orbit corrections may come at different frequencies. Typically you will get new corrections once per 5 - 15 seconds.

You will receive correctional data until you unsubscribe from the data types or close the WebSocket connection.

{
  "data": [
    {
      "data_type": DATATYPE_GPS_CLOCKS,
      "payload": BER encoded LPP data, root element <A-GNSS-ProvideAssistanceData>, correction data in child element <gnss-SSR-ClockCorrections-r15>
      "metadata": {
        "creation_timestamp": 1615295835
      }
    }
  ]
}

{
  "data": [
    {
      "data_type": DATATYPE_GPS_ORBITS,
      "payload": BER encoded LPP data, root element <A-GNSS-ProvideAssistanceData>, correction data in child element <gnss-SSR-OrbitECEFCorrections-r15>
      "metadata": {
        "creation_timestamp": 1615295840
      }
    }
  ]
}

Example: request predicted GNSS assistance data

When you want to request one set of predicted GNSS assistance data for GPS constellation, the following Message is sent to the API:

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

As a response you receive a WebSocket message that containsa a protobuf Message where the data sub-message contains predicted assistance data for GPS constellation for the next 14 days.

{
  "data": [
    {
      "data_type": DATATYPE_NAV_MODEL_PREDICTIONS_GPS,
      "payload": BER encoded LPP data, several consecutive BER encoded LPP <A-GNSS-ProvideAssistanceData> elements.
      "metadata": {
        "creation_timestamp": 1615295835
      }
    }
  ]
}

Note that in this case the payload contains several consecutive LPP elements that must be decoded one by one. Each element provides predicted navigation models for all valid GPS satellites for 2 hours. GPS predictions are provided for 14 days. So there are 14 * 12 = 168 elements in the payload.

Each of the A-GNSS-ProvideAssistanceData elements has child elements gnss-DayNumber and gnss-TimeOfDay that tell what time it was calculated for.

Info

If you subscribe only to predicted GNSS assistance and / or GNSS assistance, GNSS Assistance 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 or the connection is closed. Fortunately, all WebSocket libraries should send the pong message automatically (pong message support is a MUST feature in 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 connection breaks, for example, due to data connectivity issues.

results matching ""

    No results matching ""