# Mireye Earth

> Cited public coordinate data, parcel enrichment, search, and answers for applications and agents.

## x402 Fetch without an API key

`POST https://api.mireye.com/v1/x402/fetch` returns the same public Fetch facts
for $0.001 USDC on Base (`eip155:8453`) per successful call. Use an x402 v2
client: inspect the unpaid `402` / `Payment-Required` challenge, then retry with
`Payment-Signature`. Successful payment produces a `Payment-Response` receipt.
Bazaar discovery metadata is included. No Mireye API key or account balance is
needed. Licensed parcel fields remain excluded, and `partial_failures` must
still be inspected. Account-wallet idempotency and recovery do not apply here.
See [x402 Fetch](https://docs.mireye.ai/api-reference/x402-fetch) for the full
payment and retry contract. Authenticated Fetch remains free.

## API

Base URL: `https://api.mireye.com`. Discover public Fetch fields and presets from `GET /v1/meta/fields`; use this current catalog instead of a remembered field list. `GET /v1/meta/plans` publishes the pricing contract.

- **Fetch** (`POST /v1/fetch`): free public coordinate fields, with cited provenance. Provide a US coordinate or street address plus fields or a preset. It excludes parcel identity, ownership, assessor attributes, and parcel-dependent data. Use Enrich for those.
- **Batch Fetch** (`POST /v1/fetch/batch`): apply the public field selection to a list of locations. Check each location's result and partial failures. The async `/v1/runs` surface supports Fetch jobs and saved artifacts.
- **Geocode** (`POST /v1/geocode`): free US address-to-coordinate conversion. Inspect accuracy; a coordinate alone is not authoritative parcel identity.
- **Enrich** (`POST /v1/enrich`): authoritative parcel identity and attributes plus public context, at one price per successfully enriched parcel. Read the current schema for locator options and field selection.
- **Search** (`POST /v1/search`): find parcels matching supported filters. Each page has one Search charge that includes the output fields you request. Read the schema for pagination and limits before a sweep.
- **Ask** (`POST /v1/ask`, streaming `/v1/ask/stream`): a cited answer grounded in data. **Ask-site** (`POST /v1/ask-site`) answers questions about a saved site. Each answer costs $0.10 on every plan.
- **Proximity** (`POST /v1/proximity`): distance, nearest, screening, and labor-shed operations. Driving is charged per successful calculation. `max_cost_usd` is a decimal-string spending ceiling; the default is $10 per request. Straight-line proximity and labor estimates are free. There are no credit floors or geocoding surcharges.
- **Field requests** (`POST /v1/field-requests`): free on-demand indexing requests for missing public fields. Poll `/v1/field-requests/{request_id}` for the result; admission and capacity controls still apply.

Lookup is retired (HTTP 410). Resolve and Fetch quote are also retired. Use Enrich for authoritative parcel identity and attributes, Fetch for free public coordinate fields, or Geocode for address-to-coordinate conversion.

**New agent setup:** open [Connect your agent](https://www.mireye.com/onboarding), sign in, copy one private setup prompt, and paste it into your agent. Your API key is included automatically. The setup helper connects supported Claude Code, Codex, and Cursor clients to hosted MCP, installs the Mireye skill, and saves credentials privately for future calls. The first successful location-data call completes setup. Re-copying uses the same eligible key; revoked keys are replaced. Keep the prompt and saved credentials private. Manual hosted OAuth remains available.

## Search and Enrich

For a bounded, executable workflow, use [Parcel Discovery](https://www.mireye.com/templates/parcel-discovery) and its Copy Skill. It includes state-scoped APN and polygon examples, output fields, remarks, cursor recovery and identity checks before a separate Enrich call. [Open its prepared playground request](https://www.mireye.com/dashboard/search?template=parcel-discovery); review the scope and cost before Run.

### `POST /v1/search`

Try the authenticated [Search playground](https://www.mireye.com/integrate?endpoint=search) or use `/dashboard/search`. Both run on your own account; neither spends a shared demo balance.

State is required: include a positive `state2` filter with `eq` for one two-letter code or `in` for a nonempty list. The 50 US states and DC are accepted; case and surrounding whitespace are normalized. A negative `ne` filter alone is insufficient. County is optional: `county` accepts names or five-digit combined state-and-county FIPS strings, preserving leading zeros. County or geometry does not replace state scope. Results follow stored order, not a ranking.

Output is chosen only by `fields`, a list of public Search or Enrich field IDs; there are no presets in Search. Each match carries the identity keys (`parcelnumb`, `address`, `state2`, `county`, `scity`, `szip5`, `source`, `pvd_gisacre`, `analysis_point`) plus one flat `fields` map of filter values and requested output fields, excluding values already present in the identity. Output fields are included in the normal Search page price and never become Search filters. The request body accepts only the documented keys; any other key is a validation error.

The response is `{matches, next_cursor, remarks, request_id, billing}`. `remarks` is always an array and is `[]` when the page has nothing to report. Each remark has `code` and `message`, and may add `path` (for example `fields[2]`), `hint`, `candidates` or `matches`. Branch on `code` and `path` only; show `message` and `hint` as given. Codes: `time_limit_reached`, `source_unavailable`, `candidates_not_checked` (with `candidates`: a qualifying parcel may be missing) and `field_unavailable` (with `path` and `matches`: a requested field is missing on some matches). `next_cursor` is the only signal for more pages: `null` marks the last page, and a short or empty page may still carry a cursor.

Search point measurements use the stored parcel coordinates unchanged, reported as `analysis_point.method: "parcel_stored_lat_lon"`; the point is not guaranteed to be inside the boundary. A missing or invalid pair skips that candidate and is counted in a `candidates_not_checked` remark. Whole-parcel calculations use the original boundary. Search charges per page; the response carries one top-level `billing` receipt.

### `POST /v1/enrich`

Supply a US `address` or both `lat` and `lng`, plus optional individual Enrich `fields` and/or a `preset` list of one or more preset names. Selections combine without duplicates. Start with `fields: ["owner", "slope_degrees"]` or `preset: ["terrain"]`; omitting both selectors or setting both to `null` selects the complete current catalog. An empty `fields` array is invalid for standalone Enrich. Free context remains available inside Enrich at the same parcel price.

Use a 210-second client timeout (for example `curl --max-time 210`) and allow for larger responses when requesting all fields. Standalone Enrich does not share Search's server deadline. Read the [Enrich fields and presets](https://docs.mireye.ai/api-reference/enrich-fields), independently of Fetch presets and Search filters; `GET /v1/meta/fields` describes Fetch. Try the authenticated [Enrich playground](https://www.mireye.com/dashboard/enrich) or [Integrate](https://www.mireye.com/integrate?endpoint=enrich).

Check `parcel_match.status` first: only `matched` returns fields. `ambiguous`, `no_match`, and `unavailable` return empty fields, not proof that the requested facts are absent. For an address, Enrich selects a parcel only from a rooftop-precision geocode; otherwise `parcel_match` is `no_match` with a reason naming the precision, and nothing is charged. Retry with a fuller address or `lat`/`lng`. Do not silently choose an ambiguous parcel. For a match, enumerate the sparse field map dynamically. Failed fields are omitted. An omitted field is not a zero or negative finding. Preserve nested JSON, zero, false, empty strings, empty lists and returned nulls. Point calculations use the recorded `analysis_point`; polygon calculations use the matched boundary.


Standalone Enrich fields contain only `value`, `source`, `confidence`, and `interpretation_hints`, plus `unit` when it is available. Failed fields are omitted.

Search matches carry plain values in `fields`; a requested field that could not be returned for some matches is described by a `field_unavailable` remark rather than per-field metadata. Historical saved Search responses may contain detailed `enrichment.fields`, field statuses, `partial_failures` or compact `enriched_fields` cells; preserve that returned evidence when reading those responses.

Standalone Enrich's `fields` form one flat map in preset order (`parcel`, `zoning`, `buildings`, `valuation`, `legal`, `power`, `access`, `water`, `terrain`, `environment`, `climate`, `hazards`, `market`, `constraints`), with each preset's field order within its group. Fields outside presets follow in catalog order. Overlapping fields appear once in their first group. Standalone Enrich selections keep this order too. Read the current [Enrich catalog](https://docs.mireye.ai/api-reference/enrich-fields); do not hard-code its field count.

## Pricing in USD

Free has no subscription and includes a one-time $10 welcome balance, with no expiry and no recurring refill. Build is $49/month with $49 of usage; Growth is $199/month with $199 of usage. Rates and available balance are dollars, not credits.

| Operation | Free | Build | Growth |
| --- | --- | --- | --- |
| Fetch, Geocode, on-demand indexing | Free | Free | Free |
| Enrich, per successfully enriched parcel | $0.020 | $0.018 | $0.015 |
| Search, per page | $0.200 | $0.180 | $0.150 |
| Driving, per successful calculation | $0.020 | $0.018 | $0.015 |
| Ask and Ask-site, per answer | $0.10 | $0.10 | $0.10 |
| Requests per minute | 20 | 60 | 300 |

Search includes filter values and requested public Search or Enrich output fields in its page price, without duplicating top-level identity values. There is no per-parcel charge in Search. Read the single top-level `billing` receipt and the page `remarks`.

Search has a 180-second server deadline per page; allow 210 seconds in HTTP clients. Reuse `next_cursor` with unchanged filters and fields; limit and `max_cost_usd` may change. Cursors also bind the current dataset receipt, so start a new search after dataset access or publication changes. Every page is a new paid operation, including valid zero-match pages. Use a new `Idempotency-Key` per page and preserve that exact key and body when recovering a lost response. `max_cost_usd` caps the whole call.

Straight-line proximity and labor estimates are free. Free calls still have rate and capacity limits.

Top-ups start at $10 and use the active plan's rates after its monthly allowance runs out. Purchased funds never expire. Auto-recharge requires explicit opt-in. Paid operations stop if available funds or a spending control cannot cover them; no automatic debt or unapproved recharge.

Paid allowances follow the subscription billing day. Unused allowance carries into one additional paid billing period, capped at the upcoming allowance. Carried funds cannot roll again. Build/Growth changes apply at the next renewal.

At Free rates, the $10 welcome balance covers 500 enrichments, 50 search pages, or 100 answers; these are alternatives, not simultaneous grants. It can also cover 20 search pages + 200 enrichments + 20 answers. Free Fetch and Geocode do not consume it.

[Full pricing](https://www.mireye.com/pricing) · [Machine-readable pricing](https://api.mireye.com/v1/meta/plans)

## Authentication and terms

Use `X-API-Key: YOUR_MIREYE_KEY` for direct HTTP calls. New keys start with `mry_`, are shown once, and do not expire unless an expiry is selected. Existing `Authorization: Bearer …` API credentials remain supported for their existing permissions. Send exactly one credential header: duplicate headers or both headers are rejected. Never put keys in URLs.

A verified human signs in, accepts the current terms, and creates a key in the dashboard. Enrich, Search, and licensed parcel access require a new key with the current receipt-bound grants. Accepting terms alone does not upgrade an old key. A lost new key cannot be revealed again; create a replacement and revoke the old key.

Hosted MCP uses OAuth 2.1 + PKCE at `https://api.mireye.com/mcp`. Reconnect and explicitly approve licensed access with the same account after accepting current terms. Refreshing an old OAuth session does not add licensed grants. Local device-code issuance is retired and returns HTTP 410.

Claude Code: `claude mcp add --transport http --scope user mireye-earth https://api.mireye.com/mcp`, then open `/mcp` and complete browser sign-in.

Hosted tools: `mireye_ask`, `mireye_fetch`, `mireye_geocode`, `mireye_enrich`, `mireye_search`, `mireye_proximity`, `mireye_request_field`, `mireye_field_request_status`.

[Authentication details](https://docs.mireye.ai/authentication) · [Hosted MCP setup](https://docs.mireye.ai/mcp/installation)

## Docs

- [API reference](https://docs.mireye.ai/api-reference/fetch)
- [Field catalog](https://docs.mireye.ai/api-reference/field-catalog)
- [Agent guide](https://www.mireye.com/skills.md)
- [OpenAPI schema](https://api.mireye.com/v1/openapi.json)
- [Docs index](https://docs.mireye.ai/llms.txt)
- [Research and writing](https://www.mireye.com/blog)