# Get started with the HERE GNSS API
This section outlines how to get started quickly using the HERE GNSS Service on the [HERE platform](https://platform.here.com):
## Get a HERE account
Obtain access to the HERE platform through your organization administrator's invitation or [contact us](https://www.here.com/contact?intref=dev_docum) 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](https://www.here.com/contact?intref=dev_docum).
## 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](https://www.here.com/contact?intref=dev_docum) 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:
```bash
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](https://docs.here.com/positioning/docs/protobuf-message) 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](https://developers.google.com/protocol-buffers/docs/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:
```json
{
"requests": [
{
"data_type": DATATYPE_LPP_AGNSS_GPS
},
{
"data_type": DATATYPE_LPP_AGNSS_GAL
}
]
}
```
The response that you get back could be::
```json
{
"data": [
{
"data_type": DATATYPE_LPP_AGNSS_GPS,
"payload": UPER encoded LPP 18.3.0 element
"metadata": {
"creation_timestamp": 1615295745
}
},
{
"data_type": DATATYPE_LPP_AGNSS_GAL,
"payload": UPER encoded LPP 18.3.0 element
"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](https://docs.here.com/positioning/docs/lpp-18-3-0-asn1-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:
```json
{
"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).
```json
{
"data": [
{
"data_type": DATATYPE_LPP_CLOCK_AND_ORBIT_BEI,
"payload": UPER encoded LPP 18.3.0 element
"metadata": {
"creation_timestamp": 1615295835
}
},
{
"data_type": DATATYPE_LPP_CLOCK_AND_ORBIT_GPS,
"payload": UPER encoded LPP 18.3.0 element
"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](https://docs.here.com/positioning/docs/description-ionospheric-corrections).
First, the following `Message` is sent to the API:
```json
{
"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`.
```json
{
"data": [
{
"data_type": DATATYPE_LPP_IONO_GPS,
"payload": UPER encoded LPP 18.3.0 element
"metadata": {
"creation_timestamp": 1615295745
}
},
...
{
"data_type": DATATYPE_LPP_IONO_GPS,
"payload": UPER encoded LPP 18.3.0 element
"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:
```json
{
"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).
```json
{
"data": [
{
"data_type": DATATYPE_LPP_IONO_GPS,
"payload": UPER encoded LPP 18.3.0 element , definition for grid 10
"metadata": {
"creation_timestamp": 1615295835
}
},
...
{
"data_type": DATATYPE_LPP_IONO_GPS,
"payload": UPER encoded LPP 18.3.0 element , corrections for grid 10
"metadata": {
"creation_timestamp": 1615295835
}
},
{
"data_type": DATATYPE_LPP_IONO_GPS,
"payload": UPER encoded LPP 18.3.0 element , definition for grid 11
"metadata": {
"creation_timestamp": 1615295840
}
},
...
{
"data_type": DATATYPE_LPP_IONO_GPS,
"payload": UPER encoded LPP 18.3.0 element , 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:
```json
{
"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.
```json
{
"data": [
{
"data_type": DATATYPE_LPP_NAV_MODEL_PREDICTIONS_GPS,
"payload": UPER encoded LPP 18.3.0 element .
"metadata": {
"creation_timestamp": 1615295835
}
},
...
{
"data_type": DATATYPE_LPP_NAV_MODEL_PREDICTIONS_GPS,
"payload": UPER encoded LPP 18.3.0 element .
"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:
```json
{
"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](https://docs.here.com/positioning/docs/lpp-18-3-0-asn1-schema).
## Next steps
* To learn how to request / subscribe assistance for A-GNSS data, see [GNSS Assistance Data](https://docs.here.com/positioning/docs/concept-gnss-assistance).
* To understand how to request / subscribe correction for HD GNSS data, see [HD GNSS Correction Data](https://docs.here.com/positioning/docs/concept-hd-gnss-assistance).