Skip to content
Documentation menu
docs / api / get-v1-boundaries
Boundaries, coordinates and time zones

GET/v1/boundaries

Access and price

AuthAn API key, as Authorization: Bearer snk_… or ?api_key=snk_…. Metered. Needs a full key; a browser (maps) key is refused.
Price1 call per request. Class: standard. Published as unit_rules.default in /pricing.json.

What it does

GET /v1/boundaries?q=&near=&level=&country=&limit=.

Call it

bash
curl -fsS -X GET "https://api.mapmap.ai/v1/boundaries" \
  -H "Authorization: Bearer $MAPMAP_KEY"

Parameters

NameInTypeRequiredDescription
qquerystringnoA name, matched word by word from the start of each word, case and accents folded: camden finds "London Borough of Camden", mosc finds "Москва" by its English name. Searches name, name:en, the alternative names and the ISO code
nearquerystringnolat,lon. With q, the nearest match first (distance to its box, 0 inside it). Without q, exactly the boundaries whose polygon contains the point, coarsest level first
levelquerystringnoOSM admin_level(s) to keep, 2 to 10, comma separated: 2 country, 4 region or federal subject, 5 to 8 county, district or borough, 9 and 10 parish or municipal district (the meaning of a level varies by country)
countryquerystringnoISO 3166-1 alpha-2 country to keep
limitqueryintegernoCandidates, 1 to 50 (default 10) Limits: at least 0.

Responses

200{boundaries: [{boundary_id, name, name_en, admin_level, country, iso_code, area_km2, bbox, territory, contains_near?, distance_km?}], attribution, licence}. area_km2 is the area of the stored, simplified polygon: the figure a custom region by this boundary is limited on. An empty list is a valid answer
FieldTypeRequiredDescription
attributionstringnoBoundary data attribution.
boundariesobject[]noMatches: boundary_id (for GET /v1/boundaries/{id}), name, admin_level, iso_code, country, territory, bbox, area_km2, and with near the distance_km and contains_near.
licencestringnoBoundary data licence, e.g. ODbL-1.0.

Example: Recorded from the hosted gateway on 2026-11-05 with a test key: GET /v1/boundaries?near=50.8290,-0.1410&limit=3; lists trimmed to their first items

json
{
  "attribution": "© OpenStreetMap contributors",
  "boundaries": [
    {
      "admin_level": 2,
      "area_km2": 403952.089,
      "bbox": [
        -14.015517,
        49.674,
        2.091912,
        61.061
      ],
      "boundary_id": "osm-r62149",
      "contains_near": true,
      "country": "GB",
      "distance_km": 0,
      "iso_code": "GB",
      "name": "United Kingdom",
      "name_en": null,
      "territory": "uk"
    },
    {
      "admin_level": 4,
      "area_km2": 180103.476,
      "bbox": [
        -6.704727,
        49.674,
        2.091904,
        55.917
      ],
      "boundary_id": "osm-r58447",
      "contains_near": true,
      "country": "GB",
      "distance_km": 0,
      "iso_code": "GB-ENG",
      "name": "England",
      "name_en": null,
      "territory": "uk"
    }
  ],
  "licence": "ODbL-1.0"
}
400Neither q nor near, or a malformed parameter

application/problem+json · Problem

401Missing or invalid API key. Also: No key, or a missing, malformed, unknown, revoked or expired one (unauthorized); the body carries signup, docs and a one-call hint for a free key

application/problem+json · Problem

402Beyond the included volume with no way to pay this call: an x402 body naming how to pay (provisional key past its allowance, prepaid balance below the price, or a rejected X-PAYMENT). Not problem+json

application/json · X402PaymentRequired

403The key may not call this: a browser key outside its scope (scope-insufficient), a request from an origin the key does not allow (origin-not-allowed), or an account restriction (forbidden)

application/problem+json · Problem

429Quota or rate limit exceeded. Also: Per-key rate limit (rate-limited, with Retry-After), or monthly quota exhausted with no payment path (quota-exceeded)

application/problem+json · Problem

501Boundaries by name not enabled (SN_BOUNDARIES_DIR unset)

application/problem+json · Problem

504The request did not finish within the gateway's request deadline (request-timeout)

application/problem+json · Problem

Error bodies follow the shared problem model documented on API conventions.

Also under Boundaries, coordinates and time zones

Generated from https://api.mapmap.ai/openapi.json on 2026-11-12 · operationId get_boundaries