Protobuf Message · HERE GNSS Service

Visit www.here.com

Protobuf definition for Message

Protocol used in HERE GNSS API

HERE GNSS API uses a special communication protocol based on the protobuf messages shown below.

This protocol enables the communicating parties to request data from each other and to deliver the requested data. To be more specific, a client can request a server to send certain type of assistance data as an immediate single time response or as subscription-type repeated data responses.

The protocol is content type agnostic. The client needs to know the DataType constants and what they mean regarding the data content, format and so on. DataType constants are documented in Data Types.

You can download the gnss.proto file using the following link:

gnss.proto

gnss.proto

/*
Copyright (C) 2019-2021 HERE Global B.V. and its affiliate(s).
All rights reserved.
This software and other materials contain proprietary information
controlled by HERE and are protected by applicable copyright legislation.
Any use and utilization of this software and other materials and
disclosure to any third parties is conditional upon having a separate
agreement with HERE for the access, use, utilization or disclosure of this
software. In the absence of such agreement, the use of the software is not
allowed.
*/


/*
HERE GNSS Assistance protocol

This protocol enables the communicating parties to request data from each
other, and to deliver the requested data. To be more specific, a client can
request a server to send certain type of assistance data; as an immediate
single time response, or as subscription-type repeated data responses.

The protocol is content type agnostic. The client and server need to agree
on the 'data type' constants, and what they mean regarding the data content,
format etc. The data types have been defined in enum DataType in the beginning
of this file.

The protocol is primarily targeted to be used over a WebSocket connection,
but it could be used with other transport protocols as well; there's nothing
WebSocket specific in the protocol.
*/



/*
HERE GNSS Assistance protocol - Data types

Each data type value is an agreement about the details of the data, including:
 - format (e.g. LPP)
 - data contents (e.g. GPS ephemerides)
 - parameters for requesting the data. These parameters are needed only for
   miscellaneous data types
Once the details for some data type constant has been agreed on, the agreement
cannot be changed (unless absolutely sure that no-one is relying on the old
agreement). New data type constant has to be allocated for a new revised
(non-backward-compatible) version of the agreement.

There's no need to allocate the constants in increasing numerical order.
*/

syntax = "proto3";

package here.gnss;

enum DataType {

  /* default value = no DataType value specified */
  DATATYPE_UNSPECIFIED = 0;


  /*
   * Global ionospheric models (GIM) in IONEX 1.1 format.
   * Contains 1-day to 2-day predicted GIMs.
   *
   * Format: IONEX 1.1
   */
  DATATYPE_IONEX = 17000;

  /*
   * Differential code bias (DCB) data in
   * BSX (Bias Solution INdependent EXchange Format (Bias-SINEX)) format.
   *
   * Format: Bias-SINEX 1.00
   */
  DATATYPE_BSX = 17001;

  /*
   * Assistance data for GPS constellation.
   *
   * Format: BER encoded LPP 12.3, root element A-GNSS-ProvideAssistanceData,
   * child elements gnss-ReferenceTime, gnss-IonosphericModel,
   * gnss-TimeModels, gnss-NavigationModel, gnss-RealTimeIntegrity,
   * gnss-Almanac, gnss-UTC-Model, gnss-AuxiliaryInformation
   */
  DATATYPE_AGNSS_GPS = 18005;

  /*
   * Assistance data for GLONASS constellation.
   *
   * Format: BER encoded LPP 12.3, root element A-GNSS-ProvideAssistanceData,
   * child elements gnss-ReferenceTime, gnss-NavigationModel,
   * gnss-RealTimeIntegrity, gnss-Almanac, gnss-UTC-Model,
   * gnss-AuxiliaryInformation
   */
  DATATYPE_AGNSS_GLO = 18006;

  /*
   * Assistance data for Galileo constellation.
   *
   * Format: BER encoded LPP 12.3, root element A-GNSS-ProvideAssistanceData,
   * child elements gnss-ReferenceTime, gnss-IonosphericModel,
   * gnss-TimeModels, gnss-NavigationModel, gnss-RealTimeIntegrity,
   * gnss-Almanac, gnss-UTC-Model
   */
  DATATYPE_AGNSS_GAL = 18007;

  /*
   * Assistance data for Beidou constellation.
   *
   * Format: BER encoded LPP 12.3, root element A-GNSS-ProvideAssistanceData,
   * child elements gnss-ReferenceTime, gnss-IonosphericModel,
   * gnss-TimeModels, gnss-NavigationModel, gnss-RealTimeIntegrity,
   * gnss-Almanac, gnss-UTC-Model
   */
  DATATYPE_AGNSS_BEI = 18008;

