Mireye

/api-reference/fetch

POST /v1/fetch

cURL

curl --request POST \
  --url https://api.example.com/v1/fetch \
  --header 'Content-Type: application/json' \
  --data '
{
  "fields": [
    "<string>"
  ],
  "lat": 123,
  "lng": 123,
  "address": "<string>"
}
'

Deterministic per-field data fetch with full provenance.

cURL

curl --request POST \
  --url https://api.example.com/v1/fetch \
  --header 'Content-Type: application/json' \
  --data '
{
  "fields": [
    "<string>"
  ],
  "lat": 123,
  "lng": 123,
  "address": "<string>"
}
'

​ When to use this

  • The caller knows exactly which fields they need.
  • The workflow is deterministic and you don’t want LLM latency or variability on every call.
  • You are powering a downstream model that needs raw structured values rather than synthesized prose.
  • You want a preset bundle (e.g., everything needed for flood underwriting) in one round trip.

​ Request shape

​ Fetching by address

curl -s https://api.mireye.com/v1/fetch \
  -H "Authorization: Bearer $MIREYE_API_TOKEN" \
  -H 'content-type: application/json' \
  -d '{"address": "350 5th Ave, New York, NY 10118", "fields": ["elevation"]}' | jq

​ Presets

{
  "terrain": [
    "elevation",
    "slope_degrees",
    "aspect_cardinal",
    "coast_distance_m",
    "soil_drainage_class",
    "bedrock_depth_cm"
  ],
  "flood_risk": [
    "elevation",
    "coast_distance_m",
    "within_floodplain_polygon",
    "intersects_nhd_area",
    "intersects_wetland",
    "wetland_type",
    "wetland_subtype",
    "wetland_acres",
    "nearest_wetland_distance_m",
    "wetlands_within_100m_count",
    "wetlands_within_500m_count",
    "surface_water_permanence_pct",
    "nearest_waterbody_name"
  ],
  "wildfire_underwrite": [
    "lcms_class",
    "tree_canopy_pct",
    "ndvi_current",
    "ndvi_change_5y",
    "slope_degrees",
    "elevation"
  ],
  "land_cover": [
    "lcms_class",
    "land_use_class",
    "tree_canopy_pct",
    "cdl_class",
    "dominant_crop_5y"
  ],
  "site_selection": [
    "elevation",
    "slope_degrees",
    "lcms_class",
    "within_floodplain_polygon",
    "intersects_wetland",
    "wetland_type",
    "nearest_wetland_distance_m",
    "wetlands_within_100m_count",
    "nearest_major_road_distance_m",
    "nearest_major_road_class",
    "roads_within_500m_count",
    "nearest_transmission_line_distance_m",
    "nearest_tr

​ Example 1: flat fields list in Manhattan

curl -s https://api.mireye.com/v1/fetch \
  -H "Authorization: Bearer $MIREYE_API_TOKEN" \
  -H 'content-type: application/json' \
  -d '{
    "lat": 40.7128,
    "lng": -74.0060,
    "fields": ["elevation", "coast_distance_m"]
  }' | jq

​ Example 2: preset on a coastal coordinate

curl -s https://api.mireye.com/v1/fetch \
  -H "Authorization: Bearer $MIREYE_API_TOKEN" \
  -H 'content-type: application/json' \
  -d '{
    "lat": 29.7604,
    "lng": -95.3698,
    "preset": "flood_risk"
  }' | jq

​ Per-field response shape

​ The honesty pattern: status + partial_failures

  • In fields, with "status": "failed", "value": null, and the error + retryable hints inline — so every requested field is present in fields, distinguished by its status.
  • In partial_failures, a flat list of just the failures (kept for back-compat).
JSON
{
  "lat": 46.6, "lng": -93.7,
  "fields": {
    // … the requested fields that succeeded (status "ok") or had valid
    // no-data (status "absent") …
    "ndvi_current": {
      "value": null,
      "status": "failed",
      "source": "COPERNICUS_S2_SR_HARMONIZED",
      "error": "TimeoutError: Earth Engine compute exceeded 30s",
      "retryable": true
      // … plus the standard unit / source_url / ttl_seconds / notes keys …
    }
  },
  "partial_failures": [
    {
      "field": "ndvi_current",
      "source": "COPERNICUS_S2_SR_HARMONIZED",
      "error": "TimeoutError: Earth Engine compute exceeded 30s",
      "retryable": true
    }
  ]
}
  • retryable: true — transient and worth a retry with backoff: a timeout / connection reset, or a metered quota that resets later (e.g. a Regrid billing-period exhaustion).
  • retryable: false — retrying won’t help: the upstream returned a structured error (a missing plan entitlement, an unsupported request).

​ Limits

  • 50 fields maximum per request (after preset expansion). Exceeding this returns 400 fields_too_many.
  • Batching: one location per request here; up to 25 locations in one call via POST /v1/fetch/batch, which returns index-aligned results in this endpoint’s exact response shape.
  • No caching headers on /v1/fetch. Each call hits the underlying layer orchestrators, which keep their own 24-hour response cache (local disk, plus a shared Redis tier in production). The ttl_seconds hint is for the caller’s own cache layer.

Successful Response