The Point One Navigation Polaris API provides GNSS corrections and supporting data.

System Overview

The Polaris API provides a secure way for a group of devices to use a single API key to request and use Access Tokens to access the Point One GNSS corrections streams.

Message Flow

Device                            Server        Type

            Access Token (http)
 | Access Token Request [API Key]-----> |       JSON
 |            <--------[Access Token]   |       JSON
 |

       GNSS Corrections Streams (TCP/IP)
 | Authorization [Access Token]--->     |       System Message
 | Position (ECEF or LLA) ----->        |       System Message
 |                                      |
 |                <---  Corrections     |       RTCM3 Message
 |                <---  Corrections     |       RTCM3 Message
 |                <---  Corrections     |       RTCM3 Message
 | Position (ECEF or LLA)----->         |       System Message
 |                                      |
 |                <---  Corrections     |       RTCM3 Message
 |                <---  Corrections     |       RTCM3 Message
 |                <---  Corrections     |       RTCM3 Message

Access Token Request

The device submits the API key to receive an [Access Token] which is used to authorize the GNSS streams.

The [Access Token] request endpoint is:

https://api.pointonenav.com/api/v1/auth/token

Method : POST

Auth required : NO

Data constraints

{
    "grant_type": "authorization_code",
    "token_type": "bearer",
    "authorization_code": "[API Key]",
    "unique_id": "[Unique Id]"
}

Data example

{
    "grant_type": "authorization_code",
    "token_type": "bearer",
    "authorization_code": "a94fd3abd3a84o494273h28923dh38",
    "unique_id": "fd3c9b488fbb43459dd920ca11251c2b"
}

Success Response

Code : 200 OK

Content example

{
    "token_type": "bearer",
    "access_token": "3c92c819ebc44def884ab3f931a22024",
    "expires_in": "604800",
    "issued_at": "1515449959"
}

Note: The expiration time indicates the time at which the token can no longer be used for new connections and a new access request must be sent. Once connected using a valid token, a client will continue to receive data even if the token expires.

Error Response

• Code : 403 FORBIDDEN

  Condition : If API_KEY is invalid.  

GNSS Streams

The GNSS stream endpoints and corresponding messages support RTCM3 streams over TCP/IP using an access token for authentication.

The available GNSS stream endpoints are:

polaris.pointonenav.com:8090 (TLS Encrypted)
polaris.pointonenav.com:8088 (plaintext, not recommended for production designs)

System Messages

System messages are framed with a header and footer to aid in processing. The header includes two start bytes, followed by a message class, message ID, and payload length (in bytes). The footer contains a 16b checksum, described below.

Packets look as follows:

0xB5 0x62 <CLASS:1> <ID:1> <LEN_DATA:2> <---DATA---> <CHK:2>

Note: All values in the following messages, including the payload length (LEN_DATA) and checksum (CHK), are little endian.

Checksum is calculated over everything except the first two bytes. The algorithm is:

CK_A, CK_B = 0, 0
for i in range(len(packet)):
  CK_A = CK_A + packet[i]
  CK_B = CK_B + CK_A

# Ensure unsigned byte range
CK_A = CK_A & 0xFF
CK_B = CK_B & 0xFF

# Compute 16b checksum
CHK = (CK_B << 8) | CK_A

Authorization via Access Token

Class: 0xE0 Id: 0x01

Authorization is accomplished by sending the System Message for Authentication:

The payload is the [Access Token] received from the API server encoded as a series of characters: For example, for the access token 3c92c819ebc44def884ab3f931a22024 we have:

b5 62 e0 01 20 00 33 63 39 32 63 38 31 39 65 62 63 34 34 64 65 66 38 38 34 61 62 33 66 39 33 31 61 32 32 30 32 34 c0 b9

(This token in this example is shorter for clarity, an actual token would be much longer like below)

eyJhbGciOiJBMTI4S1ciLCJ6aXAiOiJERUYiLCJlbmMiOiJBMTI4Q0JDLUhTMjU2In0.N-URpWR7VRV44W2uDgbNBb-RaQ4yrgo9jw2Kf_8jOcKp5dCLN1WoLQ.bAljVEcUUpIGpgjEeF441w.orPAve6fhzZoYtSYF7JGAZ0ZHgRuOhFQtVSF7HgIbw4Fn4fgBCQPdvdRJQ5-yvX6NKiuffv1MzTx5lMaB0pXEMf39S9XWh70Ybz8d1OCe5Y.p5FyEcMI2GKIsneHLJmMYw

If the token is invalid or expired, the socket will be closed immediately.

Position ECEF

Class: 0xE0 Id: 0x03

Sending this message causes the backend to reevaluate its assignment of the device’s current correction source. It’s up to the client when to send this, but a common strategy is to remember the last point at which it is sent and only send it again after moving > 1km.

 B5 62 E0 03 0C 00 <ECEFX in cm:4> <ECEFY in cm:4> <ECEFZ in cm:4> <CHK:2>

Note that the ECEF coordinates are sent as signed 32 bit integers in CENTIMETERS.

Position LLA (WGS84)

Class: 0xE0 Id: 0x04

Sending this message causes the backend to reevaluate its assignment of the device’s current correction source. It’s up to the client when to send this, but a common strategy is to remember the last point at which it is sent and only send it again after moving > 1km.

 B5 62 E0 04 0C 00 <LATITUDE:4> <LONGITUDE:4> <ALTITUDE:4> <CHK:2>

Note that the latitude and longitude coordinates are sent as signed 32 bit integers in DECIMAL DEGREES scaled by 1x10^7. Altitude is sent in MILLIMETERS.

RTCM3 Messages

Once the device is authenticated and an initial position message is sent the system will output RTCM3 messages. It is recommended to resend the device position at a regular interval of once a minute. 1 Hz is the highest recommended rate for high dynamic applications.

Note: RTCM Messages are NOT encapsulated in the system message format.

The system currently outputs RTCM3 messages L1/L2/L5 on GPS, GLONASS, GALILEO AND BEIDOU. The details of those specs are in the RTCM3.1 ICD.