  /*
   * Clock corrections for GPS constellation.
   *
   * Format: BER encoded LPP 12.3, root element A-GNSS-ProvideAssistanceData,
   * child element gnss-SSR-ClockCorrections-r15
   */
  DATATYPE_GPS_CLOCKS = 18009;

  /*
   * Clock corrections for GLONASS constellation.
   *
   * There are no request parameters for this data.
   *
   * Format: BER encoded LPP 12.3, root element A-GNSS-ProvideAssistanceData,
   * child element gnss-SSR-ClockCorrections-r15
   */
  DATATYPE_GLO_CLOCKS = 18010;

  /*
   * Clock corrections for Galileo constellation.
   *
   * There are no request parameters for this data.
   *
   * Format: BER encoded LPP 12.3, root element A-GNSS-ProvideAssistanceData,
   * child element gnss-SSR-ClockCorrections-r15
   */
  DATATYPE_GAL_CLOCKS = 18011;

  /*
   * Clock corrections for Beidou constellation.
   *
   * There are no request parameters for this data.
   *
   * Format: BER encoded LPP 12.3, root element A-GNSS-ProvideAssistanceData,
   * child element gnss-SSR-ClockCorrections-r15
   */
  DATATYPE_BEI_CLOCKS = 18012;

  /*
   * Orbit corrections for GPS constellation.
   *
   * There are no request parameters for this data.
   *
   * Format: BER encoded LPP 12.3, root element A-GNSS-ProvideAssistanceData,
   * child element gnss-SSR-OrbitECEFCorrections-r15
   */
  DATATYPE_GPS_ORBITS = 18013;

  /*
   * Orbit corrections for GLONASS constellation.
   *
   * There are no request parameters for this data.
   *
   * Format: BER encoded LPP 12.3, root element A-GNSS-ProvideAssistanceData,
   * child element gnss-SSR-OrbitECEFCorrections-r15
   */
  DATATYPE_GLO_ORBITS = 18014;

  /*
   * Orbit corrections for Galileo constellation.
   *
   * There are no request parameters for this data.
   *
   * Format: BER encoded LPP 12.3, root element A-GNSS-ProvideAssistanceData,
   * child element gnss-SSR-OrbitECEFCorrections-r15
   */
  DATATYPE_GAL_ORBITS = 18015;

  /*
   * Orbit corrections for Beidou constellation.
   *
   * There are no request parameters for this data.
   *
   * Format: BER encoded LPP 12.3, root element A-GNSS-ProvideAssistanceData,
   * child element gnss-SSR-OrbitECEFCorrections-r15
   */
  DATATYPE_BEI_ORBITS = 18016;

  /*
   * Assistance data for QZSS constellation.
   *
   * There are no request parameters for this data.
   *
   * Format: BER encoded LPP 12.3, root element A-GNSS-ProvideAssistanceData,
   * child elements gnss-ReferenceTime, gnss-IonosphericModel,
   * gnss-TimeModels, gnss-NavigationModel, gnss-RealTimeIntegrity,
   * gnss-Almanac, gnss-UTC-Model
   */
  DATATYPE_AGNSS_QZS = 18030;

  /*
   * Number of milliseconds since the Unix Epoch.
   * This can be used for example for service monitoring and testing purposes.
   *
   * Note: the standard Unix Time is in seconds. In order to get that,
   * divide the value by 1000, and round down to the nearest integer value.
   * Otherwise this is the same as the Unix time, just with higher resolution
   * (milliseconds vs. seconds), and without Year 2038 Problem. Leap second
   * handling is similar to stardard Unix Time.
   *
   * By default server sends this data once per second. Less frequent updates
   * can be requested by specifying the interval in subscription request -
   * see ParamsUnixTimestamp.
   *
   * Format:
   * The data is a 64bit unsigned integer value; 8 bytes in little-endian
   * order.
   *
   * Example:
   * d9 7e 1b 0d 6b 01 00 00   = 1559293034201 = 2019-05-31T08:57:14.201Z
   */
  DATATYPE_UNIX_TIMESTAMP = 20000;


  /*
   * Human readable ISO 8601 formatted date time string.
   * This can be used for example for service monitoring and testing purposes.
   *
   * Server sends this data by default once per second. Less frequent updates
   * can be requested by specifying the interval in subscription request -
   * see ParamsIso8601Datetime.
   *
   * The response data can be modified according to the user timezone by
   * specifying the timezone to be used (defaults to UTC i.e. +00:00).
   *
   * Format: ascii/utf-8 string (without null-termination), up to 29 bytes
   *
   * Example:
   * 32 30 31 39 2d 30 35 2d 33 31 54 31 31 3a 35 35 3a 33 39 2e 30 39 31 2b
   * 30 33 3a 30 30    = "2019-05-31T11:55:39.091+03:00"
   */
  DATATYPE_ISO_8601_DATETIME = 20001;

