Interacting with the Pinnacle API

This section describes an idealized operational sequence for a client to interact with the Pinnacle API 

Pinnacle API Characteristics

1. When using the Pinnacle API, ensure that the client can make multiple API requests to improve the accuracy of altitude data (as needed/indicated by the HAT/HAE accuracy value).
2. The 1st (ever) API response for each device-ID will typically not be very accurate, especially if the “barocalNeeded” is set to “Y”.
3. Be sure to use the same unique device ID when making a call from a given device to allow the Pinnacle API service to carry over the barometric sensor calibration values across multiple requests.
4. The client should attempt to detect if a device is in an outdoor, ground-level, non-drive scenario, then collect the relevant data and make Pinnacle API request. This will ensure highest quality Baro calibration.
   • If this is not possible, then a few datapoints each day can also work.
5. Ensure that the location and pressure values are collected at the same time stamps together and are not stale.

Suggested Sequence of Operation

1. Once your App is installed on the device, start the client that exercises the Pinnacle API, generate a unique DID, collect the relevant (location, pressure etc.) data and make a Pinnacle API request – even if the App’s use-case does NOT need altitude data.
2. Check for the “barocalNeeded” indicator, if it is set to “Y”, the entity should switch to detecting the ideal baro-calibration data collection opportunity – which is ground level outdoor situations – and collect the relevant (location, pressure etc.) data and make a Pinnacle API request – even if the App’s use-case does NOT need altitude data.
   • The best location to collect data for calibration is ground level outdoor point when a device is stationary or moderately moving
     • Data for calibration should NOT be collected when a device is moving rapidly in the vertical (elevator ride) or horizontal (car, train, plane etc.) direction
   • A “Well Calibrated” barometric pressure sensor on the device is essential to obtain the highly accurate altitude from NextNav’s Pinnacle service.  The accuracy of the altitude data is denoted by the with the “accuracy” data field in the API response.
3. Repeat the process till “barocalNeeded” indicator is returned as “N” – a few times a day or multiple times a day at geographically diverse location.
4. Once the “barocalNeeded” indicator is set to “N” – indicating that the baro sensor on the device has achieved the “well calibrated” state – the client must check every 4-5 days by calling the Pinnacle API to evaluate if the sensor continues to be in this “well calibrated” state.
5. Each time the “barocalNeeded” indicator is returned at “Y” – the client must renew/re-start the data collect and Pinnacle API post process to get the baro-sensor into the “well calibrated” state
   • Ideal data collect by the client should include 3 to 4 data/record collects from a diverse set (3 or 4 locations) of ground level outdoor points/locations.