1. How do I get started with using the Public API?
Firstly, you’ll need to create a service account to access the Public API. Details on how to do this at Infogrid REST API v1
The full Public API documentation is available at https://api.infogrid.io/v1/docs
Details about how to create a token to authenticate are in this document: https://drive.google.com/file/d/1tLtikHwKc8ooqjdmregzysaTNc_oI1Ht/view?usp=sharing - Connect to preview
2. What endpoint on the Public API would be best to get started with?
There are two endpoints focused on retrieving events exposed in the Public API:
GET /org/{organization_pk}/sensors/latest-events
which allows you to retrieve the latest event for all sensors in your organisation
GET /org/{organization_pk}/sensors/{deviceName}/events
which allows you to retrieve all events (in the last 90 days) for a particular sensor
Starting with these would be recommended as it return events in our standardised format, and more information on these endpoints can be found on the API docs site (e.g. here)
If you're looking for a snapshot of how all of your sensors are looking at a particular time then
/latest-eventsis probably better as it provides the most recent event for all sensors at a given time and provides it from a single API request.
If you're more interested in readings/trends over time then
/eventsis better suited. However, given that you can only retrieve data for one sensor at a time, for organisations with a lot of sensors this would require a lot of API calls (a reason why a webhook would be better-suited for recurring/long-term use cases).
1. “I’ve got issues with: GET /org/{organization_pk}/sensors/{deviceName}/events":
“The response doesn’t include the events I want, they all seem to be about battery/connection/seen_device”
Currently we return all events from a sensor from this endpoint. This means we include any battery readings, signal readings and the primary readings you’d expect. The events returned can be identified by the “type” in the response, the options for which are reflected in our docs:
Most types are fairly self-explanatory e.g. air_pressure, desk_occupancy, temperature. One to note is that the “object_present” type is used for door monitoring and the value in this case will give an indication as to the state of the door - these events are triggered when the state changes. “true” indicates that the door is closed and “false” indicates that the door is open.
“I’m only getting back 100 events/I’m trying to alter the number of events I get back using the “page”/”page_size” parameter but it is not working how I expect it to?”
This endpoint uses the “from_time” and “to_time” parameters for pagination. The response will always be returned in reverse chronological order (returning the most recent event first). The “next” url can be used to cycle through all responses.
This endpoint is paginated with the default response returning around 100 events. When I say around 100, this is because the endpoint works in the following way: (by default) it will aim to return 100 events with the condition that any events which occurred at the same time as the 100th event will also be returned. This is to make it clearer when events occur at the same time. As such, the “page_size” specified in the request will not always be the same as the size of the response due to this condition.