  /*
   * Predicted navigation models for GPS.
   *
   * The prediction period is 14 days.
   * The encoding is BER.
   *
   * Format: several consecutive BER encoded LPP A-GNSS-ProvideAssistanceData elements.
   * Each element provides predicted navigation models for same Toe (Time of
   * Ephemeris) for all valid GPS satellites. The validity of the navigation
   * models starts 2 hours before the Toe and ends 2 hours after the Toe.
   *
   * The interval between A-GNSS-ProvideAssistanceData elements is 2 hours.
   * Therefore, 12 elements are needed to provide predictions for one day.
   */
  DATATYPE_NAV_MODEL_PREDICTIONS_GPS = 22000;

  /*
   * Predicted navigation models for Glonass.
   *
   * The prediction period is 14 days.
   * The encoding is BER.
   *
   * Format: several consecutive BER encoded LPP A-GNSS-ProvideAssistanceData elements.
   * Each element provides predicted navigation models for same time for
   * all valid Glonass satellites.
   *
   * Each navigation model contains tb value that is the index of a 0.5 hour time
   * interval within current day. The validity of the navigation models starts at
   * the beginning of the specified time interval and ends when the time interval
   * ends.
   *
   * The interval between A-GNSS-ProvideAssistanceData elements is 0.5 hours.
   * Therefore, 48 elements are needed to provide predictions for one day.
   */
  DATATYPE_NAV_MODEL_PREDICTIONS_GLO = 22020;

  /*
   * Predicted navigation models for Galileo.
   *
   * The prediction period is 7 days.
   * The encoding is BER.
   *
   * Format: several consecutive BER encoded LPP A-GNSS-ProvideAssistanceData elements.
   * Each element provides predicted navigation models for same Toe (Time of
   * Ephemeris) for all valid Galileo satellites. The validity of the navigation
   * models starts 2 hours before the Toe and ends 2 hours after the Toe.
   *
   * The interval between A-GNSS-ProvideAssistanceData elements is 1 hour.
   * Therefore, 24 elements are needed to provide predictions for one day.
   */
  DATATYPE_NAV_MODEL_PREDICTIONS_GAL = 22040;

  /*
   * Predicted navigation models for Beidou.
   *
   * The prediction period is 7 days.
   * The encoding is BER.
   *
   * Format: several consecutive BER encoded LPP A-GNSS-ProvideAssistanceData elements.
   * Each element provides predicted navigation models for same Toe (Time of
   * Ephemeris) for all valid Beidou satellites. The validity of the navigation
   * models starts 2 hours before the Toe and ends 2 hours after the Toe.
   *
   * The interval between A-GNSS-ProvideAssistanceData elements is 2 hour.
   * Therefore, 12 elements are needed to provide predictions for one day.
   */
  DATATYPE_NAV_MODEL_PREDICTIONS_BEI = 22060;

}


// DATATYPE_UNIX_TIMESTAMP request parameters
enum ParamsUnixTimestamp {
  /* default unspecified value, not valid for use */
  PARAMS_UNIX_TIMESTAMP_UNSPECIFIED = 0;

  /*
   * Data sending interval in seconds. Has an effect only with subscription
   * requests. Optional. If not specified, server will send data once per
   * second.
   * Format: 16bit unsigned integer value (1 - 65535), which corresponds
   * time interval from 1 seconds to about 18 hours. (Value 0 results in
   * the default 1 second interval.)
   */
  PARAMS_UNIX_TIMESTAMP_INTERVAL = 1;
}


// DATATYPE_ISO_8601_DATETIME request parameters
enum ParamsIso8601Datetime {
  /* default unspecified value, not valid for use */
  PARAMS_ISO_8601_DATETIME_UNSPECIFIED = 0;

  /*
   * Data sending interval in seconds. Has an effect only with subscription
   * requests. Optional. If not specified, server will send data once per
   * second.
   * Format: 16bit unsigned integer value (1 - 65535), which corresponds
   * time interval from 1 seconds to about 18 hours. (Value 0 results in
   * the default 1 second interval.)
   */
  PARAMS_ISO_8601_DATETIME_INTERVAL = 1;

