The HydroFlux API
Send a field boundary and a date. Get a 30 m evapotranspiration map where every pixel carries uncertainty, observation age, support status and the reasons behind them.
Base path: /api/v1/hydroflux
Your assigned API host and credentials are provided securely during onboarding.
Quickstart
One call returns a daily field map. No satellite infrastructure to run on your side.
curl -X POST "$HYDROFLUX_API_BASE_URL/api/v1/hydroflux/daily-field-et" \
-H "X-HydroFlux-API-Key: hf1.${KEY_ID}.${KEY_SECRET}" \
-H "Content-Type: application/json" \
-d '{
"field_id": "north-pivot-12",
"target_date": "2026-07-22",
"geometry": { "type": "Polygon", "coordinates": [[[-100.24,40.10],[-100.23,40.10],[-100.23,40.11],[-100.24,40.11],[-100.24,40.10]]] },
"crop_type": "corn",
"is_irrigated": true
}'Replace the geometry with your own closed WGS84 polygon ring — one management unit per request.
Authentication
Access is scoped to the organization approved during onboarding.
X-HydroFlux-API-Key
Developer integrations use an API key issued for the approved organization and environment.
hf1.<key_id>.<secret>Treat API keys as secrets. Never place them in browser code, public repositories or support forms; call HydroFlux from a server-side environment.
Reading the response
et_mm_day is nullable by contract. Respect estimate_status and never replace an abstention with a candidate from diagnostics.
{
"target_date": "2026-07-22",
"temporal_status": "PROVISIONAL",
"model": { "name": "HydroFlux", "version": "<assigned-model-version>" },
"spatial_contract": { "grid_m": 30, "coverage_status": "COMPLETE" },
"paging": { "has_more": false, "next_pixel_offset": null },
"pixels": [
{
"lat": 40.1032,
"lon": -100.2411,
"et_mm_day": 4.21,
"estimate_status": "ESTIMATED",
"uncertainty": { "lower": 3.83, "upper": 4.59 },
"support_status": "SUPPORTED",
"observation": { "last_clear_date": "2026-07-19", "age_days": 3 },
"reasons": ["recent_clear_observation", "crop_group_resolved"],
"context_provenance": {
"era5_land": "coarse_grid_sample_at_field_centroid"
}
},
{
"lat": 40.1032,
"lon": -100.2408,
"et_mm_day": null,
"estimate_status": "ABSTAINED",
"support_status": "UNSUPPORTED",
"observation": { "last_clear_date": "2026-06-14", "age_days": 38 },
"reasons": ["clear_observation_older_than_32_days"]
}
]
}Truncated for readability. coverage_status is COMPLETE or TRUNCATED — a TRUNCATED page must never be displayed as full-field coverage.
Synchronous calls and asynchronous jobs
Synchronous pages cap at 4,500 returned pixels. Larger or operational workloads use idempotent jobs with immutable result revisions.
# Set HYDROFLUX_API_BASE_URL to the host assigned during onboarding.
# 1. submit — the idempotency key makes retries safe
curl -X POST "$HYDROFLUX_API_BASE_URL/api/v1/hydroflux/daily-field-et/jobs" \
-H "X-HydroFlux-API-Key: hf1.${KEY_ID}.${KEY_SECRET}" \
-H "Idempotency-Key: north-pivot-12:2026-07-22:v1" \
-H "Content-Type: application/json" \
-d @request.json
# 2. poll the job
curl "$HYDROFLUX_API_BASE_URL/api/v1/hydroflux/daily-field-et/jobs/${JOB_ID}" \
-H "X-HydroFlux-API-Key: hf1.${KEY_ID}.${KEY_SECRET}"
# 3. read an immutable stored revision
curl "$HYDROFLUX_API_BASE_URL/api/v1/hydroflux/daily-field-et/results/north-pivot-12/2026-07-22?revision=2" \
-H "X-HydroFlux-API-Key: hf1.${KEY_ID}.${KEY_SECRET}"The same idempotency key with different bytes is rejected; the same key and bytes return the existing job.
Endpoint reference
All paths are relative to /api/v1/hydroflux. Preview availability and limits are confirmed during onboarding.