Places

Explore administrative places near a point

Browsing / discovery search — administrative places (cities, neighbourhoods, boroughs, counties, regions) near a location. Supports population filtering, ranking by significance or distance, and per-layer radius policy. Venues and points of interest are served by /v1/places, not here.

get/v1/explore

Request

Base URL: https://geo.thinair.co
URL: https://geo.thinair.co/v1/explore
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

layersstring

Comma-separated layers: locality, neighbourhood, borough, county, region (default locality). venue, address and street are not served here — use /v1/places for venues and points of interest. An unsupported or unknown layer is rejected with 400 INVALID_QUERY.

Example:locality,neighbourhood

radiusstring

Search radius. Bare numbers are miles unless units is set — radius=30 is 30 miles, radius=30&units=kilometers is 30 km; kilometers via units or a km suffix ('150km'); aliases mi/km/imperial/metric. A value carrying its own unit suffix ('150km', '30mi') is also accepted for compatibility and its suffix wins. Per-layer policy: locality / county / region default 150 km (93.206 mi) and cap at 500 km (~310 mi); neighbourhood / borough default 25 km (15.534 mi) and cap at 100 km (~62 mi). A request naming several layers takes the TIGHTEST default and cap among them. An over-maximum radius returns HTTP 200 with a structured_error of radius_exceeds_max naming the governing cap and no items.

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). On its own it does not supply a radius — the default is per layer (150 km for locality/county/region, 25 km for neighbourhood/borough; a mixed request takes the tightest) — but it selects the display unit of meta.radius / meta.units.

Example:miles

sizeinteger

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

Example:10

min_populationinteger

Minimum population filter; applied JS-side.

Example:100000

sort'population' | 'distance' | 'combined'

Ranking basis (default: population — significance, using population where the source has it, with distance as the tiebreak). distance is nearest first; combined blends population against a distance decay. The basis applied is echoed in meta.ranking.

boundary_countrystring

ISO 3166-1 alpha-2 or alpha-3 country code restriction.

Example:US

Response

Explore results — items list with optional upstream_error fallback.

upstream_errorstring nullable

Example response

{
  "items": [
    {
      "layer": "locality",
      "population": 2314157,
      "distance_km": 12.4,
      "distance": 7.7,
      "distance_unit": "miles",
      "bearing": 315,
      "coordinates": {
        "lat": 29.7604,
        "lon": -95.3698
      }
    }
  ],
  "meta": {
    "radius_km": 150,
    "radius": 93.206,
    "units": "miles",
    "layers": [
      "locality"
    ],
    "ranking": "population desc, distance asc",
    "total_candidates": 412
  },
  "structured_error": {
    "code": "radius_exceeds_max"
  }
}

Changes

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