Mireye

/api-reference/geocode

POST /v1/geocode

cURL

curl --request POST \
  --url https://api.example.com/v1/geocode \
  --header 'Content-Type: application/json' \
  --data '
{
  "address": "<string>"
}
'

Resolve a US street address to a coordinate, with the quality of that coordinate.

cURL

curl --request POST \
  --url https://api.example.com/v1/geocode \
  --header 'Content-Type: application/json' \
  --data '
{
  "address": "<string>"
}
'

​ When to use this

​ Request shape

​ Example: a rooftop match

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

​ Read accuracy_type before you trust the coordinate

curl -s https://api.mireye.com/v1/geocode \
  -H "Authorization: Bearer $MIREYE_API_TOKEN" \
  -H 'content-type: application/json' \
  -d '{"address": "2470 Hunter Rd, Kyle, TX 78640"}' | jq
  • rooftop / nearest_rooftop_match — safe for parcel-level work.
  • anything else — treat as approximate. Show the user normalized_address and let them confirm before you act on it.

​ Vague addresses are rejected, not guessed

curl -s -i https://api.mireye.com/v1/geocode \
  -H "Authorization: Bearer $MIREYE_API_TOKEN" \
  -H 'content-type: application/json' \
  -d '{"address": "Manhattan, NY"}'

​ Two more ways a request is refused

​ Known limitation: US territories

Text
asked:  1 Calle Fortaleza, San Juan,  PR 00901
got:    1 Calle E,         San Juan,  PR 00926     accuracy 0.99

asked:  1 Marine Corps Dr, Hagatna,   GU 96910
got:    1 Marine Corps Dr, Barrigada, GU 96913     accuracy 0.94

​ Response shape

​ The fallback, and why provider matters

​ Errors

​ Limits

  • One address per request. No batching in V1; loop client-side.
  • 256 characters maximum, rejected rather than truncated.
  • Successful results are cached for 30 days; “no such address” for 24 hours. A repeat lookup of the same address within the window is free and instant, and the cache expires on the same 30-day clock as everything else we keep — this page used to say “a year” here while promising 30 days two sections down, and both could not be true. The cache key is normalized for form only — case, spacing, accents and punctuation, except -, # and /, which carry meaning (12-34 Queens house numbers, # 4 units, 123 1/2 half-addresses) — so 350 5th Ave and 350 5TH AVE are one entry. It deliberately does not treat Parkway and Pkwy as the same word: doing that safely requires knowing which token is the street suffix, and guessing merges real streets whose name is a suffix word (Northern Blvd would collapse into N Blvd). Two spellings of one address therefore cost two lookups. That is the intended trade — a duplicate lookup is cheap, a merged cache entry would hand you a different property’s coordinate. A negative is deliberately short-lived: an address the provider has not ingested yet starts working the moment it does, and a month-long 404 would outlast the truth by months.
  • Worst case 5.5 s (3 s primary + 2.5 s fallback). Set your client timeout above that.
  • US only. Feed the coordinate to /v1/fetch or /v1/ask, both of which enforce the US envelope.

​ What we keep

  • The audit record (address as typed, coordinate, geocode block) sits in monthly partitions; a scheduled job drops each one once its whole month is past the cutoff, so a record lives 30 to about 60 days depending on when in the month it was created.
  • The result cache (the matched address and coordinate, keyed by a digest of your input, kept so a repeat lookup does not re-bill) expires at 30 days via the store’s own TTL — no job involved, so it cannot quietly stop.

Successful Response