Pinnacle API Data Fields

The Pinnacle API is RESTful service where a client can POST data in JSON over HTTPS method to receive the altitude data in the response.

Pinnacle API End Point: https://api.nextnav.io/plh/v1/get-live-height

The latest version of the Pinnacle API YAML document can be found in the Developer Portal document library folder.

API Inputs

Required Objects:

1. appId
   • This is the unique application ID of the client making the request to the API.
   • Developers need to list this App-ID when requesting the Pinnacle API access KEY in the NextNav Developer Portal.
   • The API KEY is tied to a specific App-ID.
2. deviceId
   • This is a unique Device-ID created by the client for the specific device .
   • The Device-ID needs to be globally unique for a specific device + barometric sensor combination.
   • At minimum, ensure that the Device-ID is globally unique for device + baro sensor and app-Id combination.
   • The Pinnacle System uses this Device-ID to correlate multiple API posts over time in order to perform on-going baro-sensor calibration. Therefore, it’s vital that multiple API posts over time from a given device + baro sensor combination be made with the same Device-ID. This will ensure that the correct device + baro sensor specific calibration value can be used for generating the altitude data. 
3. xyLocation
   • 2D location and associated accuracy (or uncertainty) of device from which pressure data is collected; also utilized to determine the device’s altitude or vertical location above terrain.
   • Since altitude (vertical location) is also referenced to the horizontal location (2D location) of the device – it is important to have a good quality 2D location – indicated by smaller accuracy/uncertainty radius.
4. pressure
   • This is the pressure read/collected from the barometric sensor of device which the client uses to request altitude data via the Pinnacle API.
   • Barometric sensors typically put out pressure readings at the 10Hz rate (1 pressure reading per 0.1 seconds). These pressure readings can in some situations be noisy. Ideally the client must collect ~10 such pressure readings (over 1 sec) and use the average as the pressure value.
   • In addition to average pressure, it requires that the client should use the samples to record the count, min, max and variance values. Any missed field will cause the error of 400.
   • If multiple pressure readings are not available, and a single pressure value is available then that value should be passed in the average position. The other fields should be ignored.    
5. timestamp
   • This is the timestamp in milliseconds at which the device’s 2D-location and pressure data is collected.
   • The xyLocation (2D-location) timestamp and the pressure timestamp needs to be within a second of each other. This is to ensure the altitude generation is tied as closely as possible to the 2d location of the device
   • The client should ensure that the 2D-location data and pressure data do not get stale.
   • Timestamp for the data collection cannot be more than 5 minutes older than the current time. Location, pressure, and time of request time should be within relatively the same timestamp.

Ideal for optimal performance (but optional)

1. appVersion:
   • The field is used to indicate the version of the client-app to assist with reporting debugging etc.
2. serviceType:
   • The field is used to indicate the purpose of the API post. There are 2 possible options: ALT_BAROCAL and BAROCAL_ONLY
     • ALT_BAROCAL will result in the Pinnacle API service performinhg a barometric calibration and generating an altitude value. This service type must be whenever the client needs altitude (vertical location) data in addition to calibration.
     • BAROCAL_ONLY will result in the Pinnacle API service using the data to perform a barometric calibration and will not return altitude data. This service type can be used whenever the client wants to keep the barometric sensor well calibrated and does NOT need altitude data. (BAROCAL_ONLY to be supported at a later time)
   • If this field is not populated the Pinnacle API service will assume ALT_BAROCAL as default.
3. phoneModel:
   • This is the model of the phone/device and could be used by the Pinnacle API service to associate context for the barometric sensor behavior (drift, noise etc.) and is especially useful for large volume of devices of a specific model.
4. baroModel:
   • This is the model of the barometric sensor and could be used by the Pinnacle API service to associate context for the barometric sensor behavior (drift, noise etc.).
5. batteryTemperature:
   • Ideally the Pinnacle API service needs the temperature of the barometric sensor or the closest element to the barometric sensor on the device.
   • In many devices this is not readily available, instead the battery temperature is more readily available.
   • The client has some flexibility in choosing its source of temperature data -dependent on the device’s capability to read such data.
6. activity:
   • This is the activity state of the device at the time of data (location and pressure) collection.
   • The activity state is used by the Pinnacle API to further add context to thedata collected by the client.
   • The YAML document lists the valid values for the activity especially for Android and iOS devices.

API Outputs

1. xyLocation:
   • This is the 2D location provided by the client API call and provided back as a reference to which the altitude data was generated.
2. hae:
   • HAE is an abbreviation for height above ellipsoid.
   • This is an object with 2 fields (1) Z-Height-Value = the altitude data in meters in the WGS-84 datum format and (2) Z-Height-Accuracy = the “accuracy” value is also provided in meters.
   • The Z-Height-Value (HAE in meters) format for altitude data is described more here: https://nextnav.com/hae.
   • The Z-Height-Accuracy (HAE-Accuracy in meters) is reported by the Pinnacle API service at the 68% confidence. This means that there is 68% confidence that estimated altitude value generate by the Pinnacle API will lie in a range of (altitude-Value – altitude-Accuracy) and (altitude-Value + altitude-Accuracy).
     • For example, if the Pinnacle API service generates an HAE value of 30m and an HAE accuracy of 3m, then there is 68% confidence that the HAE value lies between 27m and 33m.
   • The HAE “accuracy” value is not intended to be an estimate of error relative to the actual vertical location of the device, but instead is provided primarily to convey a quality metric for the altitude estimate. The larger the “accuracy” value the poorer the quality of the altitude estimate at 68% confidence. 
3. hat:
   • HAT is an abbreviation for height above terrain.
   • This is an object with 2 fields (1) Z-Height-Value = the altitude data in meters above the ground/terrain as indicated by the 2D-location in the Pinnacle API Post and (2) Z-Height-Accuracy = the “accuracy” also in meters.
   • The Z-Height-Value (HAT in meters) format for altitude data is described more here: https://nextnav.com/hat.
   • The Z-Height-Accuracy (HAT-Accuracy in meters) is reported by the Pinnacle API service at the 68% confidence like the HAE-accuracy above. This means that there is 68% confidence that estimated altitude value generate by the Pinnacle API will lie in a range of (altitude-Value – altitude-Accuracy) and (altitude-Value + altitude-Accuracy).
   • For example, if the Pinnacle API service generates an HAT value of 3m and an HAT accuracy of 3m, then there is 68% confidence that the HAT value lies between 0m and 6m.
   • The HAT “accuracy” value is not intended to be an estimate of error relative to the actual vertical location of the device, but instead is provided primarily to convey a quality metric for the altitude estimate. The larger the “accuracy” value the poorer the quality of the altitude estimate at 68% confidence.
4. barocalNeeded:
   • This field is used by the Pinnacle API service to indicate that the device’s barometric sensor (as indicated by Device-ID and App-ID combination) is not in a “well calibrated” state and a that a calibration is needed.
   • Each individual barometric (mems) sensor drifts at its own unique rate (random walk).
   • Refer to reference document: App Note: NextNav Pinnacle Service Best Practices for more information and tips to calibrate the device’s barometric sensor.
5. timestamp:
   • This is the timestamp (unix time in milliseconds) at which the altitude was computed using the data provide in the Pinnacle API input fields
6. status:
   • The Pinnacle API service provides status-codes in its response to indicate the status of the API transaction.
   • The status codes are: