Data Endpoints
Application Zones Data Endpoint
Aggregated irrigation, ET, satellite ET, and vegetation indices by application zone.
Endpoint: GET /api/v1/data/application_zones/
Returns time-series data (aggregated irrigation, ET, satellite ET, vegetation indices) for application zones. For zone metadata (list zones, zone detail), see the Application Zones Asset Endpoint. Data is joined from PostgreSQL (zone metadata), InfluxDB (irrigation runtime, sensor ET), ML models (satellite ET), and remote sensing (NDRE/NDVI).
Authentication
Requires authentication via Bearer token (Authorization: Bearer <JWT>) or API key (x-api-key header). Results are scoped to organizations the identity can access.
Query Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
location_ids | string[] | No* | Filter by location UUIDs (comma-separated or repeated). Each must belong to the resolved org scope; otherwise returns 403. *At least one of location_ids or application_zone_ids required. |
application_zone_ids | string[] | No* | Filter by application zone UUIDs. Each must belong to the resolved org scope; otherwise returns 403. *At least one of location_ids or application_zone_ids required. |
organization_id | integer | No | Organization ID to scope results. Omit to use all organizations the user can access. If provided, must be an org the user belongs to; otherwise returns 403. |
start | datetime | No | Start time (ISO 8601 with timezone, e.g. 2024-01-01T00:00:00+13:00). |
stop | datetime | No | Stop time (ISO 8601 with timezone). |
aggregation | string | Yes | Aggregation function: sum or mean. |
aggregation_period | string | Yes | Period: 1h, 1d, 24h, 7d, 1w, 30d, 1m. |
fields | string[] | No | Fields to include: et, satellite_et, openet_et, irrigation_duration, irrigation_applied, ndre, ndvi, precip. Omit to include all supported fields. |
timezone | string | No* | IANA timezone. *Required when requesting irrigation_applied, irrigation_duration, ndre, ndvi, or precip. |
skip | integer | No | Number of records to skip for pagination. Default: 0. |
limit | integer | No | Maximum number of records to return (1–10,000). Default: 1000. |
Org-Scoped Access & Errors
organization_idomitted: Uses all organizations the user can access.organization_idprovided: Limits results to that org. Returns 403 if the user lacks access.location_ids/application_zone_ids: Each requested ID must belong to the resolved org scope. Returns 403 with"Access denied for one or more locations"or"Access denied for one or more application zones"if any are outside scope.
The same /data* concurrency, per-minute, timeout, and max-location limits as GET /api/v1/data/ apply (429 / 400 / 504).
Response Fields
Response is an array of objects. Fields vary by aggregation_period (hourly, daily, weekly, monthly).
Metadata (always present)
| Field | Type | Description |
|---|---|---|
application_zone_id | string (UUID) | Application zone identifier. |
application_zone_name | string | Name of the application zone. |
location_id | string (UUID) | Location (sensor) identifier. |
location_name | string | null | Human-readable location name. |
assignment_start | string (ISO 8601) | null | Start of the location's irrigation tenure (location created_at). Not the later zone-assignment timestamp. Present for irrigation queries. |
assignment_end | string (ISO 8601) | null | End of the location's irrigation tenure (archive or device unassignment); null while the location is still active. Present for irrigation queries. |
pump_station_name | string | null | Pump station linked to the zone. |
planting_name | string | null | Linked planting name. Null when the zone was created on its own. |
acreage | number | null | Zone acreage. |
variety_name | string | null | Crop variety name. |
irrigator_name | string | null | Assigned irrigator. |
start_time | string (ISO 8601) | Start of the aggregation window. |
end_time | string (ISO 8601) | End of the aggregation window. |
aggregation | string | Aggregation function used. |
aggregation_period | string | Aggregation period used. |
timezone | string | Timezone used. |
Irrigation
| Field | Type | Unit | Description | Availability |
|---|---|---|---|---|
application_rate | number | null | mm/hr | The zone's application rate at the window start (application_rate_mm_per_hr). | Present when the zone has a rate. |
telemetry_status | observed | carried_forward | missing | — | Whether the bucket contains an ON/OFF event, uses a known prior state, or has no known irrigation state. | Irrigation queries. |
irrigation_duration | number | null | hours | Hours irrigation was on in the window. | 1h, 1d, 7d, 1m; request via fields=irrigation_duration. Requires timezone. |
irrigation_applied | number | null | mm | Irrigation depth applied. Computed as irrigation_duration × application_rate. | Same as irrigation_duration. Request via fields=irrigation_applied. Versioned by zone history. |
Irrigation rows are emitted only for buckets that overlap the location's irrigation tenure (created_at through archive or unassignment). A known OFF state returns 0; missing irrigation telemetry returns null.
Precipitation
| Field | Type | Unit | Description | Availability |
|---|---|---|---|---|
precip | number | null | mm | Precipitation from the closest weather station within 15 km of the zone centroid. | Daily, weekly, monthly only (not hourly). Request via fields=precip. Requires timezone. |
Evapotranspiration
| Field | Type | Unit | Description | Availability |
|---|---|---|---|---|
et | number | null | mm | Direct (sensor) evapotranspiration from group0_et. | All periods. Request via fields=et. |
satellite_et | number | null | mm | Satellite-derived ET from internal ML model. | Daily, weekly, monthly only (not hourly). Request via fields=satellite_et. |
openet_et | number | null | mm | Evapotranspiration from OpenET (open-source satellite ET ensemble). | Daily, weekly, monthly only (not hourly). Request via fields=openet_et. Requires timezone. |
Vegetation Indices
| Field | Type | Unit | Description | Availability |
|---|---|---|---|---|
ndre | number | null | — | Normalized Difference Red Edge. Interpolated from remote sensing via GDD. | Daily, weekly, monthly only. Request via fields=ndre. Requires timezone. |
ndvi | number | null | — | Normalized Difference Vegetation Index. Interpolated via GDD. | Same as ndre. Request via fields=ndvi. |
Aggregation Behavior
| Period | Window | Notes |
|---|---|---|
1h | Hourly | Each row = one hour. |
1d, 24h | Daily | Each row = calendar day in local timezone. |
7d, 1w | Weekly | 7-day windows from start date. |
30d, 1m | Monthly | Calendar months. start and stop must be 1st of month (e.g. 2025-11-01, 2025-12-01). |
Response Shape & Pagination
- Returns an array of objects (paginated via
skipandlimit).
Constraints
- Precipitation: Sourced from the closest weather station within 15 km of each zone centroid. If no station is within 15 km,
precipis null for that zone. - Satellite ET / OpenET ET: Not available for hourly aggregation.
- NDRE/NDVI: Daily measurements; only supported for daily, weekly, or monthly aggregation.
- Timezone: Required when requesting irrigation or vegetation index fields.
- Monthly: Start date must be 1st of month; stop date must be 1st of next month.