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

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.

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.

Example: single shot request for GNSS assistance data

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.

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.

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.