Skip to content
IoT OS

Query current positions and trails

POST
/integration/v1/organizations/{organization}/location-map/query
curl --request POST \
  --url https://api.elwids.xyz/api/integration/v1/organizations/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/location-map/query \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "device_uuids": [ "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0" ], "trail_window": "1h", "include_trails": true, "geofence_uuid": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0" }'

Requires: locations:read

Rate limits: 240 a minute per address, 60 a minute per application

Positions, geofence condition and optional trails (last 1h, 6h, 24h or 7d) of 1 to 100 granted devices. Device entries are the device runtime’s output with four fields added by the control plane. 403 when a requested device is not granted; 422 for invalid input or when the runtime rejects the query (under errors.runtime); 503 when the runtime is unavailable.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
organization
required
string format: uuid

The organization UUID. A value that does not match returns 404.

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json
object
device_uuids
required
Array<string>
>= 1 items <= 100 items unique items
trail_window
required
string
Allowed values: 1h 6h 24h 7d
include_trails
required
boolean
geofence_uuid
string | null format: uuid

Responses

Section titled “Responses”

200

Section titled “200”

location-map.v1. Entries in data.devices are runtime-shaped.

Media typeapplication/json
object
data
required

location-map.v1: positions and trails of the requested devices.

object
schema_version
required
Allowed value: location-map.v1
trail_window
required
string
Allowed values: 1h 6h 24h 7d
geofence
required
Any of:
object
uuid
required
string format: uuid
name
required
string
geometry
required

A GeoJSON Polygon with one ring of 4 to 257 positions.

object
type
required
Allowed value: Polygon
coordinates
required
Array<Array<array>>
>= 1 items <= 1 items
revision
required
integer
>= 1
devices
required

One entry per requested device that has a location binding.

Array<object>

The device runtime’s map entry, passed through unchanged, plus wandering, active_alert, assignment_status and deployment_status added by the control plane.

object
device_uuid
required
string format: uuid
device_name
required
string
binding_uuid
required
string format: uuid
latest
required
Any of:
object
schema_version
required
Allowed value: location-fix.v1
binding_uuid
required
string format: uuid
binding_revision
required
integer
>= 1
event_id
required
string format: uuid
organization_uuid
required
string format: uuid
device_uuid
required
string format: uuid
configuration_uuid
required
string format: uuid
generation
required
integer
>= 1
evaluated_at
required
string format: date-time
observed_at
required
Any of:
string format: date-time
received_at
required
Any of:
string format: date-time
timestamp_source
required
Allowed values: source receipt corrected_future derived unknown
historical
required
boolean
status
required
Allowed values: valid unknown
reason
required
Allowed values: scope_mismatch ambiguous_parameters incomplete_fix incoherent_fix invalid_quality invalid_coordinates invalid_units invalid_time future_time untrusted_time incoherent_accuracy invalid_accuracy accuracy_required historical stale_fix eligible
live_eligible
required
boolean
point
required
Any of:
object
latitude
required
number
>= -90 <= 90
longitude
required
number
>= -180 <= 180
accuracy_metres
required
number | null
condition
required

unknown unless the latest fix is live-eligible.

string
Allowed values: inside outside unknown
active
required

Whether the geofence rule’s condition is active.

boolean
geometry
required
Any of:

A GeoJSON Polygon with one ring of 4 to 257 positions.

object
type
required
Allowed value: Polygon
coordinates
required
Array<Array<array>>
>= 1 items <= 1 items
trail
required
object
segments
required

Runs of valid fixes; a gap longer than twice the binding’s max_age_seconds starts a new segment. Empty unless trails were requested.

Array<Array<object>>
sampled
required

Whether the trail was thinned to at most 200 points.

boolean
wandering
required

Whether the device’s geofence workflow has an active alert.

boolean
active_alert
required
Any of:
object
uuid
required
string format: uuid
activated_at
required
string | null format: date-time
assignment_status
required

The geofence assignment’s status, or null when the device has no assignment.

string | null
deployment_status
required

The assignment workflow’s deployment status, or null.

string | null

Example 

{
  "data": {
    "schema_version": "location-map.v1",
    "trail_window": "24h",
    "geofence": null,
    "devices": [
      {
        "device_uuid": "00000000-0000-4000-8000-000000000003",
        "device_name": "Herd tracker 17",
        "binding_uuid": "00000000-0000-4000-8000-000000000001",
        "latest": null,
        "condition": "unknown",
        "active": false,
        "geometry": null,
        "trail": {
          "segments": [],
          "sampled": false
        },
        "wandering": false,
        "active_alert": null,
        "assignment_status": "active",
        "deployment_status": "active"
      }
    ]
  }
}

Headers

Section titled “Headers”
Cache-Control
required
string
/(^|[ ,])no-store([ ,]|$)/

Responses to authenticated integration requests are never cached. The header also carries private.

Example 
no-store, private

401

Section titled “401”

No valid credentials: no session (first-party API), or a missing, invalid, expired or revoked application token (integration API).

Media typeapplication/json

The body of most error responses.

object
message
required
string

Example generated

{
  "message": "example"
}

403

Section titled “403”

The caller is not allowed: not a member of the organization, missing a tenant or platform permission, or (integration API) an ability not granted on both the application and the token.

Media typeapplication/json

The body of most error responses.

object
message
required
string

Example generated

{
  "message": "example"
}

404

Section titled “404”

Not found: an unknown organization or resource, a resource in another organization or not granted to the application, or a malformed identifier (the route does not match).

Media typeapplication/json

The body of most error responses.

object
message
required
string

Example generated

{
  "message": "example"
}

422

Section titled “422”

The input failed validation.

Media typeapplication/json

422 for input that failed validation.

object
message
required

The first error, followed by a count of the others.

string
errors
required

Messages per field, keyed by the field’s dotted path. A rejection by the device runtime appears under runtime.

object
runtime
Array<string>
key
additional properties
Array<string>

Example generated

{
  "message": "example",
  "errors": {
    "runtime": [
      "example"
    ]
  }
}

429

Section titled “429”

A rate limit was reached; see x-rate-limits on the operation.

Media typeapplication/json

The body of most error responses.

object
message
required
string

Example generated

{
  "message": "example"
}

Headers

Section titled “Headers”
Retry-After
required
integer

Seconds to wait before retrying.

503

Section titled “503”

The device runtime is not configured, unavailable, or could not complete the request.

Media typeapplication/json

The body of most error responses.

object
message
required
string

Example generated

{
  "message": "example"
}

Report a problem with this page