Overview
Location API can be used to receive location information about all tags of a given site. Once subscribed to a topic, your application will receive MQTT messages. Each message contains a topic and a payload.
Refer ot the “Connection and authentication” for more information about the connection.
The topic of the message contains the API_key, it has the following format:
1 | {environment}/{API_key}/locs |
where
- environment is prod
- API_key gives access to your site on NAO Cloud. API Key can be found and managed in NAO Cloud in the following page: Left menu of your site > Developers > API Keys
Ex: prod/9NqWWUa0uvYLOJWiWme7b/locs where 9NqWWUa0uvYLOJWiWme7b is the API_key generated by NAO Cloud.
Refer to the next section to see how to get meta-data on tags via the REST API.
The payload of the message is in Message Pack format, which is like JSON but small and fast. MessagePack is supported by over 50 programming languages and environments so please pick the one that is most convenient for you. Once unpacked, the payload has the following structure:
2 | 'tag_id': ID of the tag generated by NAO Cloud, required, |
3 | 'site_id': ID of the site generated by NAO Cloud, required, |
4 | 'tracking_id': Tracking identifier of the tag, usually the BLE MAC address, required |
5 | 'lon': longitude in decimal degrees, optional |
6 | 'lat': latitude in decimal degrees, optional |
7 | 'alt': altitude in meters, optional |
8 | 'loc_uncertainty': accuracy in meters, optional |
9 | 'loc_updated_at': timestamp in ms from Epoch, required |
10 | 'duration': period in which the tag is at this position, in seconds, required |
11 | 'debug_enabled': whether the tag is currently being debugged, optional |
12 | 'zone_ids': list of IDs of zones in which the tag is, optional |
13 | 'trigger': trigger of the location, required |
The returned data will contains:
- If the tag has moved: lon, lat, alt, loc_uncertainty, loc_updated_at, duration, zone_ids, trigger
- If the tag has not moved: loc_updated_at, duration, trigger
- If there are alerts triggered: alerts, same format as {environment}/{API_key}/alerts, please see below
- The trigger field can have one of the following values:
- ” or None: NAO Track legacy location update.
- ‘accelerometer’: NAO Track NG location update triggered by movement detection.
- ‘autoloc’: NAO Track NG dummy updates triggered by monitoring gateways.
- ‘button_pressed’: Button-press location update.
- 'dummy_button_press': Dummy button-press event triggered by the user to test the system.
- ‘monitoring’: Automatically generated, periodic NAO Track NG dummy button-press location update, triggered for all NAO Track NG for which a telemetry was received recently. See section "NAO Track NG tags monitoring events" below. Locations with this trigger only are used for monitoring, DO NOT use them as real tags locations.
- 'post_event_loc_update': Post button-press follow up location updates.
- ‘timer’: NAO Track NG periodic location update.
- other: Some events may have other internal triggers. These events should be ignored.
Example:
4 | 'lon': 1.3874217173837997, |
5 | 'lat': 43.56428367165108, |
8 | 'loc_updated_at': 1522856593000, |
11 | 'trigger': 'button_pressed' |
The Location API returns data in real time, the location of each tag are updated every 3 to 5 seconds.
You can obtain the metadata of tags, geofences and alerts using the REST API.
On-demand location
Assets can be defined as being on-demand on NAO Cloud. The asset will be tracked when requesting its location only, instead of continuously. Enabling this option will reduce your asset tracking costs if you don’t need continuous geofencing geonotifications or complete location history and instead only want the ability to sporadically get the asset’s position.
To request the location of an on-demand tag, you will need to send a request on the following API endpoint.
1 | POST /api/v2/sites/{siteID}/nao_trackables/{nao_trackable_id}/locate |
This will locate the tag for the duration configured on NAO Cloud. The default duration is 5 minutes, and can be configured from one to 60 minutes.
On NAO Track NG sites, for each tag, approximately every 10 minutes, a “monitoring” position is sent to the /locs topic to ensure that the tag is healthy even without the tag triggering an actual positioning event (button press, movement, …). This location will have a trigger “monitoring” instead of the usual “button_pressed”, “accelerometer”, ….
This monitoring position is not linked to a real button press but is simulated from the reception of a telemetry frame from the tag, received 10 minutes after the previous simulation. If no telemetry received from the tags, there will be no monitoring position.
Because these monitoring events mimic real push button events, if the dummy location falls in a geofence for which a geonotification has been defined and published, an alert event with the trigger “monitoring” will also be sent on the /alerts topic.
Out-of-site events
When a tag has not been heard on a site for 5 minutes, an MQTT event with the ‘lon’, ‘lat’, ‘alt’ fields set to None will be sent on the /locs topic.
Example:
1 | <span class="ui-provider a b c d e f g h i j k l m n o p q r s t u v w x y z ab ac ae af ag ah ai aj ak" dir="ltr">[{'tag_id': 177019, 'tracking_id': 'AABBCCDDEEFF', 'site_id': 10000, 'lon': None, 'lat': None, 'alt': None, 'loc_uncertainty': None, 'loc_updated_at': 1711653049000, 'duration': 0, 'zone_ids': [], 'trigger': None, 'step_events': [], 'journey_definition_id': None, 'current_step_number': None}]</span> |