Quickstart

This walkthrough makes three real API calls. No SDK, no install — just curl, jq, and a Mireye API token. We’ll ask about a Manhattan rooftop, fetch the same location’s flood-risk preset, and then wire up the hosted MCP server for Claude Code.

1. Pick a coordinate

Use any US lat/lng. We’ll use the corner of Beekman and Park Row in lower Manhattan, near City Hall:

lat = 40.7128
lng = -74.0060

The primary accepted coordinate envelope is lat ∈ [18, 72], lng ∈ [-180, -65] (lower 48, Alaska, Hawaii, US territories). The Western Aleutians additionally accept lat ∈ [51, 54], lng ∈ [172, 180). Anything outside those two regions returns 400 coord_out_of_bounds.

Starting from an address?

If your user typed an address, you do not need to resolve it first — /v1/fetch and /v1/ask both accept an address in place of lat/lng, and hand back the same quality information in a geocode block. Use POST /v1/geocode when you want the coordinate on its own — to inspect before using the coordinate, or to reuse across calls:

curl -s https://api.mireye.com/v1/geocode \
  -H "X-API-Key: $MIREYE_API_TOKEN" \
  -H 'content-type: application/json' \
  -d '{"address": "350 5th Ave, New York, NY 10118"}' | jq

{
  "lat": 40.748377,
  "lng": -73.984854,
  "accuracy_type": "rooftop",
  "normalized_address": "350 5th Ave, New York, NY 10118",
  "provider": "commercial"
}

Check accuracy_type before you use the coordinate: rooftop is on the parcel, range_interpolation is an estimate along the street and can be kilometres off in rural areas. Details on the geocode page.

2. Get an API key

Sign in at www.mireye.com, accept the current Earth terms, and create a compact API key in the dashboard. Store it privately:

export MIREYE_API_TOKEN="<paste from dashboard>"

See Authentication for the other credential paths (compact API keys for HTTP and OAuth for hosted MCP).

3. Ask a question

A completed answer costs $0.10 on every plan. Set MIREYE_OPERATION_KEY once for this answer, and reuse that key and body to recover a lost response. Choose a new key only for a new operation. Free Fetch below does not spend wallet funds.

: "${MIREYE_OPERATION_KEY:?Set one stable operation key before this paid request}"

curl --max-time 120 -s https://api.mireye.com/v1/ask \
  -H "X-API-Key: $MIREYE_API_TOKEN" \
  -H "Idempotency-Key: $MIREYE_OPERATION_KEY" \
  -H 'content-type: application/json' \
  -d '{
    "lat": 40.7128,
    "lng": -74.0060,
    "question": "What is the elevation here?",
    "max_cost_usd": "0.10"
  }' | jq

Response:

{
  "lat": 40.7128,
  "lng": -74.006,
  "question": "What is the elevation here?",
  "answered_at": "2026-06-12T07:29:37.353451+00:00",
  "answer": "The ground elevation at coordinate 40.7128, -74.006 is 13.15 meters above sea level (NAVD88 datum), per USGS 3DEP/EPQS at ~10m resolution. This elevation is above the 10-meter storm-surge exposure threshold, though proximity to the coast would warrant further review in conjunction with flood zone and coastal distance data for a complete flood-risk assessment.",
  "confidence": "high",
  "citations": [
    {
      "source": "USGS_EPQS",
      "source_url": "https://epqs.nationalmap.gov/v1/json?x=-74.006&y=40.7128&wkid=4326&units=Meters",
      "fields": [
        "elevation"
      ],
      "fetched_at": "2026-06-12T07:29:40.330095+00:00",
      "confidence": "high"
    }
  ],
  "fields_used": [
    "elevation"
  ]
}

What just happened:

The planner (Claude Sonnet 4.6) read the question, looked at the field catalog, and decided only elevation was needed.
The terrain layer fetched 3DEP elevation for the coordinate.
The synthesizer (also Claude Sonnet 4.6) wrote the prose answer, grounded in the fetched value, and the citation engine attached the source.

Read the fields top-to-bottom: answer is the prose, confidence summarizes the whole response, citations is the audit trail, and fields_used lists exactly which catalog fields the answer depends on.

4. Fetch raw fields

When you know what you want, skip the planner and hit /v1/fetch:

