Documentation menu
Boundaries, coordinates and time zones
GET/v1/boundaries
Access and price
| Auth | An API key, as Authorization: Bearer snk_… or ?api_key=snk_…. Metered. Needs a full key; a browser (maps) key is refused. |
|---|---|
| Price | 1 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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| q | query | string | no | A 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 |
| near | query | string | no | lat,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 |
| level | query | string | no | OSM 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) |
| country | query | string | no | ISO 3166-1 alpha-2 country to keep |
| limit | query | integer | no | Candidates, 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| Field | Type | Required | Description |
|---|---|---|---|
| attribution | string | no | Boundary data attribution. |
| boundaries | object[] | no | Matches: 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. |
| licence | string | no | Boundary 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 parameterapplication/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 keyapplication/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+jsonapplication/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