Locations Endpoint
Location (sensor hub) metadata with coordinates, assignment, and status.
Endpoints: GET /api/v1/locations, GET /api/v1/locations/{location_id}
Returns location (sensor hub) metadata with coordinates, assignment, and status. Use these when listing active sensors, assigning devices to zones, or building location selectors. For time-series sensor data by location, see the Data Endpoint.
Authentication
Requires authentication via Bearer token (Authorization: Bearer <JWT>) or API key (x-api-key header). API keys are organization-scoped; Bearer tokens use all organizations the user can access.
List Locations
GET /api/v1/locations
Query Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
organization_id | integer | No | Filter by organization. Omit to use all organizations the user can access. Must belong to user's orgs or returns 403. |
skip | integer | No | Records to skip for pagination. Default: 0. |
limit | integer | No | Max records to return (1–10,000). Default: 200. |
status | string | No | Filter by status: active or archived. Default: active. |
Response
Returns an array of objects (not wrapped in a container). Each object includes:
| Field | Type | Description |
|---|---|---|
location_id | string (UUID) | Location identifier. |
device_id | integer | Associated device ID. |
name | string | Location display name. |
application_zone_id | string | null | Assigned zone UUID, if any. |
latitude | number | Latitude (from InfluxDB). |
longitude | number | Longitude (from InfluxDB). |
timezone | string | IANA timezone derived from coordinates. |
organization_id | integer | Organization ID. |
volumetric_water_content_fc | number | null | Field capacity (VWC). |
status | string | active or archived. |
created_at | string | ISO 8601. |
updated_at | string | ISO 8601. |
last_post | string | null | ISO 8601 of last telemetry. |
zone_assigned_at | string | null | ISO 8601 when zone was assigned. |
Returns [] when no locations match.
Get Location by ID
GET /api/v1/locations/{location_id}
Returns a single location by UUID. Returns 404 if not found or outside the user's organization scope.
Path Parameters
| Parameter | Type | Description |
|---|---|---|
location_id | string (UUID) | Location identifier. |