ThinAir Geo

geocode

Convert an address, place name, street, or intersection into coordinates and structured location results. Use when input is text and you need coordinates before routing, weather, or search. Supports street-level resolution and proximity biasing.

geocode_structured

Geocode from discrete address components (address, locality, region, postalcode, country) instead of one free-text string. Use when the input is already fielded (forms, CRM records, stop tables) — skips free-text parsing so components can't be mis-tokenized. At least one component is required. No cross-street field: for named intersections use resolve_intersection or geocode.

reverse_geocode

Converts a coordinate pair into the nearest addresses, streets, venues, or administrative places, ordered by proximity. Use when starting from GPS or a map position; for text-to-coordinates use geocode, and for a point's road-network context (name, class, speed limit, legality) use locate instead. Read-only and cached. Near the poles (|lat| = 85 degrees) the index is too sparse for a real nearest match, so this returns no results rather than a distant wrong guess. Returns up to size candidates (default 5, max 40); layers restricts the type returned (address, street, venue, neighbourhood, locality, county, region, country, postalcode, and more). Each result carries a confidence score, layer, label, and coordinates, same shape as geocode.

directions

Generate routes, ETAs, and turn-by-turn directions between locations. Live traffic is post-route ETA enrichment and does not change the returned path (path_influenced=false); truck traffic adjustments are slowdown-only. Supports car / truck / motorcycle / pedestrian / bicycle, with hazmat + dimension + toll avoidance for commercial routing. ETAs are returned as ISO 8601 with timezone offset (in the destination's local timezone). Use vehicle_profile presets (10 total — DRY_VAN_53, FLATBED_48/_40, STEP_DECK, TANKER, BOX_TRUCK_26, AUTO_CARRIER, SPRINTER_VAN, DOUBLE_TRAILER, OVERSIZE) when routing trucks — they set height/weight/length in one parameter.

traffic

Retrieve live traffic conditions, congestion, and speed for a location. Use when traffic is needed independently of routing — for corridor monitoring, area congestion, or incident checks. COVERAGE: live data for ~30 major US metros; returns degraded or empty values outside these areas. For rural coordinates, qualify the response (e.g. 'no live traffic coverage here — showing free-flow speeds').

locate

Snap one coordinate to the road network and return the matched road's context: name, road class, speed limit, bearing, snap distance, side of street, truck legality, and toll/ferry/highway/bridge/tunnel flags — plus the IANA timezone. Use to answer 'what road is this point on and what are its rules?' for fleet/telematics snapping, geofence edge checks, or enriching a GPS fix. Set include_elevation for terrain-sourced point elevation_m; grade_pct is a forward-compatible field that stays null for now. Read road_status, not matched alone: matched — a road was found and road is filled; no_road_nearby — a real answer: no routable road is near the point for this travel profile; unavailable — the road lookup could not be answered right now, so matched:false / road:null say nothing about the point, retryable is true, and the timezone and any requested elevation are still looked up separately (see timezone_status and warnings). Never a guess.

weather

Get current and forecast weather for a location, including severe weather alerts and minute-by-minute precipitation. Use for destination conditions, travel planning, or route risk assessment.

isochrone

Computes reachability polygons: the area reachable from an origin within given travel-time or travel-distance bands. Use for service coverage, dispatch range, territory design, and 'how far can I get in X minutes' questions; use directions or distance_matrix for a route or distance between specific points instead. Pass multiple bands in one call (contours_minutes:[10,20,30]) for nested polygons in one response, up to 4 bands, defaulting to 15/30/60-minute driving bands if none given. location accepts an address string or 'lat,lon'. costing selects the travel profile (auto default, or truck/bicycle/pedestrian/motorcycle). Read-only and cached. Returns a GeoJSON FeatureCollection of nested polygon contours, one per band.

search_places

CATEGORY-specific POI search near a point — gas stations, truck stops, restaurants, charging stations, etc. Use this when the user has a specific TYPE of place in mind (food / health / retail / fuel / accommodation / nightlife / transport / government / recreation). For broader DISCOVERY (e.g. 'cities within 50 miles' or 'venues by population'), use explore instead.

batch_geocode

Geocode multiple addresses in one request with structured per-record results. Use for bulk operations instead of repeated single geocode calls. Max 50 per batch.

explore

BROWSING / DISCOVERY search — administrative places (cities, neighbourhoods, boroughs, counties, regions) near a location. Use this when the user is exploring a REGION rather than looking for a specific category. Supports population filtering ('cities 100k'), ranking by significance or distance, and layer filtering (locality / neighbourhood / borough / county / region). Venues, addresses and streets are NOT served here — for venues and POI categories (gas, food, charging, etc.) use search_places instead. Each result carries its distance in the caller's units and a bearing from the center.

resolve_intersection

Resolve a NAMED cross-street (street1 × street2 within a locality/region/country) to a single best coordinate with a confidence score and a fleet-safe fallback. High-confidence tier matches US-metro highway corners; named non-highway streets resolve via the geocoder fallback. For free-form streets use geocode.

distance_matrix

Compute road distances and travel times for every origin → destination pair. Endpoints accept free-text addresses or 'lat,lon' strings; N × M is capped at 625 pairs. Use for fleet dispatch, nearest-depot, and bulk ETA tables. Durations do NOT include live or historical traffic — see duration_basis; use directions for a traffic-adjusted ETA between two specific points.

map_match

Map matching snaps raw GPS breadcrumbs to the road network. Feed a recorded trace (2–100 points) and get back the road-accurate route that was actually driven: matched geometry, distance, time, road names, and a 0–1 match confidence. matched: true only means a route was returned — gate on match_status: full when every input point was matched or interpolated onto the road network and the match is one continuous section, none when no point was, otherwise partial. coverage gives the per-point counts, unmatched_ranges (0-based input indexes that did not match) and route_sections (above 1, the geometry, distance and time cover only the first section — split the trace there). match_status is null, with coverage.unavailable_reason, when the per-point check could not be completed. Sparsely-reported traces (consecutive fixes farther apart than the default breakage distance — e.g. fleet units reporting every several minutes on a highway) can split into multiple sections; increase breakage_distance_m to keep them as one. Total matched distance is limited to 200 km per call — split longer sparse traces by distance, not only by the 100-point cap. Use for fleet trace cleanup, mileage from GPS logs, and reconstructing routes from telemetry. road_names come from the route's maneuver points, so they cover the roads the route turns onto or starts on — for the name of every segment actually travelled, use trace_attributes. For planning a route between places, use directions instead.

trace_attributes

Trace attributes return road/network attributes for matched traces. Feed a GPS breadcrumb trail (2–100 points) and get per-segment road names, road classes, speed limits, surfaces, truck-route flags, and segment lengths along the matched route, plus a matcher confidence score. Sparsely-reported traces (consecutive fixes farther apart than the default breakage distance — e.g. fleet units reporting every several minutes on a highway) can split into multiple sections; increase breakage_distance_m to keep them as one. Total matched distance is limited to 200 km per call — split longer sparse traces by distance, not only by the 100-point cap. Use to audit what roads a vehicle actually used (speed-limit compliance, truck-route adherence, surface checks). For just the matched route line, use map_match.

geofence_contains

Tests one or more points for containment inside a polygon you supply as GeoJSON (Polygon, MultiPolygon, or a Feature/FeatureCollection wrapping one). Pure geometry against your own shape - it does not search a place index, so use explore or search_places to find what's near a point instead. Boundary points count as contained. Up to 1000 points per call, against a polygon of up to 100 rings/parts and 1000 positions per ring; larger inputs are rejected. Runs locally with no external lookup, but still counts as one metered request like other tools, so batch points into a single call rather than looping. Errors, rather than returning false, when the polygon is structurally invalid. Returns one boolean per point, in order, plus contained_count and point_count.

place_get

Look up a place by its stable ThinAir id (ta_place_… / ta_intersection_…) as returned in the id field of geocode, reverse_geocode, search_places, or resolve_intersection results. Ids are deterministic and survive re-serves — safe to store as favorites or foreign keys. Returns the canonical name, label, layer, and coordinates. Unknown or expired ids error with re-search guidance.

quota

Check current usage, remaining limits, plan, and quota breakdown for the caller. FREE TO CALL — never counts against your quota, never blocked by it. Use this proactively when the user asks about usage or seems near limits.

issue_api_key

Issue a fresh ta_geo_ API key for ThinAir GEO (geocoding/routing) for your current authenticated user/tenant, and rotate: any previous key keeps working for one hour, then stops — the response reports how many and exactly when (previous_keys_retiring, previous_keys_retire_at). Use it to rotate, or when a CLI/MCP client needs a key and can't reach the console. The new key is tied to your existing plan. Counts as 1 query against your daily quota. NOTE: this key works ONLY against ThinAir Geo — it does NOT authenticate against ThinAir Data, which issues its own ta_data_ key from its own identically-named tool.