Places

Search places by category or text near a point

Category-specific POI search near a point — gas stations, truck stops, restaurants, charging stations, etc. Provide either query or center coordinates (or both). For broader discovery use /v1/explore.

get/v1/places

Request

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

Query parameters

locationstring

Center point — free-text address or 'lat,lon' string.

Example:Houston, TX
latnumber

Center latitude (alternative to location).

Example:29.7604
lonnumber

Center longitude (alternative to location).

Example:-95.3698
querystring

Free-text place query (alternative to category). One of query or category is required — a bare center (lat+lon) with neither is rejected with a 400.

Example:truck stop
categorystring[]

Structured categories (repeatable / CSV): food, fuel, charging_station, education, health, entertainment, retail, accommodation, nightlife, transport, government, recreation. One of category or query is required — a bare center (lat+lon) with neither is rejected with a 400.

[
  "food",
  "fuel"
]
radiusstring

Search radius. Bare numbers are miles unless units is set — radius=30 is 30 miles, radius=5&units=kilometers is 5 km; kilometers via units or a km suffix ('5km'); aliases mi/km/imperial/metric. A value carrying its own unit suffix ('30mi', '5km') is also accepted and its suffix wins. Default 50 km (about 31 mi); maximum 50 km (up to 31.068 mi). Preferred over radius_m.

Example:30
units'miles' | 'kilometers'

Units for a bare numeric radius: miles (default) or kilometers; aliases mi, mile, imperial (miles) and km, kilometer, kilometre, kilometres, metric (kilometers), case-insensitive, echoed as miles|kilometers. An empty units= is treated as absent. Ignored when radius already carries a unit suffix (a contradicting pair is rejected). Not valid with radius_m alone — radius_m is always meters, so that pair is rejected rather than silently ignored. On its own (no radius) it does not supply a radius — the default 50 km applies — but it selects the display unit of the units echo.

Example:miles
radius_minteger

Search radius in meters (0..50000 — i.e. up to 50 km / ~31 mi; 0 means 'not supplied' and applies the default 50 km, as on the MCP tool). Accepted alias; radius + units is the preferred form. Sending both is only valid when they agree. Do not pair with units — radius_m is always meters and the pair is rejected.

Example:1000
limitinteger

Max results (default 10, clamped 1..50).

Example:10
layersstring

Restrict to: venue, address.

Example:venue

Response

Places results — items list with optional rich metadata.

querystring required
radiusstring

Legacy echo — the applied radius as '<n>m'. Present only when the request supplied a radius (any form); absent on the default path. Prefer radius_km + units.

radius_kmnumber

Search radius actually applied, in kilometers (the canonical unit) — 50 on the default path. Present on every center-based search, cache hit or miss; absent on the text-only path (no center), where no radius applies.

units'miles' | 'kilometers'

Display unit for the radius: the request's units if sent; else the unit of a suffixed radius string; else kilometers for radius_m; else miles — the platform default, which also covers a bare numeric radius and the no-input path. Same presence rules as radius_km.

upstream_errorstring nullable
raw_upstream_payloadunknown

Example response

{
  "warnings": [
    {
      "code": "category_text_mismatch"
    }
  ],
  "radius": "48280m",
  "radius_km": 50,
  "units": "miles",
  "items": [
    {
      "id": "ta_place_8f3a2c9e61c04d58"
    }
  ]
}

Changes

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