---
title: "Locate — road-network context for one coordinate"
method: GET
path: "/v1/locate"
tags: ["Routing"]
---

# Locate — road-network context for one coordinate

`GET /v1/locate`

## Request

- Base URL: `https://geo.thinair.co`
- URL: `https://geo.thinair.co/v1/locate`
- Auth: HTTP bearer

Snap a `(lat, lon)` to the road network and return the matched road's public attributes (name, class, speed limit, access/legality, bridge/tunnel, bearing, snap distance, side of street) plus the timezone. `include_elevation=true` returns terrain-sourced `elevation_m`/`elevation_ft` across North America; outside that coverage they stay `null` with an `elevation_unavailable` warning rather than a guessed value. `grade_pct` stays `null` pending an elevation-enhanced road network. Results may be cached for up to 7 days on a ~65m grid — repeat nearby lookups can return `X-Cache: HIT`.

## Query parameters

- `lat` number, required: Latitude in decimal degrees, WGS84.
- `lon` number, required: Longitude in decimal degrees, WGS84.
- `costing` 'auto' | 'truck' | 'bicycle' | 'pedestrian': Travel profile that scopes edge access/legality. Defaults to `auto`.
- `units` 'imperial' | 'metric': Unit system for the human summary. Auto-detected (US/UK/… → imperial) when omitted.
- `include_elevation` 'true' | 'false' | '1' | '0': Opt-in to look up point elevation (`true`/`1`). Populates `elevation_m`/`elevation_ft` once terrain data is available; until then they stay `null` and an `elevation_unavailable` warning is emitted. `grade_pct` stays `null` regardless — it needs an elevation-enhanced road network.

## Response `200`

Road-network context. `matched:false` (with `road:null`) is a valid 200: `road_status` says whether no routable road is near the point (`no_road_nearby`) or the road lookup could not be answered (`unavailable`, with `retryable:true`).

- LocateResponse
  - `summary` string, required: Human/LLM-friendly summary of the road match.
  - `matched` boolean, required
  - `road_status` 'matched' | 'no_road_nearby' | 'unavailable', required: Why `road` is what it is. `matched` - a routable road was found. `no_road_nearby` - the road lookup answered and found no routable road for this travel profile (a real answer; may be cached). `unavailable` - the road lookup could not be answered right now; this says nothing about the point, `matched` is `false`, `road` is `null`, `retryable` is `true`, and the result is never cached. The timezone and elevation fields are still resolved.
  - `retryable` boolean: Present and `true` only when `road_status` is `unavailable`: the same request may succeed shortly.
  - `location` object, required
    - `lat` number, required
    - `lon` number, required
  - `road` LocateRoad, nullable, required
    - `name` string, nullable, required
    - `road_class` string, nullable, required
    - `speed_limit_kph` number, nullable, required
    - `speed_limit_mph` number, nullable, required
    - `bearing` number, nullable, required
    - `distance_m` number, nullable, required
    - `distance_ft` number, nullable, required
    - `side_of_street` 'left' | 'right' | 'unknown', required
    - `truck_legal` boolean, nullable, required
    - `has_toll` boolean, required
    - `has_ferry` boolean, required
    - `has_highway` boolean, required
    - `bridge` boolean, required
    - `tunnel` boolean, required
  - `timezone` string, nullable, required: IANA timezone name for the point (e.g. `America/Los_Angeles`), resolved by point-in-polygon against published timezone boundaries. Null unless `timezone_status` is `resolved` — an absent timezone is reported rather than an estimated one. Contains information from timezone-boundary-builder, which is made available under the Open Database License (ODbL) v1.0. Timezone boundaries © OpenStreetMap contributors. US legal-zone cross-check: U.S. Department of Transportation, Bureau of Transportation Statistics (public domain).
  - `timezone_status` 'resolved' | 'boundary_ambiguous' | 'source_conflict' | 'not_covered' | 'unavailable', required: Why `timezone` is what it is. `resolved` — exactly one zone contains the point, clear of every boundary. `boundary_ambiguous` — on or within the documented boundary tolerance of an edge, or claimed by two zones. `source_conflict` — the boundary data and the US legal-zone layer disagree here. `not_covered` — no zone polygon contains the point. `unavailable` — no verified boundary artifact is active. Only `resolved` carries a name.
  - `timezone_artifact_version` string, nullable, required: Version of the timezone boundary artifact that produced this answer. Changes when the data is promoted, and participates in this endpoint's cache identity so an answer cannot outlive the data it came from.
  - `elevation_m` number, nullable, required: Ground elevation in metres. Non-null only when `include_elevation=true` AND terrain data is available; `null` otherwise.
  - `elevation_ft` number, nullable, required
  - `grade_pct` number, nullable, required: Road grade at the point, percent. Reserved — `null` until an elevation-enhanced road network or verified post-processing are live.
  - `geojson` LocateGeoJson, required
    - `type` 'FeatureCollection', required
    - `features` object[], required
      - `type` 'Feature', required
      - `geometry` object, required
        - `type` 'Point', required
        - `coordinates` unknown[], required
          - unknown
      - `properties` object, required
  - `warnings` string[], required
  - `meta` LocateMeta, required
    - `upstream_ms` number, required
    - `feature_count` number, required
    - `cacheHit` boolean: True when the result was served from the edge grid cache (no upstream call).
    - `units` 'imperial' | 'metric', required
    - `include_elevation` boolean, required
    - `degraded` boolean: Present and `true` only when `road_status` is `unavailable`: the road lookup could not be answered, so the result carries the timezone (and elevation, when requested and available) but no road information.
    - `elevation_source` 'terrain', nullable, required: Provenance of `elevation_m` — `terrain` when sampled from terrain/DEM data, or `null` when unavailable.
  - `upstream_error` string, nullable

## Other responses

- `400`: Invalid coordinates or query parameters.
- `429`: Quota exceeded.
- `502`: Upstream routing engine unavailable.

---

[API](https://skmtc.dev/thinair/apis/thinair-geo-api.md) · [All operations](https://skmtc.dev/thinair/apis/thinair-geo-api/llms.txt) · [OpenAPI document](https://skmtc.dev/thinair/apis/thinair-geo-api/revisions/8fac2d5e4b34?raw)