  /*
   * Timezone string. The timezone can be either:
   * a) a timezone name, e.g. "America/Vancouver" or "Asia/Kolkata" or
   * b) UTC DST offset ±hhmm, e.g. "-0700" or "+0530"
   * If the timezone name is not recognized, server falls back to use
   * UTC = +0000
   * Format: utf-8 string
   */
  PARAMS_ISO_8601_DATETIME_TIMEZONE = 2;
}




/*
 * Message is the top-level protobuf message type being sent from client to
 * server and from server to client. It comprises sub-messages of different
 * types, which enable client to request data from server, and server to
 * deliver data to client.
 *
 * If a Request is somehow invalid, the response is an Error message.
 */
message Message {

  /*
   * Request is used by client to request data from the server. (At least in
   * principle the other direction is possible as well.) Message type 'Request'
   * can be used both for:
   *  a) single-shot requests, for which the client expects a single (and
   *     immediate) response Data message from the server
   *  b) subscription requests, for which the client expects repeated flow of
   *     response Data messages from the server, whenever server has new data
   *     available (until client unsubscribes)
   *
   * - If the server receives an invalid Request (for example with unsupported
   *   data type), it will reject the Request.
   * - The server may limit the number of concurrent active subscriptions per
   *   client connection, and reject excessive subscriptions.
   */
  message Request {
    // The type of the data requested, required. See DataType.
    DataType data_type = 1;

    // Optional identifier for the request, selected by the client. The server
    // will include the same value in the response Data messages, which enables
    // the client to associate the response Data messages with a request. This
    // might be usefull if the client has made multiple requests for the same
    // data_type (with different request parameters). Value 0 means
    // 'unspecified', and must not be used by the client if it chooses to
    // specify this value explicitly.
    uint32 request_id = 2;

    // Additional request parameters, optional.
    // Arbitrary data given as key-value pairs, where the key is an integer,
    // and the value is a sequence of bytes. The meaning of each key and the
    // further interpretation of the value bytes depends on the assistance
    // data type. See ParamsUnixTimestamp, ParamsIso8601Datetime
    map<uint32, bytes> params = 3;
  }

  /*
   * Unsubscribe is used for cancelling subscription request(s). Subscriptions
   * with matching data type and request id will be cancelled. If no data_type
   * is specified (=0), the unsubsciption is based on the request_id alone.
   * Correspondingly, if no request_id is specified, the unsubscription is done
   * according to the data_type alone. If neither of them is given, all
   * subscriptions will be cancelled.
   */
  message Unsubscribe {
    // The type of the data request(s) to unsubscribe, optional.
    // 0 = unspecified.
    DataType data_type = 1;

    // The ids of the requests(s) to unsubscribe, optional. 0 = unspecified.
    uint32 request_id = 2;
  }

  /*
   * Data-message is used for the actual data delivery (as a response to a
   * subscription or a single-shot request.)
   */
  message Data {
    /*
     * Metadata-message is used to attach metadata about the payload data
     * into the Data-message, optional.
     */
     message Metadata {
      // Unix timestamp when payload data was created, optional.
      uint32 creation_timestamp = 1;
    }

    // The type of the data delivered, always present
    DataType data_type = 1;

    // The id of the request, present only if provided by the client
    uint32 request_id = 2;

    // The payload data
    bytes payload = 3;

    // The metadata
    Metadata metadata = 4;
  }

  /*
   * Error-message is used to indicate that a Request is somehow invalid,
   * for example that a requested data type is not available.
   */
  message Error {
    // The id of the request, present only if provided by the client
    uint32 request_id = 1;

    // Human readable error description, e.g. "Data type not available"
    string title = 2;

    // HTTP status code. We use non-HTTP protocol but we still map errors
    // to well known, standard HTTP status codes.
    // Clients use this code for automated / programmable handling of the errors.
    uint32 status = 3;

    // Required OLP API error code. All GNSS Assistance Data Service API
    // errors have format E619XXX
    // This code is used in the central repository of all OLP error messages.
    string code = 4;

    // E.g. "You cannot subscribe data type DATATYPE_NAV_MODEL_PREDICTIONS_GAL"
    string cause = 5;

    // Actionable instructions for the user,
    // e.g. "Contact hd.gnss.positioning@here.com to buy access."
    string action = 6;

    // Copied from X-Correlation-ID header generated by GNSS assistance server
    string correlation_id = 7;
  }

  // The Message comprises of repeated sub-messages of different types. There
  // can be zero, one, or multiple messages of each of the following types:

  repeated Request requests = 1;  // single-shot requests
  repeated Request subscriptions = 2; // subscription requests
  repeated Unsubscribe unsubscriptions = 3; // unsubscription requests
  repeated Data data = 4; // data deliveries
  repeated Error errors = 5; // errors
}

results matching ""

No results matching ""