Appearance
Geolocation
Where a device is, derived from its radio rather than from GPS. The backend watches the serving-cell properties of the device service — the only service it reads — and keeps one entry per device, alongside a table of cell positions shared by every tenant. No position is fed in here: entries are written by the backend, and this API only reads them or drops them.
Reports arrive as OBJECT_UPDATED from flake, and each stored position goes out as GEOLOCATION_DEVICE_UPDATE over the websocket. The four cell values may arrive in separate messages, so an entry can hold a cell that is not yet complete — and then no position either.
| GET | List located devices/api/v1/geolocation/devices |
| DELETE | Clear all device locations/api/v1/geolocation/devices |
| GET | Read a device's location/api/v1/geolocation/devices/:deviceId |
| DELETE | Delete a device's location/api/v1/geolocation/devices/:deviceId |
| GET | List cached cell towers/api/v1/geolocation/cache |
| DELETE | Clear the cell cache/api/v1/geolocation/cache |
List located devices
Lists every readable device that has a stored location — a device appears with its first cell report. depth=1 adds the location entry; at depth=0 an item is just the device CRN and its IMEI.
GET
/api/v1/geolocation/devices?depth=0Query Parameters
| Name | Description |
|---|---|
depthintegeroptional | How many levels of nested resources the response includes; 0 returns only the top level. Default: 0min 0 |
Response
| Name | Description |
|---|---|
crnstring | Unique Coldwave resource name (CRN) that identifies a resource |
imeistring | The device's IMEI, the 15-digit identity of its modem. |
geolocationobjectoptionaldepth ≥ 1 | Last known cell and position of the device; included at depth ≥ 1. |
resourceIdentifierstring | Unique Coldwave resource name (CRN) that identifies a resource |
cellobject | The serving cell as the device has reported it so far; the four values may arrive in separate messages, and only a complete cell is looked up. |
cellIdintegeroptional | The LTE cell identity of the serving cell, as the modem reports it. > 0 |
mobileCountryCodeintegeroptional | Mobile country code of the network the device is registered to. > 0 |
mobileNetworkCodeintegeroptional | Mobile network code inside that country; 0 is a real network here, whereas 0 in the other three values means a modem that is still registering. min 0 |
locationAreaCodeintegeroptional | Location area code of the cell — on LTE the tracking area code (TAC). > 0 |
locationobjectoptional | Position of the reported cell; null while the cell is incomplete, and when the lookup cannot place it. |
latnumber | Latitude in decimal degrees. |
lngnumber | Longitude in decimal degrees. |
accuracynumber | Radius in metres around the point within which the device is expected. |
updatedAtinteger | When the entry last changed, UTC epoch milliseconds — a repeat of the same, already placed cell leaves it untouched, so it is not a last-seen timestamp. |
Errors
| Status | Description | Body |
|---|---|---|
403 | You do not have permission to perform this action | |
400 | The request did not match the schema for this endpoint. The details field carries the specific failures. | error: Validation Error |
401 | No valid access token was presented, or the DPoP proof accompanying it was missing, expired or bound to a different key. | error: string |
500 | The request failed for a reason that is not the caller's to fix. Safe to retry. | error: string, message: string, statusCode: 50 |
Clear all device locations
Drops the stored cell and position of every device in the tenant the caller may delete; the devices themselves and the shared cell cache stay untouched. Each device is placed again on its next cell report.
DELETE
/api/v1/geolocation/devicesErrors
| Status | Description | Body |
|---|---|---|
403 | You do not have permission to perform this action | |
401 | No valid access token was presented, or the DPoP proof accompanying it was missing, expired or bound to a different key. | error: string |
500 | The request failed for a reason that is not the caller's to fix. Safe to retry. | error: string, message: string, statusCode: 50 |
Read a device's location
The last serving cell the device reported and the position derived from it; {deviceId} accepts the device id or the IMEI. location is null while the cell is incomplete or could not be placed.
GET
/api/v1/geolocation/devices/Yk3pL7rWq2Path Parameters
| Name | Description |
|---|---|
| deviceId | The device id, or its IMEI. |
Alternative 1string | Resource id: Base58 (9–10 characters) or a 16-character Crockford snowflake. Not an RFC 4122 UUID. Pattern: ^[0-9A-HJ-NP-Za-km-z]{9,16}$ |
Alternative 2string | The device id, or its IMEI. max length 16 Pattern: ^[0-9a-fA-F]+$ |
Response
| Name | Description |
|---|---|
resourceIdentifierstring | Unique Coldwave resource name (CRN) that identifies a resource |
cellobject | The serving cell as the device has reported it so far; the four values may arrive in separate messages, and only a complete cell is looked up. |
cellIdintegeroptional | The LTE cell identity of the serving cell, as the modem reports it. > 0 |
mobileCountryCodeintegeroptional | Mobile country code of the network the device is registered to. > 0 |
mobileNetworkCodeintegeroptional | Mobile network code inside that country; 0 is a real network here, whereas 0 in the other three values means a modem that is still registering. min 0 |
locationAreaCodeintegeroptional | Location area code of the cell — on LTE the tracking area code (TAC). > 0 |
locationobjectoptional | Position of the reported cell; null while the cell is incomplete, and when the lookup cannot place it. |
latnumber | Latitude in decimal degrees. |
lngnumber | Longitude in decimal degrees. |
accuracynumber | Radius in metres around the point within which the device is expected. |
updatedAtinteger | When the entry last changed, UTC epoch milliseconds — a repeat of the same, already placed cell leaves it untouched, so it is not a last-seen timestamp. |
Errors
| Status | Description | Body |
|---|---|---|
403 | You do not have permission to perform this action | |
404 | No location is stored under this identifier — it names no device of this tenant, or the device has not reported a serving cell yet. Check the device id or IMEI; an entry only appears with the first cell report. | |
400 | The request did not match the schema for this endpoint. The details field carries the specific failures. | error: Validation Error |
401 | No valid access token was presented, or the DPoP proof accompanying it was missing, expired or bound to a different key. | error: string |
500 | The request failed for a reason that is not the caller's to fix. Safe to retry. | error: string, message: string, statusCode: 50 |
Delete a device's location
Removes one device's stored cell and position; a device that has none answers 404. The next cell report places it again — normally without a fresh lookup, since the cell itself stays cached.
DELETE
/api/v1/geolocation/devices/Yk3pL7rWq2Path Parameters
| Name | Description |
|---|---|
| deviceId | The device id, or its IMEI. |
Alternative 1string | Resource id: Base58 (9–10 characters) or a 16-character Crockford snowflake. Not an RFC 4122 UUID. Pattern: ^[0-9A-HJ-NP-Za-km-z]{9,16}$ |
Alternative 2string | The device id, or its IMEI. max length 16 Pattern: ^[0-9a-fA-F]+$ |
Errors
| Status | Description | Body |
|---|---|---|
403 | You do not have permission to perform this action | |
404 | No location is stored under this identifier — it names no device of this tenant, or the device has not reported a serving cell yet. Check the device id or IMEI; an entry only appears with the first cell report. | |
400 | The request did not match the schema for this endpoint. The details field carries the specific failures. | error: Validation Error |
401 | No valid access token was presented, or the DPoP proof accompanying it was missing, expired or bound to a different key. | error: string |
500 | The request failed for a reason that is not the caller's to fix. Safe to retry. | error: string, message: string, statusCode: 50 |
List cached cell towers
The lookup table of cell towers resolved so far, shared by every tenant; an entry with location: null records a cell that could not be placed. It is held in the root tenant, so tenant-scoped access never reaches it.
GET
/api/v1/geolocation/cacheResponse
| Name | Description |
|---|---|
resourceIdentifierstring | Unique Coldwave resource name (CRN) that identifies a resource |
cellobject | The four values that identify the cell tower; joined as mcc-mnc-lac-cellId they form the key this entry is cached under. |
cellIdinteger | The LTE cell identity of the serving cell, as the modem reports it. > 0 |
mobileCountryCodeinteger | Mobile country code of the network the device is registered to. > 0 |
mobileNetworkCodeinteger | Mobile network code inside that country; 0 is a real network here, whereas 0 in the other three values means a modem that is still registering. min 0 |
locationAreaCodeinteger | Location area code of the cell — on LTE the tracking area code (TAC). > 0 |
locationobjectoptional | Where the cell was placed; null records that it could not be placed, so the same miss is not looked up again until the entry goes stale. |
latnumber | Latitude in decimal degrees. |
lngnumber | Longitude in decimal degrees. |
accuracynumber | Radius in metres around the point within which the device is expected. |
recordedAtinteger | When the answer was fetched, UTC epoch milliseconds; the entry is used until it is older than cacheDuration, or than negativeCacheDuration when no position was found. |
Errors
| Status | Description | Body |
|---|---|---|
403 | You do not have permission to perform this action | |
401 | No valid access token was presented, or the DPoP proof accompanying it was missing, expired or bound to a different key. | error: string |
500 | The request failed for a reason that is not the caller's to fix. Safe to retry. | error: string, message: string, statusCode: 50 |
Clear the cell cache
Empties the shared cell table, so the next report of each cell costs a fresh external lookup; stored device positions are left as they are. Requires root-tenant access, like reading the table.
DELETE
/api/v1/geolocation/cacheErrors
| Status | Description | Body |
|---|---|---|
403 | You do not have permission to perform this action | |
401 | No valid access token was presented, or the DPoP proof accompanying it was missing, expired or bound to a different key. | error: string |
500 | The request failed for a reason that is not the caller's to fix. Safe to retry. | error: string, message: string, statusCode: 50 |
Events
Published on the tenant's event stream and delivered over the websocket to every subscriber holding read on the resource the message names. resourceIdentifier is the resource the action changed; the payload is the shape below.
| Event | Description |
|---|---|
GEOLOCATION_CELL_DELETE | An entry left the shared cell cache; the next device reporting that cell triggers a fresh lookup. |
GEOLOCATION_CELL_SET | A cell tower was looked up and the answer stored for every device in that cell — including the answer that it cannot be placed, kept as location: null. |
GEOLOCATION_DEVICE_DELETE | A device's stored cell and position were dropped over the API; deleting the device itself removes the entry too, but without this event. |
GEOLOCATION_DEVICE_UPDATE | A device reported serving-cell properties on its device service. The payload carries the cell merged from every report so far and the position derived from it; an incomplete cell keeps the previous position. |
Cached cell dropped
An entry left the shared cell cache; the next device reporting that cell triggers a fresh lookup.
EVENT
GEOLOCATION_CELL_DELETEPayload
| Name | Description |
|---|
Cell position cached
A cell tower was looked up and the answer stored for every device in that cell — including the answer that it cannot be placed, kept as location: null.
EVENT
GEOLOCATION_CELL_SETPayload
| Name | Description |
|---|---|
resourceIdentifierstring | Unique Coldwave resource name (CRN) that identifies a resource |
cellobject | The four values that identify the cell tower; joined as mcc-mnc-lac-cellId they form the key this entry is cached under. |
cellIdinteger | The LTE cell identity of the serving cell, as the modem reports it. > 0 |
mobileCountryCodeinteger | Mobile country code of the network the device is registered to. > 0 |
mobileNetworkCodeinteger | Mobile network code inside that country; 0 is a real network here, whereas 0 in the other three values means a modem that is still registering. min 0 |
locationAreaCodeinteger | Location area code of the cell — on LTE the tracking area code (TAC). > 0 |
locationobjectoptional | Where the cell was placed; null records that it could not be placed, so the same miss is not looked up again until the entry goes stale. |
latnumber | Latitude in decimal degrees. |
lngnumber | Longitude in decimal degrees. |
accuracynumber | Radius in metres around the point within which the device is expected. |
recordedAtinteger | When the answer was fetched, UTC epoch milliseconds; the entry is used until it is older than cacheDuration, or than negativeCacheDuration when no position was found. |
Device location deleted
A device's stored cell and position were dropped over the API; deleting the device itself removes the entry too, but without this event.
EVENT
GEOLOCATION_DEVICE_DELETEPayload
| Name | Description |
|---|
Device location updated
A device reported serving-cell properties on its device service. The payload carries the cell merged from every report so far and the position derived from it; an incomplete cell keeps the previous position.
EVENT
GEOLOCATION_DEVICE_UPDATEPayload
| Name | Description |
|---|---|
resourceIdentifierstring | Unique Coldwave resource name (CRN) that identifies a resource |
cellobject | The serving cell as the device has reported it so far; the four values may arrive in separate messages, and only a complete cell is looked up. |
cellIdintegeroptional | The LTE cell identity of the serving cell, as the modem reports it. > 0 |
mobileCountryCodeintegeroptional | Mobile country code of the network the device is registered to. > 0 |
mobileNetworkCodeintegeroptional | Mobile network code inside that country; 0 is a real network here, whereas 0 in the other three values means a modem that is still registering. min 0 |
locationAreaCodeintegeroptional | Location area code of the cell — on LTE the tracking area code (TAC). > 0 |
locationobjectoptional | Position of the reported cell; null while the cell is incomplete, and when the lookup cannot place it. |
latnumber | Latitude in decimal degrees. |
lngnumber | Longitude in decimal degrees. |
accuracynumber | Radius in metres around the point within which the device is expected. |
updatedAtinteger | When the entry last changed, UTC epoch milliseconds — a repeat of the same, already placed cell leaves it untouched, so it is not a last-seen timestamp. |