> ## Documentation Index > Fetch the complete documentation index at: https://docs.mireye.ai/llms.txt > Use this file to discover all available pages before exploring further. # POST /v1/fetch > Deterministic per-field data fetch with full provenance. ## When to use this Use `/v1/fetch` when: * 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. Use [`/v1/ask`](/api-reference/ask) instead when the question is phrased in natural language and the right answer requires combining values with interpretation. ## Request shape The body accepts `lat`, `lng`, and at least one of `fields` or `preset` (both is allowed — preset expands first, then `fields` unions in, and the combined list is capped at 50). | Field | Type | Required | Notes | | -------- | ---------------- | -------- | -------------------------------------------------------------------------------------- | | `lat` | number | yes | US envelope `[18, 72]`. | | `lng` | number | yes | US envelope `[-180, -65]`. | | `fields` | array of strings | one of | Catalog field names. See [/api-reference/field-catalog](/api-reference/field-catalog). | | `preset` | string enum | one of | One of the preset names (see below). | ## Presets Presets are use-case bundles. Pass `"preset": "flood_risk"` and you get the floodplain-relevant fields without naming each one. The preset expansions: ```json theme={null} { "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_transmission_line_voltage_kv", "nearest_transmission_line_voltage_class", "nearest_transmission_line_voltage_basis", "max_transmission_line_voltage_kv_within_radius", "max_transmission_line_voltage_class_within_radius", "intersects_conservation_easement", "intersects_protected_area", "protected_area_gap_status", "intersects_critical_habitat", "critical_habitat_status", "parcel_id", "parcel_zoning", "parcel_area_m2", "parcel_geometry_wkt", "parcel_boundary_geojson", "nearest_hospital_distance_m", "nearest_fire_station_distance_m", "nearest_school_distance_m", "nearest_grocery_store_distance_m", "nearest_lodging_distance_m", "poi_count_1km", "transmission_lines_within_radius_count", "substations_within_radius_count", "substations_radius_m", "housing_units_within_1km", "in_opportunity_zone", "nearest_repowering_site_distance_m", "wetland_acres_on_parcel", "transmission_redundancy_flag", "grading_difficulty_class", "residential_context_class_1km", "developable_acres_proxy", "tax_incentive_stack", "near_epa_repowering_site", "onsite_solar_potential_mwac_low", "onsite_solar_potential_mwac_high", "nearest_urban_area_distance_m", "nearest_urban_area_rtt_floor_ms", "within_sewer_service_area", "sewer_service_area_provider", "sewer_service_area_provenance", "nearest_sewer_service_area_distance_m" ], "building_lookup": [ "primary_building_overture_class", "primary_building_height_m", "primary_building_num_floors", "primary_building_footprint_sqm" ], "points_of_interest": [ "nearest_hospital_distance_m", "nearest_hospital_name", "nearest_fire_station_distance_m", "nearest_fire_station_name", "nearest_school_distance_m", "nearest_school_name", "nearest_grocery_store_distance_m", "nearest_lodging_distance_m", "nearest_restaurant_distance_m", "nearest_restaurant_name", "nearest_cafe_distance_m", "nearest_cafe_name", "nearest_bar_distance_m", "nearest_bar_name", "nearest_gas_station_distance_m", "nearest_gas_station_name", "nearest_pharmacy_distance_m", "nearest_pharmacy_name", "nearest_bank_distance_m", "nearest_bank_name", "nearest_shopping_center_distance_m", "nearest_shopping_center_name", "poi_count_1km" ], "utilities": [ "nearest_power_plant_name", "nearest_power_plant_distance_m", "nearest_power_plant_primary_fuel", "nearest_power_plant_capacity_mw", "nearest_transmission_line_distance_m", "nearest_transmission_line_voltage_kv", "nearest_transmission_line_voltage_class", "nearest_transmission_line_voltage_basis", "nearest_transmission_line_status", "nearest_transmission_line_owner", "max_transmission_line_voltage_kv_within_radius", "max_transmission_line_voltage_class_within_radius", "transmission_lines_within_radius_count", "nearest_gas_pipeline_distance_m", "within_sewer_service_area", "sewer_service_area_provider", "sewer_service_area_provenance", "nearest_sewer_service_area_distance_m" ], "boundaries": [ "political_region", "political_county", "political_locality", "tract_geoid" ], "solar_siting": [ "ghi_annual_kwh_m2_day", "dni_annual_kwh_m2_day", "pv_capacity_factor_pct", "pv_specific_yield_kwh_per_kw", "optimal_fixed_tilt_degrees", "surface_albedo_annual", "mean_annual_snow_cover_days", "mean_annual_dry_bulb_temperature_degc", "days_above_32c_annual_count", "nearest_utility_solar_facility_distance_m", "nearest_utility_solar_facility_capacity_mw", "prime_farmland_classification", "blm_solar_application_land_status", "surface_management_agency", "nearest_repowering_site_distance_m", "slope_degrees", "aspect_degrees", "aspect_cardinal", "parcel_zoning", "is_cultivated", "tree_canopy_pct", "housing_units_within_1km", "housing_units_density_per_km2", "grading_difficulty_class", "soil_hydrologic_group", "soil_erodibility_k_factor", "soil_available_water_capacity" ], "wind_siting": [ "mean_wind_speed_100m_ms", "mean_wind_speed_120m_ms", "mean_wind_speed_160m_ms", "wind_power_density_100m_wm2", "prevailing_wind_direction_100m_cardinal", "weibull_k_100m", "wind_capacity_factor_pct", "wind_least_cost_interconnect_distance_m", "nearest_wind_turbine_distance_m", "nearest_wind_turbine_hub_height_m", "nearest_wind_turbine_total_height_m", "nearest_wind_project_capacity_mw", "special_use_airspace_type", "golden_eagle_nest_density_index", "prime_farmland_classification", "surface_management_agency", "nearest_repowering_site_distance_m", "slope_degrees", "elevation", "nearest_airport_distance_m", "bedrock_depth_cm", "housing_units_within_1km", "housing_units_density_per_km2", "grading_difficulty_class", "soil_restrictive_layer_depth_cm", "soil_restrictive_layer_kind" ], "storage_siting": [ "nearest_substation_distance_m", "nearest_substation_max_voltage_kv", "nearest_substation_status", "electric_utility_service_territory", "avg_retail_electricity_price_industrial_usd_per_kwh", "egrid_co2_output_rate_kg_per_mwh", "interconnection_queue_active_capacity_county_mw", "wind_least_cost_interconnect_distance_m", "nearest_proposed_generator_distance_m", "nearest_proposed_generator_capacity_mw", "nearest_proposed_generator_status", "nearest_utility_solar_facility_distance_m", "surface_management_agency", "prime_farmland_classification", "nearest_transmission_line_distance_m", "nearest_power_plant_distance_m", "parcel_zoning", "slope_degrees", "grading_difficulty_class", "soil_hydrologic_group" ], "data_center_siting": [ "nearest_substation_distance_m", "nearest_substation_max_voltage_kv", "nearest_substation_status", "nearest_power_plant_operator", "nearest_power_plant_technology", "electric_utility_service_territory", "avg_retail_electricity_price_industrial_usd_per_kwh", "egrid_subregion", "egrid_co2_output_rate_kg_per_mwh", "interconnection_queue_active_capacity_county_mw", "design_wet_bulb_temperature_0_4pct_degc", "mean_annual_dry_bulb_temperature_degc", "mean_annual_relative_humidity_pct", "days_above_32c_annual_count", "surface_water_supply_use_index_huc12", "public_water_system_population_served", "huc12_thermoelectric_consumptive_use_m3_per_day", "nearest_groundwater_well_depth_to_water_m", "nearest_usgs_gage_daily_discharge_cfs", "fiber_provider_count", "fiber_broadband_available", "mobile_5g_coverage_class", "nearest_submarine_cable_distance_m", "nearest_submarine_cable_name", "nearest_long_haul_rail_corridor_distance_m", "nearest_rail_line_distance_m", "nearest_urban_area_distance_m", "soil_shrink_swell_class", "surface_management_agency", "nearest_gas_pipeline_distance_m", "nearest_interstate_gas_pipeline_distance_m", "surface_water_permanence_pct", "nearest_dam_distance_m", "nearest_dam_hazard_potential", "high_hazard_dams_within_10km", "nearest_hazardous_facility_distance_m", "nearest_hazardous_facility_name", "housing_units_within_1km", "housing_units_density_per_km2", "natural_gas_citygate_price_usd_per_mcf", "natural_gas_industrial_price_usd_per_mcf", "grid_price_usd_per_mwh", "modeled_onsite_gas_generation_cost_usd_per_mwh", "in_shale_play", "nearest_shale_play_name", "sedimentary_basin_name", "nearest_gas_compressor_distance_m", "nearest_gas_storage_distance_m", "nearest_lng_terminal_distance_m", "drought_category", "in_opportunity_zone", "opportunity_zone_tract_geoid", "in_air_quality_nonattainment", "air_quality_nonattainment_pollutants", "in_air_quality_maintenance", "air_quality_maintenance_pollutants", "air_quality_worst_classification", "air_district_name", "nearest_brownfield_distance_m", "brownfields_within_radius_count", "nearest_superfund_distance_m", "superfund_sites_within_radius_count", "nearest_class_i_area_distance_m", "nearest_class_i_area_name", "nearest_class_i_area_agency", "slope_degrees", "transmission_lines_within_radius_count", "substations_within_radius_count", "substations_radius_m", "nearest_repowering_site_distance_m", "within_floodplain_polygon", "fema_flood_zone", "estimated_annual_power_cost_usd_per_mw", "transmission_redundancy_flag", "grading_difficulty_class", "residential_context_class_1km", "btm_gas_candidacy_flag", "tax_incentive_stack", "near_epa_repowering_site", "free_cooling_hours_per_year_15c", "free_cooling_hours_per_year_10c", "nearest_urban_area_rtt_floor_ms", "soil_hydrologic_group", "soil_restrictive_layer_depth_cm", "soil_restrictive_layer_kind", "soil_erodibility_k_factor", "within_sewer_service_area", "sewer_service_area_provider", "sewer_service_area_provenance", "nearest_sewer_service_area_distance_m" ], "grid_interconnect": [ "nearest_substation_distance_m", "nearest_substation_max_voltage_kv", "nearest_substation_status", "electric_utility_service_territory", "iso_rto", "interconnection_queue_active_capacity_county_mw", "interconnection_queue_active_capacity_pjm_mw", "interconnection_queue_active_capacity_miso_mw", "interconnection_queue_active_capacity_ercot_mw", "interconnection_queue_active_capacity_caiso_mw", "interconnection_queue_active_capacity_spp_mw", "interconnection_queue_active_capacity_nyiso_mw", "interconnection_queue_active_capacity_isone_mw", "interconnection_queue_active_capacity_west_mw", "interconnection_queue_active_capacity_southeast_mw", "wind_least_cost_interconnect_distance_m", "nearest_proposed_generator_distance_m", "nearest_proposed_generator_capacity_mw", "nearest_proposed_generator_status", "egrid_subregion", "nearest_transmission_line_distance_m", "nearest_power_plant_distance_m", "nearest_power_plant_capacity_mw", "nearest_power_plant_operator", "nearest_power_plant_technology", "transmission_lines_within_radius_count", "substations_within_radius_count", "substations_radius_m", "transmission_redundancy_flag" ], "natural_hazard": [ "seismic_pga_2pct_50yr_g", "seismic_design_category", "design_wind_speed_mph", "wildfire_annual_frequency", "tornado_annual_frequency", "hail_annual_frequency", "lightning_annual_flash_days", "landslide_susceptibility_index", "soil_shrink_swell_class", "within_floodplain_polygon", "slope_degrees", "nearest_dam_distance_m", "nearest_dam_hazard_potential", "high_hazard_dams_within_10km" ] } ``` To add fields beyond a preset's bundle, send both: ```json theme={null} { "lat": 29.7604, "lng": -95.3698, "preset": "flood_risk", "fields": ["soil_drainage_class"] } ``` ## Example 1: flat fields list in Manhattan ```bash theme={null} 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 ``` ```json theme={null} { "lat": 40.7128, "lng": -74.006, "fetched_at": "2026-06-12T07:27:35.840477+00:00", "fields": { "elevation": { "value": 13.150006294, "unit": "meters", "source": "USGS_EPQS", "source_url": "https://epqs.nationalmap.gov/v1/json?x=-74.006&y=40.7128&wkid=4326&units=Meters", "confidence": "high", "fetched_at": "2026-06-12T07:27:35.826959+00:00", "dataset_vintage": "3DEP dynamic service", "ttl_seconds": 31536000, "notes": null }, "coast_distance_m": { "value": 764.2256402243065, "unit": "meters", "source": "NOAA_CUSP", "source_url": "https://shoreline.noaa.gov/data/datasheets/cusp.html", "confidence": "high", "fetched_at": "2026-06-12T07:27:35.839783+00:00", "dataset_vintage": null, "ttl_seconds": 31536000, "notes": null } }, "partial_failures": [] } ``` ## Example 2: preset on a coastal coordinate Houston, downtown — flood-relevant features in the same call: ```bash theme={null} 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 ``` ```jsonc theme={null} { "lat": 29.7604, "lng": -95.3698, "fetched_at": "2026-06-12T07:27:55.451492+00:00", "fields": { "elevation": { "value": 14.376572609, "unit": "meters", "source": "USGS_EPQS", "source_url": "https://epqs.nationalmap.gov/v1/json?x=-95.3698&y=29.7604&wkid=4326&units=Meters", "confidence": "high", "fetched_at": "2026-06-12T07:27:52.656898+00:00", "dataset_vintage": "3DEP dynamic service", "ttl_seconds": 31536000, "notes": null }, "coast_distance_m": { "value": 2014.0760126281036, "unit": "meters", "source": "NOAA_CUSP", "source_url": "https://shoreline.noaa.gov/data/datasheets/cusp.html", "confidence": "high", "fetched_at": "2026-06-12T07:27:51.795394+00:00", "dataset_vintage": null, "ttl_seconds": 31536000, "notes": null }, "within_floodplain_polygon": { "value": false, "unit": null, "source": "FEMA_NFHL", "source_url": "https://hazards.fema.gov/arcgis/rest/services/public/NFHL/MapServer/28/query?f=json&geometry=-95.3698%2C29.7604&geometryType=esriGeometryPoint&inSR=4326&spatialRel=esriSpatialRelIntersects&outFields=FLD_ZONE%2CZONE_SUBTY%2CSFHA_TF%2CFLD_AR_ID%2CDFIRM_ID%2CSOURCE_CIT&returnGeometry=false&resultRecordCount=5", "confidence": "high", "fetched_at": "2026-06-12T07:27:52.259816+00:00", "dataset_vintage": "48201C_STUDY1", "ttl_seconds": 86400, "notes": "FEMA NFHL Flood Hazard Zones intersect, but not an SFHA: Zone X; AREA OF MINIMAL FLOOD HAZARD; SFHA_TF=F; FLD_AR_ID=48201C_9742; SOURCE_CIT=48201C_STUDY1." }, "intersects_wetland": { "value": false, "unit": null, "source": "USFWS_NWI", "source_url": "https://fwspublicservices.wim.usgs.gov/wetlandsmapservice/rest/services/Wetlands/MapServer/0/query?f=json&geometry=-95.3698%2C29.7604&geometryType=esriGeometryPoint&inSR=4326&spatialRel=esriSpatialRelIntersects&distance=500&units=esriSRUnit_Meter&outFields=%2A&returnGeometry=true&outSR=4326", "confidence": "high", "fetched_at": "2026-06-12T07:27:52.654612+00:00", "dataset_vintage": null, "ttl_seconds": 31536000, "notes": null }, "wetland_type": { "value": "Riverine Lower Perennial Unconsolidated Bottom Permanently Flooded", "unit": null, "source": "USFWS_NWI", "source_url": "https://fwspublicservices.wim.usgs.gov/wetlandsmapservice/rest/services/Wetlands/MapServer/0/query?f=json&geometry=-95.3698%2C29.7604&geometryType=esriGeometryPoint&inSR=4326&spatialRel=esriSpatialRelIntersects&distance=500&units=esriSRUnit_Meter&outFields=%2A&returnGeometry=true&outSR=4326", "confidence": "high", "fetched_at": "2026-06-12T07:27:52.654652+00:00", "dataset_vintage": null, "ttl_seconds": 31536000, "notes": null }, "wetlands_within_500m_count": { "value": 2, "unit": null, "source": "USFWS_NWI", "source_url": "https://fwspublicservices.wim.usgs.gov/wetlandsmapservice/rest/services/Wetlands/MapServer/0/query?f=json&geometry=-95.3698%2C29.7604&geometryType=esriGeometryPoint&inSR=4326&spatialRel=esriSpatialRelIntersects&distance=500&units=esriSRUnit_Meter&outFields=%2A&returnGeometry=true&outSR=4326", "confidence": "high", "fetched_at": "2026-06-12T07:27:52.654684+00:00", "dataset_vintage": null, "ttl_seconds": 31536000, "notes": null } /* …7 more flood_risk fields (wetland subtype/acres/distance/counts, NHD, surface-water permanence) — run the call to see all 13 */ }, "partial_failures": [] } ``` ## Per-field response shape Each value in `fields` is a self-contained record: | Field | Type | Notes | | ----------------- | ------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `value` | varies | The actual value. Type matches the catalog `type` (float/int/bool/string). | | `unit` | string or null | SI unit. `null` for enums, booleans, strings. | | `source` | string | Short source name. Runtime provenance can be more specific than the catalog default (e.g. `elevation` normally reports `USGS_EPQS`, or `USGS_3DEP_COG` when the EPQS service was slow/unavailable and the static-DEM fallback answered — with a `notes` explanation; slope reports `USGS_3DEP_COG`). | | `source_url` | string | URL where the value can be re-fetched/verified. | | `confidence` | `high`/`medium`/`low`/`unknown` | Per-field confidence bucket. | | `fetched_at` | ISO 8601 string | When this value was retrieved from source. | | `dataset_vintage` | string or null | Upstream dataset vintage/release (e.g., a CDL year), when the source reports one. | | `ttl_seconds` | integer | Recommended cache lifetime — see the [TTL table](/api-reference/field-catalog#cache-ttls). | | `notes` | string or null | Source-specific caveats (e.g., "NDVI from cloudy scene; mean over 4-week window"). | | `status` | `ok`/`absent`/`failed` | Tri-state marker: `ok` = a real value present; `absent` = valid no-data (the source answered "nothing here"); `failed` = the fetch errored. | A `failed` entry additionally carries `error` (string) and `retryable` (bool); its `value` is `null`. Read `status` to tell a real value from no-data from a failure without parsing `notes`. ## The honesty pattern: `status` + `partial_failures` `/v1/fetch` always returns 200 unless the request itself is malformed. A field that failed to fetch is surfaced **two ways**, so it can never be silently dropped or misread as "not requested": 1. 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`. 2. In `partial_failures`, a flat list of just the failures (kept for back-compat). ```jsonc theme={null} { "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 } ] } ``` Two recoverability hints (present on both the `fields` entry and the `partial_failures` record): * `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). We never silently drop a field we couldn't fetch: **every requested field appears in `fields` with a `status`** (`ok` / `absent` / `failed`). Read `status` (or cross-check `partial_failures`) rather than assuming presence in `fields` means success — a `failed` field is present too. ## Limits * **50 fields maximum** per request (after preset expansion). Exceeding this returns `400 fields_too_many`. * **No batching** in V1. One coordinate per request. Loop client-side for N coordinates. * **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. ## OpenAPI ````yaml POST /v1/fetch openapi: 3.1.0 info: title: Mireye Earth description: >- Provenance-tagged geospatial data for US coordinates. POST /v1/fetch for deterministic field values; POST /v1/ask for natural-language Q&A; GET /v1/meta/fields for the catalog. version: 0.14.0 servers: [] security: [] paths: /v1/fetch: post: summary: Fetch operationId: fetch_v1_fetch_post requestBody: content: application/json: schema: $ref: '#/components/schemas/FetchRequest' required: true responses: '200': description: Successful Response content: application/json: schema: {} '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' components: schemas: FetchRequest: properties: lat: type: number title: Lat lng: type: number title: Lng fields: anyOf: - items: type: string type: array - type: 'null' title: Fields preset: anyOf: - type: string enum: - terrain - flood_risk - wildfire_underwrite - land_cover - site_selection - building_lookup - points_of_interest - utilities - boundaries - solar_siting - wind_siting - storage_siting - data_center_siting - grid_interconnect - natural_hazard - type: 'null' title: Preset type: object required: - lat - lng title: FetchRequest HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' type: array title: Detail type: object title: HTTPValidationError ValidationError: properties: loc: items: anyOf: - type: string - type: integer type: array title: Location msg: type: string title: Message type: type: string title: Error Type input: title: Input ctx: type: object title: Context type: object required: - loc - msg - type title: ValidationError ````