POST /v1/fetch - Mireye Earth

Fetch

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

import requests

url = "https://api.example.com/v1/fetch"

payload = {
    "lat": 123,
    "lng": 123,
    "fields": ["<string>"]
}
headers = {"Content-Type": "application/json"}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({lat: 123, lng: 123, fields: ['<string>']})
};

fetch('https://api.example.com/v1/fetch', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.example.com/v1/fetch",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'lat' => 123,
    'lng' => 123,
    'fields' => [
        '<string>'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.example.com/v1/fetch"

	payload := strings.NewReader("{\n  \"lat\": 123,\n  \"lng\": 123,\n  \"fields\": [\n    \"<string>\"\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.example.com/v1/fetch")
  .header("Content-Type", "application/json")
  .body("{\n  \"lat\": 123,\n  \"lng\": 123,\n  \"fields\": [\n    \"<string>\"\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.example.com/v1/fetch")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n  \"lat\": 123,\n  \"lng\": 123,\n  \"fields\": [\n    \"<string>\"\n  ]\n}"

response = http.request(request)
puts response.read_body

{
  "detail": [
    {
      "loc": [
        "<string>"
      ],
      "msg": "<string>",
      "type": "<string>",
      "input": "<unknown>",
      "ctx": {}
    }
  ]
}

POST

fetch

Fetch

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

import requests

url = "https://api.example.com/v1/fetch"

payload = {
    "lat": 123,
    "lng": 123,
    "fields": ["<string>"]
}
headers = {"Content-Type": "application/json"}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({lat: 123, lng: 123, fields: ['<string>']})
};

fetch('https://api.example.com/v1/fetch', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.example.com/v1/fetch",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'lat' => 123,
    'lng' => 123,
    'fields' => [
        '<string>'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.example.com/v1/fetch"

	payload := strings.NewReader("{\n  \"lat\": 123,\n  \"lng\": 123,\n  \"fields\": [\n    \"<string>\"\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.example.com/v1/fetch")
  .header("Content-Type", "application/json")
  .body("{\n  \"lat\": 123,\n  \"lng\": 123,\n  \"fields\": [\n    \"<string>\"\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.example.com/v1/fetch")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n  \"lat\": 123,\n  \"lng\": 123,\n  \"fields\": [\n    \"<string>\"\n  ]\n}"

response = http.request(request)
puts response.read_body

{
  "detail": [
    {
      "loc": [
        "<string>"
      ],
      "msg": "<string>",
      "type": "<string>",
      "input": "<unknown>",
      "ctx": {}
    }
  ]
}

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 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.
`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:

{
  "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:

{
  "lat": 29.7604,
  "lng": -95.3698,
  "preset": "flood_risk",
  "fields": ["soil_drainage_class"]
}

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

{
  "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:

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

{
  "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.
`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”:

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).

{
  "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.

Body

application/json

lat

number

required

lng

number

required

fields

string[] | null

preset

enum<string> | null

Available options:

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

Response

Successful Response

POST /v1/ask GET /v1/meta/fields

⌘I

​When to use this

​Request shape

​Presets

​Example 1: flat fields list in Manhattan

​Example 2: preset on a coastal coordinate

​Per-field response shape

​The honesty pattern: status + partial_failures

​Limits