com.mireye/earth

Answer a natural-language question about a US location, with citations to authoritative federal data sources. Give EITHER lat+lng OR address, never both. Returns the answer plus per-citation provenance (source, source URL, fetched_at, confidence). Use this when the caller has a specific question about a place (e.g. 'is this in a flood zone?', 'what's the wildfire risk here?'). When you pass an address, the response carries a `geocode` block: if `parcel_grade` is false the location was estimated from the street and can be ~2.9 km out in rural areas, and the answer says so.

Fetch specific data fields at a US location with full provenance per field. Give EITHER lat+lng OR address, never both. Use this when the caller knows exactly which fields they need (e.g. 'elevation and slope at this point') or wants to power a custom workflow. Each field includes its value, source, source URL, fetched_at timestamp, and confidence. When you pass an address, the response carries a `geocode` block: check `parcel_grade` before trusting parcel-specific fields — a false value means the coordinate was estimated from the street and can be ~2.9 km out in rural areas.

Poll the status of a field request filed with mireye_request_field: status, queue position, the promised estimated_ready_at (fixed at acceptance, never recomputed on poll), and -- once status is 'live' -- the resume call (a ready-to-send /v1/fetch request) that answers the original ask. Store request_id in durable task state, not conversation context: builds run on a scale of hours and the filing session will likely be gone before one finishes. Status vocabulary: 'received'/'screening' (still being screened; check waiting_on -- 'operator' means screening failed and a human has to look), 'matched' (the catalog already answered it, use resume), 'awaiting_confirm' (a near-miss or clarify needs you), 'rejected' (typed codes in disposition, terminal), 'queued'/'claimed'/'building'/'in_review'/'approved'/'publishing' (a build is in progress), 'live' (done, resume works now), 'blocked'/'expired' (terminal, no build). Requests are visible only to the credential that filed them; an id that doesn't exist -- or belongs to someone else -- is the same 404, never a 403 (a 403 would confirm the id exists).

Resolve a US street address to a coordinate, with the quality of that coordinate. Feed lat/lng to mireye_fetch or mireye_ask. ALWAYS check accuracy_type before trusting the result: 'rooftop' is on the parcel, but 'range_interpolation' is estimated along a street centerline and can be ~2.9 km out in rural areas — far enough to describe a neighbouring property instead. An address that can only be placed at a ZIP/city/county centroid is REJECTED as address_too_coarse rather than returned — if you get that, ask the user for a more complete address instead of retrying. The address you send is retained alongside the coordinate it resolves to, so a result can be audited later; pass lat/lng instead if that does not suit the caller.

Turn a messy human locator (address, "lat,lng", or APN) into canonical join keys: a coordinate, resolved address, and -- when the geocode is parcel-quality -- a parcel (id, boundary, owner). Unlike mireye_geocode, this detects genuine ambiguity across multiple candidate matches instead of trusting a single top result, so an underspecified input like '1100 King St W, Toronto' returns disposition='clarify' with candidates instead of silently landing on the wrong Toronto. ALWAYS check `disposition` first: 'resolved' carries a coordinate and confidence (plus a parcel when safe); 'clarify' means the input is genuinely ambiguous -- present the candidates to the user, never auto-pick one; 'no_match' is an honest failure with a `reason`. A parcel-lookup failure never demotes a good geocode -- 'resolved' can still come back with `parcel_unavailable: true` and a `parcel_unavailable_reason` (e.g. the vendor's own quota being exhausted) rather than an error. Swapped coordinates (e.g. lng where lat belongs) are rejected as a bounds error, never silently treated as a nearest-match. APN-only lookup is not supported yet -- supply an address or coordinate. A 'resolved' response also carries free area context gathered concurrently with the parcel lookup: jurisdiction codes (state, block/block-group, congressional district, CBSA/metro area) alongside county/tract, elevation and FEMA flood-zone fields, a county_market bundle (population, growth, employment, home-price change, median income), Opportunity Zone status, and an IANA timezone -- every one of these degrades independently to null on its own failure and never blocks the primary coordinate/parcel answer.

Ask Mireye for a data field it doesn't have yet, in plain language, at one or more example locations. If the catalog already answers it you get the value now with a citation (disposition 'matched_existing'/'partial') and never spend a build; if something close exists you get 'near_miss_confirm' to accept or reject; otherwise the field is queued to build and you get a request_id to poll with mireye_field_request_status. ALWAYS pass idempotency_key for agent-originated requests: the same key replays the existing request's state instead of filing a second build. Answering use_case/decision_threshold (what decision this feeds, and the value that flips it) is optional but sharply improves match quality and build speed. example_locations (1-10 entries) each carry exactly one of address, lat+lng, or polygon, plus optional claimed_value/note -- see docs.mireye.ai/api-reference/field-requests for the full entry shape. requested_fields optionally pre-splits a bundled ask into atomic sub-questions (plain-language asks); the server decomposes bundles anyway. extra carries the rarer structured fields verbatim (area_of_interest, expected_volume, freshness, constraints, known_sources, output_preference) -- same doc has their shapes. A 'rejected' disposition carries a typed rejection_code and routing_hint, never a bare no; a genuinely ambiguous location returns a stateless 'clarify' with candidates instead of guessing. Filing a request never spends /v1/fetch credits; plans carry a separate included build allowance.