# Mireye

> Federal-grade geospatial ground truth for any US coordinate. Every value carries a source, URL, dataset vintage, and confidence — built for AI agents.

Mireye turns a latitude/longitude — or a US street address — into sourced, structured data across 250+ fields (7 layers, 15 presets): terrain & soils, flood & wildfire risk, land cover, buildings & roads, the electric grid & gas network, water, solar/wind resource, natural hazards, parcels & boundaries. US only (lat 18–72, lng -180 to -65). Sources are federal: USGS, NOAA, USDA, USFS, USFWS, FEMA, EPA, EIA, NREL, LBNL, US Census, BLM, USACE, and more.

## Start here (no auth)

Discover the entire catalog — every field, unit, source, and the 15 presets — with one public call:

```
curl -s https://api.mireye.com/v1/meta/fields | jq
```

## API

- [Ask, natural language](https://api.mireye.com/v1/ask): POST a coordinate (or a US street address) + question; a planner picks fields, a synthesizer returns a cited prose answer. Bearer token required.
- [Fetch, named fields](https://api.mireye.com/v1/fetch): POST a coordinate (or a US street address) + field names or a preset; each value returns with source, source_url, confidence, dataset_vintage, fetched_at, status. Bearer token required.
- [Batch fetch, many locations](https://api.mireye.com/v1/fetch/batch): POST one field selection plus up to 25 locations (each lat+lng or address). Results are index-aligned with the request and each is the same shape as a `/v1/fetch` body; a location that fails comes back as an `ok: false` entry carrying the error the single endpoint would have returned, never failing the batch. Bills per location. Bearer token required.
- [Runs, async jobs](https://api.mireye.com/v1/runs): POST a job and get a `run_id` back immediately (202), then poll `/v1/runs/{run_id}` for `queued` / `running` / `done` / `failed` plus progress, or stream `/v1/runs/{run_id}/events` over SSE. A finished run downloads as `csv` or `geojson` from `/v1/runs/{run_id}/artifacts/{fmt}`. One kind today, `fetch_batch` — the `/v1/fetch/batch` request shape, same validation, same limits. A run is readable only by the account that submitted it and expires 30 days after submission. Bearer token required.
- [Field catalog](https://api.mireye.com/v1/meta/fields): GET the machine-readable catalog. Public, no auth, ETag-cached.
- [Geocode, address to coordinate](https://api.mireye.com/v1/geocode): POST a US street address; returns lat/lng plus `accuracy_type` (rooftop / street / centroid) so you know whether the coordinate is on the building or estimated from a street range. Ask and Fetch also accept `address` directly instead of lat/lng. Centroid-grade and low-confidence matches are refused rather than guessed at. The address you send is recorded for 30 days alongside the coordinate it resolves to, so a disputed result can be audited; pass lat/lng instead if that does not suit your caller. Bearer token required.
- [Resolve, canonical join keys](https://api.mireye.com/v1/lookup): POST an address or a `"lat,lng"` pair; returns a typed `disposition` (`resolved` / `clarify` / `no_match`) plus a coordinate, county/tract codes, and — when the geocode clears parcel-quality accuracy — a parcel (owner, boundary). Genuinely ambiguous input (e.g. a city name that exists in two states) returns candidates instead of a silent pick; a parcel-lookup failure never demotes an otherwise-good match to an error. APN-shaped input is detected but not yet resolved — returns a clean `no_match`. Bearer token required.
- [Compute, drive-time analysis](https://api.mireye.com/v1/proximity): POST one of four ops — `distance` (point-to-point or a matrix, up to 10,000 calcs), `nearest` (nearest-N by drive time over curated sets: airports, substations, power plants, rail, ports, urban areas), `screen` (filter locations by a drive-time cutoff, with near-miss reporting), or `labor_shed` (civilian labor force and population within a drive-time radius). Durations reflect typical traffic, not real-time. US + Canada. Bearer token required. Every origin/destination/anchor must be a `lat,lng` coordinate or a FULL street address (house number, street, city, state) — a place or landmark name ("SFO airport") is not a locator and is refused, because it silently matches a real but wrong place. If you infer a missing city yourself, say so in your answer.
- [Field requests, order a missing field](https://api.mireye.com/v1/field-requests): POST a plain-language description of a field the catalog doesn't have yet plus 1–10 example locations. It is matched against the catalog first — an existing field that already answers it returns the value now with a citation and spends no build, a close-but-inexact match comes back for you to accept or reject, and only a genuine gap is queued to build. Poll `/v1/field-requests/{request_id}` for status, queue position, and — once the status is `live` — a ready-to-send `/v1/fetch` call that answers the original ask. A rejection carries a typed code and a routing hint rather than a bare no. Filing spends no fetch credits; each plan includes a build allowance. Bearer token required.

## Pricing (credits)

Credit-based, one flat overage rate. Free tier: 5,000 credits/mo, 20 req/min, no card. Paid plans: Build $19/mo (25,000 credits, 60 rpm) · Growth $99/mo (120,000 credits, 300 rpm) · Scale $499/mo (750,000 credits, 600 rpm). Extra credits are always $1.00 per 1,000; credits reset on the 1st of each month (UTC).

- Per call: geocode 1 credit · fields 1 credit per field per location · ask 10 credits · resolve 300 credits (150 on Scale, charged only on a successful match) · compute 12 credits per driving calculation (floors: distance 2, nearest 2, screen 5, labor_shed 25; +1 credit per address-form locator, max 25/request; straight-line mode bills only the floor).
- [Full pricing](https://www.mireye.com/pricing): plan table, what a credit buys, and worked workload costs.

## MCP (for agent clients)

- Hosted: point your MCP client at https://api.mireye.com/mcp (OAuth 2.1 + PKCE — no manual tokens).
- Local (stdio): `uvx mireye-mcp`
- Tools: `mireye_ask`, `mireye_fetch`, `mireye_geocode`, `mireye_lookup`, `mireye_proximity`, `mireye_request_field`, `mireye_field_request_status`.

## Writing

- [The Mireye blog](https://www.mireye.com/blog): research and essays from Mireye — we point our API at America and publish what we find, every number cited.
- [We Screened Every Meat Plant in America in One Afternoon](https://www.mireye.com/blog/cold-chain-fragility-us-meat-plants): Every US meat plant screened for cold-chain fragility in one afternoon. The fragile tail is small, Southern, humid, and far from the grid.
- [Site Selection Is Now Grid Selection: Screening Land for Data Centers](https://www.mireye.com/blog/data-center-site-selection-grid-selection): Power, not fiber, now decides where data centers get built. The sequential filter that clears a site before the queue fills, and the data discipline underneath it.

## Docs

- [Documentation](https://docs.mireye.ai)
- [Agent guide (skills.md)](https://www.mireye.com/skills.md)
- [Docs LLM index](https://docs.mireye.ai/llms.txt)