mireye-earth 0.1.0

Provenance-tagged geospatial data for US coordinates.

Mireye Earth

Mireye Earth answers geospatial questions about US coordinates with federal-source citations. Every field returned — elevation, flood-zone status, wildfire fuel load, nearest power plant, parcel zoning — carries the source, source URL, fetched timestamp, and a calibrated confidence bucket. Built for insurance underwriters, lenders, and AI agents that need an audit trail, not just an answer.

• POST /v1/ask — natural-language Q&A over any US coordinate, returns answer + per-citation provenance.
• POST /v1/fetch — deterministic field-level access (47+ catalog fields, 8 use-case presets).
• GET /v1/meta/fields — public catalog. Versioned, ETag-cached, used by the planner and any third-party client.
• MCP server — same two operations exposed as MCP tools for Claude Desktop, Cursor, and custom agents.

Live deployment: https://mireye-earth.fly.dev Interactive Swagger: https://mireye-earth.fly.dev/v1/docs OpenAPI spec: https://mireye-earth.fly.dev/v1/openapi.json Full docs (Mintlify): https://docs.mireye.earth

---

Try it

curl -s https://mireye-earth.fly.dev/v1/ask \
  -H 'content-type: application/json' \
  -d '{
    "lat": 40.7128,
    "lng": -74.0060,
    "question": "What is the elevation here?"
  }' | jq

Returns the answer with citations naming the federal source for every value used:

{
  "lat": 40.7128,
  "lng": -74.006,
  "question": "What is the elevation here?",
  "answered_at": "2026-05-24T22:14:03.918Z",
  "answer": "The elevation at 40.7128, -74.0060 is 13.15 meters above NAVD88 (43.1 feet), per the USGS 3D Elevation Program (3DEP).",
  "confidence": "HIGH",
  "citations": [
    {
      "source": "USGS_3DEP",
      "source_url": "https://www.usgs.gov/3d-elevation-program",
      "fields": ["elevation"],
      "fetched_at": "2026-05-24T22:14:01.882Z",
      "confidence": "HIGH"
    }
  ],
  "fields_used": ["elevation"]
}

The /v1/fetch endpoint is the developer escape hatch — pass named fields or a preset, get raw structured values back:

curl -s https://mireye-earth.fly.dev/v1/fetch \
  -H 'content-type: application/json' \
  -d '{"lat": 29.7604, "lng": -95.3698, "preset": "flood_risk"}' | jq

---

At a glance

Endpoint	What it does	Latency (warm)
POST /v1/ask	LLM planner picks fields → fetches → synthesizes a cited natural-language answer.	2–6 s
POST /v1/fetch	Returns named fields with full per-field provenance + partial_failures.	1–3 s
GET /v1/meta/fields	Field + preset catalog. 1-hour Cache-Control, supports If-None-Match.	<50 ms
MCP ask / fetch	Same two operations exposed as MCP tools. stdio transport, ~100 LOC adapter.	+HTTP overhead

Coordinates are validated against the US envelope (lat ∈ [18, 72], lng ∈ [-180, -65]). Out-of-bounds requests return 400 coord_out_of_bounds with structured detail. Unknown field names return 400 fields_unknown listing exactly which names failed.

---

Install

Use the deployed API

No install. Hit https://mireye-earth.fly.dev/v1/* directly. The OpenAPI spec at /v1/openapi.json generates SDKs in any language via openapi-generator.

Install the MCP server (for Claude Desktop / Cursor / agents)

uv pip install 'mireye-earth[mcp]'

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "mireye-earth": {
      "command": "mireye-earth-mcp"
    }
  }
}

Restart Claude Desktop. Full install guide and Cursor / custom-agent setup in mcp_server/README.md and docs/mcp/installation.mdx.

Self-host the API

The HTTP server lives in api/ and is a thin FastAPI app over the mireye_earth Python library. You will need Python 3.11+, ~600 MB of disk for the bundled bulk-data assets, and an Earth Engine service account if you want live NDVI / land-cover layers.

git clone https://github.com/mireye/mireye-earth
cd mireye-earth
uv sync                       # install package + dev deps
cp .env.example .env          # add EARTHDATA_TOKEN + optional EE creds
uv run mireye-earth bootstrap # download static federal assets
uv run uvicorn api.main:app --port 8000

