Locations

Twins contain location data so you can query the location of another twin, eg if you’re looking for a nearby twin that provides a particular service.


List Location Data of Your Twin

List All Public Location Data

List Twins and Assets in a Specific Location

List the locations of your Trusted Twins

Add static location data to your twin

Update static location data of your twin


§List location data of your twin

To retrieve the location data of your twin, you can query the ‘my/locations’ URL. 

curl --location --request GET '<API_URL>/my/locations/' \ --header 'Content-Type: application/vnd.api+json' \ --header 'X-Organization: <ORG_ID>' \ --header 'X-Twin: <TWIN_ID>' \ --header 'Authorization: Token <ACCESS_TOKEN>'

§List all public location data

To retrieve all public location data, you can query the ‘/locations’ URL. This will return a list of all assets and twins along with their location data.

curl --location --request GET '<API_URL>/locations/' \ --header 'Content-Type: application/vnd.api+json' \ --header 'X-Organization: <ORG_ID>' \ --header 'X-Twin: <TWIN_ID>' \ --header 'Authorization: Token <ACCESS_TOKEN>'

You can filter the results by twins or assets by adding a filter to the URL eg.

/locations?is_twin=True

§List twins and assets in a specific location

To find twins and or assets within a specific radius of a given location, you can query the URL ‘/locations/find_around_me’ and specify the required parameters in the URL. 

curl --location --request GET '<API_URL>/locations/find_around_me/?point=[<LATITUDE>,<LONGITUDE>]&radius=2' \ --header 'Content-Type: application/vnd.api+json' \ --header 'X-Organization: <ORG_ID>' \ --header 'X-Twin: <TWIN_ID>' \ --header 'Authorization: Token <ACCESS_TOKEN>'

In the above example, this will return assets and twins within a 2km radius of the specified geographic location. 

You can filter down further by twins and or assets by adding the following example parameter to the URL:

/locations/find_around_me/?point=[<LATITUDE>,<LONGITUDE>]&radius=2&filter_by=twin

§List the locations of your Trusted Twins

To find the location(s) of your trusted twins, you can query the ‘/connected/locations’ URL as shown in the following example.

curl --location --request GET '<API_URL>/connected/locations' \ --header 'Content-Type: application/vnd.api+json' \ --header 'X-Organization: <ORG_ID>' \ --header 'X-Twin: <TWIN_ID>' \ --header 'Authorization: Token <ACCESS_TOKEN>'

You can filter this further down by twins or assets by adding a search parameter to the URL:

/connected/locations?is_twin=True

§Add static location data to your twin

To add a location to your twin, you can perform a POST request to the /my/locations URL, with the required latitude and longitude points added to the request body. It is important to specify the type with the request body too, as well as specify there is no asset location to update.

The system does not allow you to post more than one location to your twin.

curl --location --request POST '<API_URL>/my/locations/' \ --header 'Content-Type: application/vnd.api+json' \ --header 'X-Organization: <ORG_ID>' \ --header 'X-Twin: <TWIN_ID>' \ --header 'Authorization: Token <ACCESS_TOKEN>' --date-raw '{ "data":{ "type": "locations", "attributes": { "asset": null "point": [ <LATITUDE>, <LONGITUDE> ] } } }'

This will return a response similar to the following:

{ "data": { "type": "locations", "id": "<LOCATION_ID>", "attributes": { "point": { "type": "Point", "coordinates": [   <LATITUDE>, <LONGITUDE> ] }, "created": "2022-07-07T12:15:25.251647Z", "modified": "2022-07-07T12:15:25.251647Z" }, "relationships": { "twin": { "data": { "type": "twins", "id": "<TWIN_ID>" } } } } }

§Update (static) location data of your twin

To update the location of your twin, you can perform a POST request to the /update_location URL, with the new latitude and longitude points added to the request body.

curl --location --request POST '<API_URL>/update_location/' \ --header 'Content-Type: application/vnd.api+json' \ --header 'X-Organization: <ORG_ID>' \ --header 'X-Twin: <TWIN_ID>' \ --header 'Authorization: Token <ACCESS_TOKEN>' --date-raw '{ "data":{ "type": "locations", "attributes": { "point": [ <LATITUDE>, <LONGITUDE> ] } } }'

This will return a response similar to the following:

{ "data": { "status_code": 200, "detail": "Location was updated" } }