--- title: "Resolve a US street address to a coordinate" method: POST path: "/v1/geocode" --- # Resolve a US street address to a coordinate `POST /v1/geocode` ## Request - Base URL: `https://api.mireye.com` - URL: `https://api.mireye.com/v1/geocode` - Auth: none declared - TypeScript: (a function with typed inputs; its response is checked against the schema) Returns a coordinate plus the **quality** of that coordinate. Compose the result with `POST /v1/fetch` for field data at the location. **Read `accuracy_type` before trusting the coordinate.** `rooftop` sits on the parcel; `range_interpolation` is estimated along a street centerline and carries ~2,872 m error at the 95th percentile in rural areas — enough to land on a neighbouring property. `provider` says which upstream answered, as a tier rather than a vendor name: `commercial` normally, `census` when the primary timed out and the free lower-precision fallback took over, `other` for an upstream we have not characterised (treat it as unknown precision). **Centroid-grade results are rejected, not returned.** An address the upstream can only place at a ZIP, city, county or state centroid comes back as `404 address_too_coarse` rather than a confident-looking coordinate for an arbitrary property near a town centre. This is what an unrecognisable address does here: the upstream answers 200 with a centroid instead of admitting no match, so without this check a typo would silently return field data for the wrong land. Distinguish it from `404 address_not_found` (upstream had nothing at all). Retryable failures (`504 geocode_timeout`, `502 geocode_upstream_error`, `429 geocode_busy`) carry `Retry-After`. A `503 geocode_unconfigured` means the service is missing its credential — an operator problem, not a bad request, and not worth retrying. ## Request body - GeocodeRequest - `address` string, required ## Response `200` Successful Response - unknown ## Other responses - `422`: Validation Error --- [API](https://skmtc.dev/mireye/apis/mireye-earth.md) - [All operations](https://skmtc.dev/mireye/apis/mireye-earth/llms.txt) - [OpenAPI document](https://skmtc.dev/mireye/apis/mireye-earth/revisions/d8410ba83654?raw)