See api/README.md for the full endpoint reference and self-host deploy guide, and api/DEPLOY.md for the specific Fly.io configuration we run in production.

---

Field catalog (sample)

47 fields across 5 layers and 8 presets. Full table at docs/api-reference/field-catalog.mdx or the live JSON at /v1/meta/fields.

Field	Layer	Unit	Source
elevation	terrain	meters	USGS 3DEP
slope_degrees	terrain	degrees	USGS 3DEP
coast_distance_m	terrain	meters	NOAA CUSP
soil_drainage_class	terrain	(enum)	USDA SSURGO
within_floodplain_polygon	terrain	(bool)	USGS NHDPlus HR
intersects_wetland	terrain	(bool)	USFWS NWI
lcms_class	land cover	(enum)	USFS LCMS
tree_canopy_pct	land cover	percent	USFS NLCD TCC
ndvi_current	land cover	(ratio)	Sentinel-2 NDVI
cdl_class	land cover	(enum)	USDA CDL
primary_building_height_m	built environment	meters	Overture Buildings
nearest_major_road_distance_m	built environment	meters	Overture Transportation
nearest_power_plant_distance_m	utilities	meters	EIA Energy Atlas
nearest_transmission_line_distance_m	utilities	meters	EIA Energy Atlas
intersects_conservation_easement	parcels	(bool)	USGS PAD-US

Presets (request via "preset": "<name>"):

• terrain — elevation, slope, aspect, coast, soil, bedrock.
• flood_risk — elevation, coast distance, floodplain, wetland, water permanence, nearest waterbody.
• wildfire_underwrite — LCMS class, tree canopy, NDVI current, NDVI 5-year change, slope, elevation.
• land_cover — LCMS class, land use, tree canopy, CDL class, dominant crop.
• site_selection — terrain + LCMS + floodplain + nearest road + nearest transmission + easements.
• building_lookup — building class, height, floors, footprint + nearest road / bridge.
• utilities — nearest plant / transmission / pipeline / water system / rail / airport / port.
• boundaries — region, county, locality, tract GEOID, easements.

---

Data sources

Mireye Earth queries only authoritative federal datasets. No proprietary risk models, no third-party data brokers, no "AI-derived" values. Every field's source_url points back to the originating agency so a regulator, underwriter, or auditor can re-fetch and verify.

• USGS — 3D Elevation Program (3DEP), NHDPlus HR (hydrography), Watershed Boundary Dataset (WBD), PAD-US (protected areas / easements).
• NOAA — Continually Updated Shoreline (CUSP).
• USDA — SSURGO + STATSGO2 (soils), Cropland Data Layer (CDL).
• USFS — Landscape Change Monitoring System (LCMS), NLCD Tree Canopy Cover.
• USFWS — National Wetlands Inventory (NWI).
• EPA — Safe Drinking Water Information System (SDWIS).
• EIA — Energy Atlas (power plants, transmission, pipelines).
• FAA — National Airspace System Resource (NASR).
• FHWA — National Bridge Inventory (NBI).
• BTS — National Transportation Atlas Database (NTAD), Ports.
• US Census Bureau — Geocoder, TIGER.
• Overture Maps Foundation — Buildings, Transportation, Divisions (federation of OSM + Microsoft + others under a permissive license).
• Copernicus / ESA — Sentinel-2 (NDVI).
• JRC — Global Surface Water.
• Regrid — parcel boundaries (free tier via Esri Living Atlas).

---

Repo layout

api/             FastAPI HTTP surface (/v1/ask, /v1/fetch, /v1/meta/fields)
mcp_server/      MCP stdio adapter exposing the same operations as MCP tools
src/mireye_earth Python library — per-layer orchestrators and source adapters
docs/            Mintlify documentation site (introduction, quickstart, references)
tests/           pytest unit + live integration suite (~50 tests)
scripts/         CLI helpers (bootstrap, benchmark, eval harnesses)
data/            Local bulk-data drop zone (populated by `mireye-earth bootstrap`)

---

License & contact

License: TBD (planning Apache-2.0 for the library + adapter, separate terms for hosted API beyond the free tier).

Contact: [e-mail].

For background on the design decisions (why /ask + /fetch, why the planner is two-phase, why MCP, why federal-only), see API-DESIGN.md and ASK-API-DESIGN.md.