Routing

Locate — road-network context for one coordinate

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.

get/v1/locate

Request

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

Query parameters

latnumber required

Latitude in decimal degrees, WGS84.

Example:47.6205
lonnumber required

Longitude in decimal degrees, WGS84.

Example:-122.3493
costing'auto' | 'truck' | 'bicycle' | 'pedestrian'

Travel profile that scopes edge access/legality. Defaults to auto.

Example:truck
units'imperial' | 'metric'

Unit system for the human summary. Auto-detected (US/UK/… → imperial) when omitted.

Example:imperial
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.

Example:false

Response

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).

summarystring required

Human/LLM-friendly summary of the road match.

matchedboolean 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.

retryableboolean

Present and true only when road_status is unavailable: the same request may succeed shortly.

timezonestring 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_versionstring 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_mnumber nullable required

Ground elevation in metres. Non-null only when include_elevation=true AND terrain data is available; null otherwise.

elevation_ftnumber nullable required
grade_pctnumber nullable required

Road grade at the point, percent. Reserved — null until an elevation-enhanced road network or verified post-processing are live.

warningsstring[] required
upstream_errorstring nullable

Example response

{
  "road_status": "matched",
  "timezone": "America/Los_Angeles",
  "timezone_status": "resolved",
  "timezone_artifact_version": "2026c-g2-d5dbf146f5c54527"
}

Changes

No recorded changes to this operation across all 1 revision of this API.