How to transfer data with the HERE HD GNSS API

MQTT protocol is used to transfer data to/from IoT devices and the cloud service. Each device must have unique <clientId>. The following MQTT topics are reserved for HD GNSS service.

Application based access

By default clients should use the following topics to have access to client specific data of the application.

<appId> and <clientId> are used to identify the device and pair the position result with the measurement data. Device location data is only accessible using the corresponding response topic with the same <appId> and <clientId>.

Wildcard subscription is only allowed for the last topic level, i.e., for subscribing to all types of responses, for example, v1/sub/app/<appId>/clients/<clientId>/positions/+.

Project based access

Alternatively, clients can use the following topics if they have been configured to have access to a project.

<projectHrn> and <clientId> are used to identify the device and pair the position result with the measurement data. Device location data is only accessible using the corresponding response topic with the same <projectHrn> and <clientId>.

By default, wildcard subscription is only allowed for the last topic level, i.e., for subscribing to all types of responses (for example v1/sub/project/<projectHrn>/clients/<clientId>/positions/+).

It is possible to allow wildcard subscriptions for all clients within a project (for example, v1/sub/project/<projectHrn>/clients/+/positions/+) to be made by specific whitelisted clients. Contact HERE to enable this feature.

📘

Note

The HRN must be URL-encoded to include it in the MQTT topics.

MQTT Topics

📘

Note

Any payload data on MQTT topics must be in a valid protobuf format unless noted otherwise.

/configuration

Publish a message to this topic to configure the cloud service. Default values will be used if no configuration is sent.

Example payload

Measurement data to be sent to service is from automotive grade receiver and receiver type need to be configured to "RECEIVER_TYPE_AUTOMOTIVE". Used receiver have support for Beidou signals B1I, B1C, B2a and this need to be configured by setting "BEIDOU_SIGNALS_SET_1". Positioning session won't be reset when sending configuration message unless the configuration changes.

Configuration {
  forceSessionReset: false
  receiverType: Configuration.ReceiverType.RECEIVER_TYPE_AUTOMOTIVE
  beidouSignals: Configuration.BeidouSignals.BEIDOU_SIGNALS_SET_1
}

/measurements

Publish message to this topic to provide GNSS measurements for cloud processing. Measurements can be provided either as "Android GNSS measurements" or as "RTCM frames". See client implementation instructions for more information how to format the measurement data.

Example payload

The receiver is providing the measurement data as RTCM frames that are attached to the message. The measurement data is stamped with the Unix time when the measurements were collected.

Measurements: {
  gnssMeasurements: GnssMeasurement [
    GnssMeasurement {
      unixTimestampMs: 1709193600100
      gnssMeasurement.rtcmFrame = <RTCM message bytes>
    }
  ]
}

/positions/protobuf

Subscribe to this topic to receive responses for the configuration and measurements messages in protobuf format. The response contains one or more positioning results or status/error messages.

Example payload

Successful data processing with a position response. The service configuration was not reset, and the previously set configurations were used.

ServerResponse {
  responses: [
    ServerResponse.Response {
      response.position: ServerResponse.Response.Position {
        positionTechnology: ServerResponse.Response.Position.PositionTechnology.TECH_PPP
        timestamp: 1709193600000
        lat: 61.4944968194444
        lng: 23.7754625583333
        alt: 150.83
        horizontalUnc: 0.09
        verticalUnc: 0.19
        speed: 0.0
        speedUnc: 0.0
        bearing: 0
        bearingUnc: 0.0
        numSvs: 31
      }
    }
  ]
}

The service was not able to process the data, resulting in the response "MEASUREMENTS_NOT_VALID". The measurements were either invalid or missing.

ServerResponse {
  responses: [
    ServerResponse.Response {
      response.noPosition: ServerResponse.Response.NoPosition {
        reason: ServerResponse.Response.NoPosition.Reason.MEASUREMENTS_NOT_VALID
      }
    }
  ]
}

The service was not able to decode the data, resulting in the error "INVALID_DATA".

ServerResponse {
  responses: [
    ServerResponse.Response {
      response.error: ServerResponse.Response.Error {
        status: ServerResponse.Response.Error.ErrorStatus.INVALID_DATA
        errorMessage: "failed to process measurements"
      }
    }
  ]
}

/positions/json

Subscribe to this topic to receive responses for the configuration and measurements messages in JSON format. The response contains one or more positioning results or status/error messages.

Example payload

Successful data processing with a position response. The service configuration was not reset, and the previously set configurations were used.

{
  "responses": [
    {
      "type": "position",
      "timestamp": 1709193600000,
      "lat": 61.4944968194444,
      "lng": 23.7754625583333,
      "alt": 150.83,
      "horizontalUnc": 0.09,
      "verticalUnc": 0.19,
      "bearing": 0.0,
      "bearingUnc": 0.0,
      "speed": 0.0,
      "speedUnc": 0.0,
      "numSvs": 31,
      "positionTechnology": 1
    }
  ]
}

The service was not able to process the data, resulting in the response "MEASUREMENTS_NOT_VALID". The measurements were either invalid or missing.

{
  "responses": [
    {
      "type": "noPosition",
      "status": 2
    }
  ]
}

The service was not able to decode the data, resulting in the error "INVALID_DATA".

{
  "responses": [
    {
      "type": "error",
      "status": 2
    }
  ]
}