Some resource types include the concept of location, including Thngs and actions. The location of these resources can be used to give an indication of where they were created or updated, or their current/last known position. For example, if a pallet is being tracked through a supply chain, its location could be updated each time it is scanned by a transport company member at each stop along the way, creating a picture of its unique journey useful to both the brand and the consumer.
If a location was specified with provided coordinates (see below for request examples), those will be used. If not, an automatic lookup from the request's IP address will be used to find approximate location instead. Accuracy of a guessed location will vary depending on the apparent IP and location of the request seen by the EVRYTHNG API.
All instances of a location follow the GeoJSON specification, specifically the Point data type, which expresses a single point on the world map with a pair of longitude, then latitude coordinates.
Coordinate Order
When specifying
coordinatesin the EVRYTHNG API, make sure the ordering is longitude, then latitude. For example, Hammersmith in London would be[-0.223391, 51.493209].
API Status
General Availability:
/thngs/:thngId/location
LocationDocument Data Model
See also: ScopesDocument
Filterable Fields
This resource type can be filtered using the following fields and operators.
Read a Thng's Location History
To access all the location updates for a thng, send a GET to the /location endpoint of the Thng.
Update a Thng's Location
Just like properties, the location of a Thng can be updated at any time via the /location endpoint of the Thng. The payload must always be an array of LocationDocument objects, which allows you to send several locations (with different timestamps each) in a single request.
This is useful when a device wants to update a path cached over a certain period of time at once. An example would be a GPS tracker on a shipping container that updates the whole set of locations it has been through once per hour, or when it is in range of a network instead of sending each GPS sensor reading individually.
Note: instead of specifying the location itself, it is also possible to specify a place to set the Thng's location.
Delete a Thng's Location History
Similar to properties, location updates are not individually identified, therefore the only way to delete them is by specifying a point in time before which all the updates will be deleted as a query param: ?to=Timestamp.
Important
If the
?toparameter is not specified, ALL location updates will be deleted for the Thng specified.
Set an Action's Location
When creating an action, specify the location property as a valid LocationDocument to set the action's location. If you are supplying the coordinates, make sure to also specify locationSource as sensor, or geoIP will be used instead.
An example is shown below: