Locations

Latest location and environmental data of tracked assets.

Operations

Request the latest event with location and environmental data

Request

Returns the latest location of the tags on an air waybill (AWB), or the latest location and environmental readings of a device identified by its asset barcode.

Headers. customer_id and authorized_groups (plural) are required; they select the account whose data is returned.

Two modes, chosen by the event query parameter. Send either no event or event=sensor. Other values are not supported; do not send them.

AWB mode (no event). asset_id is the AWB number.

Every active tag on the AWB in your account is considered. For each tag, its latest event is used (activation and end-of-journey events are not counted).
A tag is returned only if that latest event has a position (latitude and longitude), a location and a facility; tags without one are left out. A latitude or longitude of exactly 0 counts as no position.
event_type is cargoiq-<STATUS> when the event carries a Cargo iQ status (for example cargoiq-RCS), otherwise location.
If no tag can be returned, the response is 404 AWB not found.

Sensor mode (event=sensor). asset_id is a device asset barcode.

The latest event (activation and end-of-journey events are not counted) of a device with that asset barcode in your account is returned with six environmental readings, always in this order: ambient_temp, probe_temp, shock, humidity, pressure, light.
A reading the device did not report is returned as 0, not null.
event_type is always environment.
Only the single latest event is considered. If it has no position (latitude and longitude; a value of exactly 0 counts as none), location or facility, nothing is returned, even when older events have one.
When there is nothing to return, the response is 200 with assets: []. Sensor mode never returns 404.

Timestamps. timestamp is the event time as local wall-clock time in the event's time zone, format YYYY-MM-DDTHH:mm:ss, with no offset and no Z. The zone is given in time_zone as an IANA name; it is Etc/UTC when the event's time zone is not known.

Units. °C for ambient_temp and probe_temp, g for shock, % for humidity, Pa for pressure, lx for light.

Error messages (this endpoint returns a message, not an error_code):

Status	`message`	What to do
400	`Missing required headers: customer_id or authorized_groups`	Send both headers (note the plural `authorized_groups`).
404	`AWB not found`	AWB mode only: no active tag on this AWB in your account has a latest event with a position, location and facility. Check the AWB number and headers; a newly labelled AWB has no location until its tags report one.

A temporary server fault while reading the data is reported the same way as no data: 404 AWB not found in AWB mode, 200 with assets: [] in sensor mode. If an asset you expect to have a location returns one of these, retry once with backoff before treating the result as final.

Retries. Read-only; safe to repeat.

Security

bearerAuth

Path

asset_idstringrequired

The AWB number (AWB mode) or the device asset barcode (event=sensor). Matched exactly (case-sensitive).

Examples:

AWB number in AWB mode

00612345675

Asset barcode with event=sensor

PHARMA-0042

Query

eventstring

Omit for AWB mode. Send sensor for asset-barcode mode with environmental readings. No other value is supported.

Value:"sensor"

Example:event=sensor

customer_idstringrequired

Customer ID of the account to read. Required; missing or empty → 400. Matched exactly (case-sensitive).

Example:acme

authorized_groupsstringrequired

Authorized group of the account to read. Required; missing or empty → 400. Note the plural header name: the singular authorized_group is not read here. Matched exactly (case-sensitive).

Example:acme-air

curl --request GET \
  --url 'https://ppe.api.trackonomy.com/external/locations/00612345675?event=sensor' \
  --header 'Authorization: Bearer <access_token>' \
  --header 'customer_id: acme' \
  --header 'authorized_groups: acme-air'

Responses

AWB mode: one entry per returned tag (at least one). Sensor mode: at most one entry, with a sensors array, or an empty assets array.

Bodyapplication/json

Any of:

versionstringrequired

Format version, always 1.0.0.

Value:"1.0.0"

Example:"1.0.0"

uuidstring, (uuid)required

Fixed value, the same on every response (not a request ID).

Value:"a51799fa-4765-4f9c-9460-2d44fc2fe27f"

Example:"a51799fa-4765-4f9c-9460-2d44fc2fe27f"

vendor_idstring, (uuid)required

Trackonomy's vendor ID, the same on every response.

Value:"c59f7130-e0b7-4aff-ac6e-a97dcfbd9222"

Example:"c59f7130-e0b7-4aff-ac6e-a97dcfbd9222"

assetsArray of objects, non-empty(LocationAssetBase)required

One entry per returned tag of the AWB.

Response

GET /external/locations/00612345675. One tag whose latest event carries a Cargo iQ status.

{
  "version": "1.0.0",
  "uuid": "a51799fa-4765-4f9c-9460-2d44fc2fe27f",
  "vendor_id": "c59f7130-e0b7-4aff-ac6e-a97dcfbd9222",
  "assets": [
    { … }
  ]
}