Quick Start - HERE developer portal

This section outlines how to get started quickly using the HERE GNSS Service on the HERE developer portal.

  1. Get a HERE Account
  2. Register your App
  3. Get an API Key
  4. Send a Request

Note

This section provides information on the minimum setup required to begin quickly using the HERE GNSS Service.

The HERE GNSS Service is a only available in the Navigation edition. Before you begin working with the HERE GNSS Service, please contact us to acquire evaluation credentials.

For more detailed information on HERE account setup, app registration, and authentication, see the Identity & Access Management Developer Guide.

Get a HERE Account

If you are an individual developer who has signed up for one of the plans listed on our Developer plans page on developer.here.com., you received a HERE account ID when you signed up. You can use your HERE account to log in to developer.here.com. to create applications. Applications (uniquely identified by an app ID) enable development with HERE products and services.

Register your App

To register your app, follow these steps:

  1. Sign in to developer.here.com..
  2. Click your name, select Projects, and then choose your project from the list. Your project details and available application credentials are then displayed.
  3. Select JavaScript or REST and click Generate App. When your application is created, its app ID is displayed.

Get an API key

To get an API key, follow these steps:

  1. Sign in to developer.here.com..
  2. Click your name, select Projects, and then choose your project from the list. Your project details and available application credentials are then displayed.
  3. Click Create API key to generate a maximum of two API keys for your application. The API key is created and displayed.

Note

HERE GNSS Service is not included in normal HERE Freemium plan.

Contact us for free trials / pricing to activate your API key.

Select Contact us and when writing contact request mention that you want to use GNSS Service.

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_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_BEI_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 both corrections once per 5 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 contains 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.

Note

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 required 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 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 have to decode the payload data if it is in BER encoded LPP format.

If Message.Data.data_type is one of the following data types: DATATYPE_AGNESS_*, DATATYPE_*_CLOCKS, DATATYPE_*_ORBITS, or DATATYPE_NAV_MODEL_PREDICTIONS_*, the data is in BER encoded LPP format.

For the ASN.1 schema that must be used to decode the payloads, see LPP ASN.1 Schema.

The following example demonstrates how to decode the BER encoded LPP data using C++ code, protobuf classes generated by Google protoc compiler, and a LPP decoder generated from ASN.1 schema by using asn1c compiler.


// Subscribe to GNSS assistance data
serverSubscription::subscriptions subs;

// Subscribe to GPS, GLONAS, Beidou, Galileo and QZSS assistance data
subs.push_back(here::gnss::DATATYPE_AGNSS_GPS);
subs.push_back(here::gnss::DATATYPE_AGNSS_GLO);
subs.push_back(here::gnss::DATATYPE_AGNSS_GAL);
subs.push_back(here::gnss::DATATYPE_AGNSS_BEI);
subs.push_back(here::gnss::DATATYPE_AGNSS_QZS);

mServerSubscription.subscribeData(
    mConfigValues->mServiceUrl,
    subs,
    [this](const here::gnss::Message_Data *msg) // Message_Data has been generated to Google protoc compiler
    {
        if (msg == nullptr)
        {
            mServerConnection = false;
        }
        else if ((msg->data_type() == here::gnss::DATATYPE_AGNSS_GPS) ||
                (msg->data_type() == here::gnss::DATATYPE_AGNSS_GLO) ||
                (msg->data_type() == here::gnss::DATATYPE_AGNSS_GAL) ||
                (msg->data_type() == here::gnss::DATATYPE_AGNSS_QZS) ||
                (msg->data_type() == here::gnss::DATATYPE_AGNSS_BEI))
        {
            // Decode BER encoded LPP data to this structure
            // The structure definition has been generated from ASN.1 schema
            // by asn1c compiler
            A_GNSS_ProvideAssistanceData_t *structure = NULL;

            // ber_decode function has been generated by asn1c compiler
            asn_dec_rval_t rval = ber_decode(
                NULL,
                &asn_DEF_A_GNSS_ProvideAssistanceData,
                (void **)&structure,
                msg->payload().c_str(),
                msg->payload().size());

            if(rval.code == RC_FAIL || rval.consumed < 2)
            {
                LOGE(TAG, "Decoding LPP data failed");
                ASN_STRUCT_FREE(asn_DEF_A_GNSS_ProvideAssistanceData, structure);
                return false;
            }

            // Use the decoded data. In this example we just copy the iono model.
            if (structure->gnss_CommonAssistData)
            {
                if (structure->gnss_CommonAssistData->gnss_IonosphericModel)
                {
                    if (structure->gnss_CommonAssistData->gnss_IonosphericModel->klobucharModel)
                    {
                        ionUtc.alpha0 = structure->gnss_CommonAssistData->gnss_IonosphericModel->klobucharModel->alfa0;
                        ionUtc.alpha1 = structure->gnss_CommonAssistData->gnss_IonosphericModel->klobucharModel->alfa1;
                        ionUtc.alpha2 = structure->gnss_CommonAssistData->gnss_IonosphericModel->klobucharModel->alfa2;
                        ionUtc.alpha3 = structure->gnss_CommonAssistData->gnss_IonosphericModel->klobucharModel->alfa3;
                        ionUtc.beta0 = structure->gnss_CommonAssistData->gnss_IonosphericModel->klobucharModel->beta0;
                        ionUtc.beta1 = structure->gnss_CommonAssistData->gnss_IonosphericModel->klobucharModel->beta1;
                        ionUtc.beta2 = structure->gnss_CommonAssistData->gnss_IonosphericModel->klobucharModel->beta2;
                        ionUtc.beta3 = structure->gnss_CommonAssistData->gnss_IonosphericModel->klobucharModel->beta3;
                    }
                }
            }

            ...

            ASN_STRUCT_FREE(asn_DEF_A_GNSS_ProvideAssistanceData, structure);
        }

If Message.Data.data_type is DATATYPE_IONEX or DATATYPE_BSX, then Message.Data.payload data is in a text based format.

results matching ""

    No results matching ""