# Request the latest event with location and environmental data

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.

Endpoint: GET /external/locations/{asset_id}
Version: 2.2
Security: bearerAuth

## Security:

  - `bearerAuth` (unknown)
    http bearer JWT

## Path parameters:

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

## Query parameters:

  - `event` (string)
    Omit for AWB mode. Send `sensor` for asset-barcode mode with environmental readings. No other value is supported.

## Header parameters:

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

  - `authorized_groups` (string, required)
    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).

## Response 200:

  - `200` (unknown)
    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.

## Response 200 fields (application/json):

  - `version` (string, required)
    Format version, always `1.0.0`.
    Enum: "1.0.0"

  - `uuid` (string, required)
    Fixed value, the same on every response (not a request ID).
    Enum: "a51799fa-4765-4f9c-9460-2d44fc2fe27f"

  - `vendor_id` (string, required)
    Trackonomy's vendor ID, the same on every response.
    Enum: "c59f7130-e0b7-4aff-ac6e-a97dcfbd9222"

  - `assets` (array, required)
    One entry per returned tag of the AWB.

  - `assets.trk_asset_id` (string)
    The asset barcode of the tag or device. In AWB mode it is absent when the tag has no asset barcode.
    Example: ULD-AKE12345DL

  - `assets.vendor_asset_id` (string)
    The tag's or device's QR code.
    Example: TRK4A7C19E2

  - `assets.event_type` (string, required)
    AWB mode — `cargoiq-<STATUS>` when the event carries a Cargo iQ status (e.g. `RCS`, `DLV`), otherwise `location`. Sensor mode — always `environment`.
    Example: cargoiq-RCS

  - `assets.timestamp` (string, required)
    Event time as local wall-clock time in `time_zone`, format `YYYY-MM-DDTHH:mm:ss`, no offset and no `Z`.
    Example: 2026-09-21T09:13:20

  - `assets.time_zone` (string, required)
    IANA time zone of `timestamp`; `Etc/UTC` when the event's time zone is not known.
    Example: America/Chicago

  - `assets.lat` (number, required)
    Latitude of the event.
    Example: 41.97

  - `assets.lon` (number, required)
    Longitude of the event.
    Example: -87.9

  - `assets.location_detailed` (string, required)
    Name of the event's location or milestone.
    Example: Cargo Terminal 2

  - `assets.location` (string, required)
    The event's facility.
    Example: ORD

  - `assets` (array)

  - `assets.sensors` (array, required)
    Always six readings, in the order ambient_temp, probe_temp, shock, humidity, pressure, light.

  - `assets.sensors.type` (string, required)
    Enum: "ambient_temp", "probe_temp", "shock", "humidity", "pressure", "light"

  - `assets.sensors.data` (number, required)
    Reading value, in `units`. `0` when not reported.
    Example: 4.5

  - `assets.sensors.units` (string, required)
    `°C` for ambient_temp and probe_temp, `g` for shock, `%` for humidity, `Pa` for pressure, `lx` for light.
    Enum: "°C", "g", "%", "Pa", "lx"

## Response 400:

  - `400` (unknown)
    The `customer_id` or `authorized_groups` header is missing or empty (both modes).

## Response 400 fields (application/json):

  - `message` (string, required)
    What went wrong.
    Example: Missing required headers: customer_id or authorized_groups

  - `code` (integer)
    The HTTP status code.
    Example: 400

## Response 401:

  - `401` (unknown)
    The access token is missing, expired, issued for another environment's audience, or your API
identity isn't granted this action. The same response is returned when the request body isn't
valid JSON or is larger than 50 MB. Check the body, request a new token and retry once; if it
still fails, contact your Trackonomy integration contact.

## Response 401 fields (application/json):

  - `message` (string, required)
    What went wrong.
    Example: Missing required headers: customer_id or authorized_groups

  - `code` (integer)
    The HTTP status code.
    Example: 400

## Response 404:

  - `404` (unknown)
    AWB mode only. No active tag on this AWB in your account has a latest event with a position, location and facility.

## Response 404 fields (application/json):

  - `message` (string, required)
    What went wrong.
    Example: Missing required headers: customer_id or authorized_groups

  - `code` (integer)
    The HTTP status code.
    Example: 400

## Response 200 examples:

  - `AWB mode, all fields` (unknown)
    `GET /external/locations/00612345675`. One tag whose latest event carries a Cargo iQ status.

  - `AWB mode, two tags` (unknown)
    The second tag's event has no Cargo iQ status and no known time zone.

  - `Sensor mode, all readings present` (unknown)
    `GET /external/locations/PHARMA-0042?event=sensor`.

  - `Sensor mode, no readings reported and time zone unknown` (unknown)
    Readings the device did not report are 0; the timestamp is in `Etc/UTC`.

  - `Sensor mode, nothing to return` (unknown)