curl -s https://api.mireye.com/v1/fetch \
  -H "X-API-Key: $MIREYE_API_TOKEN" \
  -H 'content-type: application/json' \
  -d '{
    "lat": 40.7128,
    "lng": -74.0060,
    "fields": ["elevation", "coast_distance_m"]
  }' | jq

Response:

{
  "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": []
}

Each field is a self-contained record with provenance inline. The partial_failures array is empty here; on a call where the LCMS source times out, that field gets moved to partial_failures with retryable: true and the rest of the call still returns 200. Skip the field list entirely and use a preset for common workflows:

curl -s https://api.mireye.com/v1/fetch \
  -H "X-API-Key: $MIREYE_API_TOKEN" \
  -H 'content-type: application/json' \
  -d '{"lat": 40.7128, "lng": -74.0060, "preset": "flood_risk"}' | jq '.fields | keys'

[
  "coast_distance_m",
  "elevation",
  "intersects_nhd_area",
  "intersects_wetland",
  "nearest_waterbody_name",
  "nearest_wetland_distance_m",
  "surface_water_permanence_pct",
  "wetland_acres",
  "wetland_subtype",
  "wetland_type",
  "wetlands_within_100m_count",
  "wetlands_within_500m_count",
  "within_floodplain_polygon"
]

All presets and their field expansions are listed at /api-reference/fetch.

5. Use it from Claude Code

For guided setup (Claude Code, Codex, or Cursor), open Mireye setup, sign in, accept the current terms, and copy the setup prompt into your agent. The mireye-mcp 0.7.2 helper configures hosted MCP and installs the use-mireye skill. It saves your scoped API key privately and proves a free HTTP Fetch. The page completes when the server observes that successful call; the client still completes its own OAuth authorization for hosted MCP. Repeated copies reuse an eligible setup key. For manual hosted setup: If you previously configured a local stdio server named mireye-earth, remove it first:

claude mcp remove mireye-earth -s user

Add the hosted MCP endpoint:

claude mcp add --transport http --scope user mireye-earth https://api.mireye.com/mcp

Restart Claude Code, run /mcp, and complete the browser sign-in flow. Eight tools are then available: mireye_ask, mireye_proximity, mireye_fetch, mireye_geocode, mireye_enrich, mireye_request_field, mireye_field_request_status, and mireye_search. Ask Claude:

“What’s the elevation at 40.7128, -74.0060?”

Claude will call mireye_ask, get the cited answer back, and surface the citation in chat. See /mcp/installation for Cursor and custom-agent setup.

6. Self-discover the catalog

Long-lived clients (agents, services) should fetch the catalog once at startup and cache it for an hour. This endpoint is public — no token needed:

curl -i https://api.mireye.com/v1/meta/fields | head -20

The response sets ETag and Cache-Control: public, max-age=3600. Subsequent requests with If-None-Match: "<etag>" return 304. See /api-reference/meta-fields for the full flow. This endpoint describes Fetch fields and presets; use the Search field reference and Enrich field reference for those operations.

What’s next

POST /v1/ask

The natural-language endpoint. Two-model planner + synthesizer.

POST /v1/fetch

Fields, presets, and partial_failures semantics.

POST /v1/search

Find a parcel shortlist using typed filters.

POST /v1/enrich

Resolve one parcel and investigate selected attributes.

MCP tools

Choose between questions, field fetches, parcel search, and enrichment.

POST /v1/ask/stream

Same answer, first tokens in about five seconds.

Pricing in dollars

What each call costs, and how to quote a job first.

POST /v1/runs

Screen thousands of locations in one job.

Get started

Workflows

1. Pick a coordinate

Starting from an address?

2. Get an API key

3. Ask a question

4. Fetch raw fields

5. Use it from Claude Code

6. Self-discover the catalog

What’s next

POST /v1/ask

POST /v1/fetch

POST /v1/search

POST /v1/enrich

MCP tools

POST /v1/ask/stream

Pricing in dollars

POST /v1/runs

​1. Pick a coordinate

​Starting from an address?

​2. Get an API key

​3. Ask a question

​4. Fetch raw fields

​5. Use it from Claude Code

​6. Self-discover the catalog

​What’s next

POST /v1/ask

POST /v1/fetch

POST /v1/search

POST /v1/enrich

MCP tools

POST /v1/ask/stream

Pricing in dollars

POST /v1/runs

1. Pick a coordinate

Starting from an address?

2. Get an API key

3. Ask a question

4. Fetch raw fields

5. Use it from Claude Code

6. Self-discover the catalog

What’s next