{"openapi":"3.1.0","info":{"title":"Mapbase Engine API","version":"0.0.0","description":"The **Mapbase Engine** is the public HTTP API for Mapbase products.\n\nThis reference is generated from the same Zod/OpenAPI contracts that the\nengine uses at runtime.\n\n## Base URL & versioning\n\nAll stable API routes live under `/v1`. Utility routes (`/health`, `/redis-health`, `/layers`, `/openapi.json`, `/reference`) sit outside the versioned contract and do not require authentication.\n\n`/v1` is a stable contract: we add fields, routes, and optional parameters without bumping the version, but we never remove a field or make a breaking change to an existing one within `/v1`. A breaking change ships under a new prefix (`/v2`). Clients should ignore unknown response fields so additive changes are non-breaking for them.\n\nSend an `x-sdk-version` header (the official SDK sets it automatically) so we can attribute traffic and warn about outdated clients. When a route is slated for removal it is first marked `deprecated` in this spec and serves a `Deprecation` header (and, once a removal date is set, a `Sunset` header) for at least one deprecation window before it is retired.\n\n## Layers\n\nRegistry data is grouped into three **layers**: `locations`, `postcodes`, and `zones`. The `layer` field appears on autocomplete hits, boundary routes, and the optional `layers` query parameter on several endpoints. **GET /layers** lists each layer with record counts and covered countries (sourced from `search_registry`).\n\nTwo Postgres materialized views back different read paths. **`search_registry`** holds searchable rows for locations, postcodes, and zones, with trigram-friendly text fields and ranking metadata; **GET /v1/autocomplete** and per-layer autocomplete routes query it. **`point_layers`** holds polygon-backed rows only (`locations`, `zones`) with full geometry for point-in-polygon tests; **GET /v1/points/resolve** queries it. Postcodes live in `search_registry` but not `point_layers` (they have no own boundary polygon), so resolve accepts `layers=locations|zones` only — use the postcode routes for postal lookups. By default, resolve uses `layers=locations,zones`. With `include=postcodes`, resolve embeds `anchor.postcode` (string or `null`) from the input coordinates plus the linked-code list on `anchor.postcodes`.\n\n## Custom zones\n\nPublished custom zones are read-only at **GET /v1/zones**. Customer writes use **POST /v1/zone-submissions** (draft → submit → admin review); approved submissions are published to the zones registry. The same workflow is available in the dashboard at [dashboard.mapbase.dev](https://dashboard.mapbase.dev).\n\n## Canonical registry IDs\n\nRegistry rows expose a canonical **`id`** prefixed by layer: `mb_loc_`, `mb_zon_`, `mb_lau_`, `mb_cod_`. Each is deterministic URL-safe base64url of the upstream key (postcodes encode Eurostat `pc_cntr`). Responses always return `mb_*` as `id`; upstream ingestion keys are not included in JSON bodies. Route path and query parameters may still accept legacy upstream keys where noted per route. LAU rows expose `gisco_id`; postcodes expose `code` for display. Location path and hierarchy filters use canonical `mb_loc_*` ids (including `parent_id` on location nodes).\n\n## Authentication\n\nEvery `/v1` route requires an API key, sent in the `x-api-key` header. Requests without a valid key receive `401` (`auth_missing_key` / `auth_invalid_key`). The utility routes (`/health`, `/redis-health`, `/layers`, `/openapi.json`, `/reference`) are unauthenticated. For local testing in the Scalar reference UI, set `REFERENCE_API_KEY` in your `.env` to pre-fill the key on every `/v1` endpoint. Provider passthrough routes also accept `x-google-api-key` and `x-geoapify-api-key`; pre-fill those in Scalar with `REFERENCE_GOOGLE_API_KEY` and `REFERENCE_GEOAPIFY_API_KEY` (engine `/reference`) or `REFERENCE_GOOGLE_API_KEY` / `GEOAPIFY_API_KEY` (dashboard `/api`).\n\n## Rate limits & credits\n\nEach API key is rate limited per second (burst) and per billing period (quota). Successful `/v1` responses include `X-Mapbase-Credits` with the credits charged for that request. Quota headers use the IETF-draft `RateLimit-Limit`, `RateLimit-Remaining`, `RateLimit-Reset` and `RateLimit-Policy` fields; `429` responses add `Retry-After`. The base path cost is documented on each operation as the `x-mapbase-credits` OpenAPI extension — use the [playgrounds](https://mapbase.dev/playground) to see request-aware costs live. When you exceed your included volume, requests are blocked until you upgrade or the billing period resets.\n\n## Errors\n\nEvery error response follows:\n\n```json\n{\n \"error\": {\n \"code\": \"not_found\",\n \"message\": \"Human-readable explanation.\",\n \"request_id\": \"...\"\n }\n}\n```"},"servers":[{"url":"https://api.mapbase.dev","description":"Production"}],"tags":[{"name":"health","description":"Unversioned liveness probe at GET /health and Redis connectivity probe at GET /redis-health. No API key required."},{"name":"layers","description":"Unversioned registry layer counts at GET /layers. No API key required."},{"name":"locations","description":"Administrative and named locations with hierarchy, boundaries, and autocomplete. List/detail `id` is canonical `mb_loc_*`; path params also accept ids."},{"name":"points","description":"Point-in-polygon resolve against registry matviews. Hits return canonical `mb_*` ids."},{"name":"autocomplete","description":"Unified registry autocomplete across locations, postcodes, and zones. Each hit `id` is canonical `mb_*`."},{"name":"postcodes","description":"Postal code lookups backed by Eurostat postal_codes. `id` is `mb_cod_*`; `code` is the display value."},{"name":"zones","description":"Custom overlapping areas in the published registry (read-only). `id` is `mb_zon_*`; path params also accept zone ids. To create or edit zones, use zone-submissions — drafts are reviewed before publish."},{"name":"zone-submissions","description":"Customer zone writes: create a draft, edit geometry/metadata, submit for admin review. Free (bypasses payment gate). Approved submissions are published to `/v1/zones`; published zones cannot be deleted via this API."},{"name":"boundaries","description":"Bulk boundary queries at GET /v1/boundaries (polylines by default; GeoJSON capped). For one entity use GET /v1/locations/{identifier}/boundary, /v1/zones/{identifier}/boundary, or /v1/lau/{identifier}/boundary."},{"name":"seo","description":"SEO helpers built on point resolve."},{"name":"providers","description":"Third-party adapters (Google address, Geoapify boundaries). Send the provider API key in `x-google-api-key` or `x-geoapify-api-key`; Mapbase never stores it."}],"components":{"schemas":{"CountryCode":{"type":"string","minLength":2,"maxLength":2,"description":"ISO 3166-1 alpha-2 country code. PT, ES, IT, UK, or FR on location and address surfaces.","example":"PT"},"FilterKinds":{"type":"string","description":"Comma-separated list of location kinds to include. Defaults to all kinds.","example":"town,district"},"FilterLevels":{"type":"string","description":"Comma-separated admin depths to include (1=country … 7=block).","example":"4,5"},"FilterParentId":{"type":"string","description":"Filter by parent location id. Pass the literal string `null` to fetch root rows.","example":"pt"},"FilterBbox":{"type":"string","description":"Bounding box as `minLng,minLat,maxLng,maxLat`. Filters via PostGIS ST_Intersects.","example":"-9.2,38.7,-9.0,38.8"},"FilterNear":{"type":"string","description":"Optional `lng,lat` bias or centre point.","example":"-9.1393,38.7223"},"FilterRadiusM":{"type":"integer","minimum":1,"maximum":50000,"description":"Radius in metres around `near`. Default 5000 when `near` is set without an explicit radius.","example":5000},"FilterLang":{"type":"string","enum":["native","en","fr","de"],"description":"Selects between native name and translated columns (`name_engl`, `name_fren`, `name_germ`).","example":"en"},"FilterLimit":{"type":"integer","minimum":1,"maximum":200,"description":"Max items per page.","example":50},"FilterBoundaryLimit":{"type":"integer","minimum":1,"maximum":10000,"description":"Max items per page for bulk boundary scans (`format=polyline` default).","example":50},"FilterOffset":{"type":"integer","minimum":0,"description":"Offset pagination. Mutually exclusive with `cursor`.","example":0},"FilterCursor":{"type":"string","description":"Opaque pagination cursor returned by a previous response."},"FilterSrid":{"type":"integer","enum":[4326,3857,25829,32629],"description":"Output coordinate reference (EPSG). Default 4326 (WGS84).","example":4326},"CountryQueryParam":{"type":"object","properties":{"country":{"$ref":"#/components/schemas/CountryCode"}}},"KindsQueryParam":{"type":"object","properties":{"kinds":{"$ref":"#/components/schemas/FilterKinds"}}},"LevelsQueryParam":{"type":"object","properties":{"levels":{"$ref":"#/components/schemas/FilterLevels"}}},"ParentQueryParam":{"type":"object","properties":{"parent_id":{"$ref":"#/components/schemas/FilterParentId"}}},"BboxQueryParam":{"type":"object","properties":{"bbox":{"$ref":"#/components/schemas/FilterBbox"}}},"NearQueryParam":{"type":"object","properties":{"near":{"$ref":"#/components/schemas/FilterNear"}}},"RadiusQueryParam":{"type":"object","properties":{"radius_m":{"$ref":"#/components/schemas/FilterRadiusM"}}},"LangQueryParam":{"type":"object","properties":{"lang":{"$ref":"#/components/schemas/FilterLang"}}},"PaginationQueryParam":{"type":"object","properties":{"limit":{"$ref":"#/components/schemas/FilterLimit"},"offset":{"$ref":"#/components/schemas/FilterOffset"},"cursor":{"$ref":"#/components/schemas/FilterCursor"}}},"BoundaryPaginationQueryParam":{"type":"object","properties":{"limit":{"$ref":"#/components/schemas/FilterBoundaryLimit"},"cursor":{"$ref":"#/components/schemas/FilterCursor"}}},"SridQueryParam":{"type":"object","properties":{"srid":{"$ref":"#/components/schemas/FilterSrid"}}},"HealthResponse":{"type":"object","properties":{"status":{"type":"string","enum":["ok"]},"uptime_ms":{"type":"integer"},"version":{"type":"string"},"environment":{"type":"string"}},"required":["status","uptime_ms","version","environment"]},"RedisHealthResponse":{"oneOf":[{"type":"object","properties":{"status":{"type":"string","enum":["ok"]},"redis":{"type":"object","properties":{"reachable":{"type":"boolean","enum":[true]},"host":{"type":"string"},"latency_ms":{"type":"integer","minimum":0}},"required":["reachable","host","latency_ms"]},"ratelimit_enabled":{"type":"boolean"},"ip_rules_loaded":{"type":"boolean"}},"required":["status","redis","ratelimit_enabled","ip_rules_loaded"]},{"type":"object","properties":{"status":{"type":"string","enum":["error"]},"redis":{"type":"object","properties":{"reachable":{"type":"boolean","enum":[false]},"host":{"type":"string"},"latency_ms":{"type":"null"},"error":{"type":"string"}},"required":["reachable","host","latency_ms","error"]},"ratelimit_enabled":{"type":"boolean"},"ip_rules_loaded":{"type":"null"}},"required":["status","redis","ratelimit_enabled","ip_rules_loaded"]}]},"LayersResponse":{"type":"object","properties":{"layers":{"type":"array","items":{"type":"object","properties":{"layer":{"type":"string","enum":["locations","postcodes","zones"]},"label":{"type":"string"},"count":{"type":"integer","minimum":0},"countries":{"type":"array","items":{"type":"string","minLength":2,"maxLength":2}}},"required":["layer","label","count"]}},"countries":{"type":"array","items":{"type":"object","properties":{"country":{"type":"string","minLength":2,"maxLength":2},"count":{"type":"integer","minimum":0}},"required":["country","count"]}},"byLayerCountry":{"type":"array","items":{"type":"object","properties":{"layer":{"type":"string","enum":["locations","postcodes","zones"]},"country":{"type":"string","minLength":2,"maxLength":2},"count":{"type":"integer","minimum":0}},"required":["layer","country","count"]}},"breakdown":{"type":"array","items":{"type":"object","properties":{"layer":{"type":"string","enum":["locations","postcodes","zones"]},"country":{"type":"string","minLength":2,"maxLength":2},"kind":{"type":["string","null"]},"level":{"type":["integer","null"],"minimum":0,"maximum":7},"count":{"type":"integer","minimum":0}},"required":["layer","country","kind","count"]}}},"required":["layers"]},"LocationListResponse":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"layer":{"type":"string","enum":["locations","postcodes","zones"]},"kind":{"type":"string"},"country":{"type":"string","minLength":2,"maxLength":2},"name":{"type":"string"},"label":{"type":"string"},"uri":{"type":["string","null"]},"parent_id":{"type":["string","null"]},"level":{"type":["integer","null"],"minimum":0,"maximum":7},"is_final":{"type":"boolean"},"centroid":{"type":["array","null"],"prefixItems":[{"type":"number"},{"type":"number"}]},"bbox":{"type":["array","null"],"prefixItems":[{"type":"number"},{"type":"number"},{"type":"number"},{"type":"number"}]},"polylines":{"type":"array","items":{"type":"string"}},"has_boundary":{"type":"boolean"}},"required":["id","layer","kind","country","name","uri","parent_id","level","is_final","has_boundary"]}},"meta":{"type":"object","properties":{"limit":{"type":"integer"},"next_cursor":{"type":["string","null"]}},"required":["limit","next_cursor"]}},"required":["data","meta"]},"ApiErrorEnvelope":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"scope":{"type":"string"},"detail":{"type":"string"},"request_id":{"type":"string"}},"required":["code","message","request_id"]}},"required":["error"]},"LocationRelationsResponse":{"type":"object","properties":{"location":{"type":"object","properties":{"id":{"type":"string"},"layer":{"type":"string","enum":["locations","postcodes","zones"]},"kind":{"type":"string"},"country":{"type":"string","minLength":2,"maxLength":2},"name":{"type":"string"},"label":{"type":"string"},"uri":{"type":["string","null"]},"parent_id":{"type":["string","null"]},"level":{"type":["integer","null"],"minimum":0,"maximum":7},"is_final":{"type":"boolean"},"centroid":{"type":["array","null"],"prefixItems":[{"type":"number"},{"type":"number"}]},"bbox":{"type":["array","null"],"prefixItems":[{"type":"number"},{"type":"number"},{"type":"number"},{"type":"number"}]},"polylines":{"type":"array","items":{"type":"string"}},"has_boundary":{"type":"boolean"}},"required":["id","layer","kind","country","name","uri","parent_id","level","is_final","has_boundary"]},"parent":{"type":["object","null"],"properties":{"id":{"type":"string"},"layer":{"type":"string","enum":["locations","postcodes","zones"]},"kind":{"type":"string"},"country":{"type":"string","minLength":2,"maxLength":2},"name":{"type":"string"},"label":{"type":"string"},"uri":{"type":["string","null"]},"parent_id":{"type":["string","null"]},"level":{"type":["integer","null"],"minimum":0,"maximum":7},"is_final":{"type":"boolean"},"centroid":{"type":["array","null"],"prefixItems":[{"type":"number"},{"type":"number"}]},"bbox":{"type":["array","null"],"prefixItems":[{"type":"number"},{"type":"number"},{"type":"number"},{"type":"number"}]},"polylines":{"type":"array","items":{"type":"string"}},"has_boundary":{"type":"boolean"}},"required":["id","layer","kind","country","name","uri","parent_id","level","is_final","has_boundary"]},"children":{"type":["object","null"],"properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"layer":{"type":"string","enum":["locations","postcodes","zones"]},"kind":{"type":"string"},"country":{"type":"string","minLength":2,"maxLength":2},"name":{"type":"string"},"label":{"type":"string"},"uri":{"type":["string","null"]},"parent_id":{"type":["string","null"]},"level":{"type":["integer","null"],"minimum":0,"maximum":7},"is_final":{"type":"boolean"},"centroid":{"type":["array","null"],"prefixItems":[{"type":"number"},{"type":"number"}]},"bbox":{"type":["array","null"],"prefixItems":[{"type":"number"},{"type":"number"},{"type":"number"},{"type":"number"}]},"polylines":{"type":"array","items":{"type":"string"}},"has_boundary":{"type":"boolean"}},"required":["id","layer","kind","country","name","uri","parent_id","level","is_final","has_boundary"]}},"meta":{"type":"object","properties":{"limit":{"type":"integer"},"next_cursor":{"type":["string","null"]}},"required":["limit","next_cursor"]}},"required":["data","meta"]},"siblings":{"type":["object","null"],"properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"layer":{"type":"string","enum":["locations","postcodes","zones"]},"kind":{"type":"string"},"country":{"type":"string","minLength":2,"maxLength":2},"name":{"type":"string"},"label":{"type":"string"},"uri":{"type":["string","null"]},"parent_id":{"type":["string","null"]},"level":{"type":["integer","null"],"minimum":0,"maximum":7},"is_final":{"type":"boolean"},"centroid":{"type":["array","null"],"prefixItems":[{"type":"number"},{"type":"number"}]},"bbox":{"type":["array","null"],"prefixItems":[{"type":"number"},{"type":"number"},{"type":"number"},{"type":"number"}]},"polylines":{"type":"array","items":{"type":"string"}},"has_boundary":{"type":"boolean"}},"required":["id","layer","kind","country","name","uri","parent_id","level","is_final","has_boundary"]}},"meta":{"type":"object","properties":{"limit":{"type":"integer"},"next_cursor":{"type":["string","null"]}},"required":["limit","next_cursor"]}},"required":["data","meta"]},"ancestors":{"type":["array","null"],"items":{"type":"object","properties":{"id":{"type":"string"},"layer":{"type":"string","enum":["locations","postcodes","zones"]},"kind":{"type":"string"},"country":{"type":"string","minLength":2,"maxLength":2},"name":{"type":"string"},"label":{"type":"string"},"uri":{"type":["string","null"]},"parent_id":{"type":["string","null"]},"level":{"type":["integer","null"],"minimum":0,"maximum":7},"is_final":{"type":"boolean"},"centroid":{"type":["array","null"],"prefixItems":[{"type":"number"},{"type":"number"}]},"bbox":{"type":["array","null"],"prefixItems":[{"type":"number"},{"type":"number"},{"type":"number"},{"type":"number"}]},"polylines":{"type":"array","items":{"type":"string"}},"has_boundary":{"type":"boolean"}},"required":["id","layer","kind","country","name","uri","parent_id","level","is_final","has_boundary"]}}},"required":["location","parent","children","siblings","ancestors"]},"BoundaryResponse":{"type":"object","properties":{"id":{"type":"string"},"layer":{"type":"string","enum":["locations","postcodes","zones"]},"geometry":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","enum":["Point"]},"coordinates":{"type":"array","prefixItems":[{"type":"number"},{"type":"number"}]}},"required":["type","coordinates"]},{"type":"object","properties":{"type":{"type":"string","enum":["Polygon"]},"coordinates":{"type":"array","items":{"type":"array","items":{"type":"array","prefixItems":[{"type":"number"},{"type":"number"}]}}}},"required":["type","coordinates"]},{"type":"object","properties":{"type":{"type":"string","enum":["MultiPolygon"]},"coordinates":{"type":"array","items":{"type":"array","items":{"type":"array","items":{"type":"array","prefixItems":[{"type":"number"},{"type":"number"}]}}}}},"required":["type","coordinates"]}]},"bbox":{"type":"array","prefixItems":[{"type":"number"},{"type":"number"},{"type":"number"},{"type":"number"}]},"srid":{"type":"integer"}},"required":["id","layer","geometry","bbox","srid"]},"ZoneListResponse":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"uri":{"type":"string"},"kind":{"type":"string"},"country":{"type":"string","minLength":2,"maxLength":2},"status":{"type":"string","enum":["active","inactive"]},"location_id":{"type":["string","null"]},"location":{"type":["object","null"],"properties":{"id":{"type":"string"},"layer":{"type":"string","enum":["locations","postcodes","zones"]},"kind":{"type":"string"},"country":{"type":"string","minLength":2,"maxLength":2},"name":{"type":"string"},"label":{"type":"string"},"uri":{"type":["string","null"]},"parent_id":{"type":["string","null"]},"level":{"type":["integer","null"],"minimum":0,"maximum":7},"is_final":{"type":"boolean"},"centroid":{"type":["array","null"],"prefixItems":[{"type":"number"},{"type":"number"}]},"bbox":{"type":["array","null"],"prefixItems":[{"type":"number"},{"type":"number"},{"type":"number"},{"type":"number"}]},"polylines":{"type":"array","items":{"type":"string"}},"has_boundary":{"type":"boolean"}},"required":["id","layer","kind","country","name","uri","parent_id","level","is_final","has_boundary"]},"centroid":{"type":["array","null"],"prefixItems":[{"type":"number"},{"type":"number"}]},"polylines":{"type":"array","items":{"type":"string"}},"has_boundary":{"type":"boolean"}},"required":["id","name","uri","kind","country","status","location_id","location","has_boundary"]}},"meta":{"type":"object","properties":{"limit":{"type":"integer"},"next_cursor":{"type":["string","null"]}},"required":["limit","next_cursor"]}},"required":["data","meta"]},"LocationDetail":{"type":"object","properties":{"id":{"type":"string"},"layer":{"type":"string","enum":["locations","postcodes","zones"]},"kind":{"type":"string"},"country":{"type":"string","minLength":2,"maxLength":2},"name":{"type":"string"},"label":{"type":"string"},"uri":{"type":["string","null"]},"parent_id":{"type":["string","null"]},"level":{"type":["integer","null"],"minimum":0,"maximum":7},"is_final":{"type":"boolean"},"centroid":{"type":["array","null"],"prefixItems":[{"type":"number"},{"type":"number"}]},"bbox":{"type":["array","null"],"prefixItems":[{"type":"number"},{"type":"number"},{"type":"number"},{"type":"number"}]},"polylines":{"type":"array","items":{"type":"string"}},"has_boundary":{"type":"boolean"},"parent":{"type":["object","null"],"properties":{"id":{"type":"string"},"layer":{"type":"string","enum":["locations","postcodes","zones"]},"kind":{"type":"string"},"country":{"type":"string","minLength":2,"maxLength":2},"name":{"type":"string"},"label":{"type":"string"},"uri":{"type":["string","null"]},"parent_id":{"type":["string","null"]},"level":{"type":["integer","null"],"minimum":0,"maximum":7},"is_final":{"type":"boolean"},"centroid":{"type":["array","null"],"prefixItems":[{"type":"number"},{"type":"number"}]},"bbox":{"type":["array","null"],"prefixItems":[{"type":"number"},{"type":"number"},{"type":"number"},{"type":"number"}]},"polylines":{"type":"array","items":{"type":"string"}},"has_boundary":{"type":"boolean"}},"required":["id","layer","kind","country","name","uri","parent_id","level","is_final","has_boundary"]},"hierarchy":{"type":"object","additionalProperties":{"type":"object","properties":{"id":{"type":"string"},"layer":{"type":"string","enum":["locations","postcodes","zones"]},"kind":{"type":"string"},"country":{"type":"string","minLength":2,"maxLength":2},"name":{"type":"string"},"label":{"type":"string"},"uri":{"type":["string","null"]},"parent_id":{"type":["string","null"]},"level":{"type":["integer","null"],"minimum":0,"maximum":7},"is_final":{"type":"boolean"},"centroid":{"type":["array","null"],"prefixItems":[{"type":"number"},{"type":"number"}]},"bbox":{"type":["array","null"],"prefixItems":[{"type":"number"},{"type":"number"},{"type":"number"},{"type":"number"}]},"polylines":{"type":"array","items":{"type":"string"}},"has_boundary":{"type":"boolean"}},"required":["id","layer","kind","country","name","uri","parent_id","level","is_final","has_boundary"]}},"postcodes":{"type":"array","items":{"type":"string"}}},"required":["id","layer","kind","country","name","uri","parent_id","level","is_final","has_boundary"],"example":{"id":"mb_loc_MC1FVS1QVC0xMS0wNg","layer":"locations","kind":"municipality","country":"PT","name":"Lisboa","uri":"lisboa","parent_id":"mb_loc_MC1FVS1QVC0xMQ","level":4,"is_final":false,"has_boundary":true,"parent":{"id":"mb_loc_MC1FVS1QVC0xMQ","layer":"locations","kind":"district","country":"PT","name":"Lisboa distrito","uri":"lisboa-distrito","parent_id":"mb_loc_MC1FVS1QVC1DT05U","level":3,"is_final":false,"has_boundary":true},"hierarchy":{"1":{"id":"mb_loc_MC1FVS1QVA","layer":"locations","kind":"country","country":"PT","name":"Portugal","uri":"pt","parent_id":null,"level":1,"is_final":false,"has_boundary":true},"2":{"id":"mb_loc_MC1FVS1QVC1DT05U","layer":"locations","kind":"continent","country":"PT","name":"Portugal (continente)","uri":"portugal-continent","parent_id":"mb_loc_MC1FVS1QVA","level":2,"is_final":false,"has_boundary":true},"3":{"id":"mb_loc_MC1FVS1QVC0xMQ","layer":"locations","kind":"district","country":"PT","name":"Lisboa distrito","uri":"lisboa-distrito","parent_id":"mb_loc_MC1FVS1QVC1DT05U","level":3,"is_final":false,"has_boundary":true},"4":{"id":"mb_loc_MC1FVS1QVC0xMS0wNg","layer":"locations","kind":"municipality","country":"PT","name":"Lisboa","uri":"lisboa","parent_id":"mb_loc_MC1FVS1QVC0xMQ","level":4,"is_final":false,"has_boundary":true}}}},"PointResolveResponse":{"type":"object","properties":{"point":{"type":"array","prefixItems":[{"type":"number"},{"type":"number"}]},"country":{"type":["string","null"],"minLength":2,"maxLength":2},"anchor":{"type":["object","null"],"properties":{"id":{"type":"string"},"layer":{"type":"string","enum":["locations","postcodes","zones"]},"kind":{"type":"string"},"country":{"type":"string","minLength":2,"maxLength":2},"name":{"type":"string"},"label":{"type":"string"},"uri":{"type":["string","null"]},"parent_id":{"type":["string","null"]},"level":{"type":["integer","null"],"minimum":0,"maximum":7},"centroid":{"type":["array","null"],"prefixItems":[{"type":"number"},{"type":"number"}]},"bbox":{"type":["array","null"],"prefixItems":[{"type":"number"},{"type":"number"},{"type":"number"},{"type":"number"}]},"polylines":{"type":"array","items":{"type":"string"}},"postcodes":{"type":"array","items":{"type":"string"}},"postcode":{"type":["string","null"]}},"required":["id","layer","kind","country","name","uri","parent_id","level"]},"hierarchy":{"type":"object","additionalProperties":{"type":"object","properties":{"id":{"type":"string"},"layer":{"type":"string","enum":["locations","postcodes","zones"]},"kind":{"type":"string"},"country":{"type":"string","minLength":2,"maxLength":2},"name":{"type":"string"},"label":{"type":"string"},"uri":{"type":["string","null"]},"parent_id":{"type":["string","null"]},"level":{"type":["integer","null"],"minimum":0,"maximum":7},"centroid":{"type":["array","null"],"prefixItems":[{"type":"number"},{"type":"number"}]},"bbox":{"type":["array","null"],"prefixItems":[{"type":"number"},{"type":"number"},{"type":"number"},{"type":"number"}]},"polylines":{"type":"array","items":{"type":"string"}}},"required":["id","layer","kind","country","name","uri","parent_id","level"]}},"contains":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"layer":{"type":"string","enum":["locations","postcodes","zones"]},"kind":{"type":"string"},"country":{"type":"string","minLength":2,"maxLength":2},"name":{"type":"string"},"label":{"type":"string"},"uri":{"type":["string","null"]},"parent_id":{"type":["string","null"]},"level":{"type":["integer","null"],"minimum":0,"maximum":7},"centroid":{"type":["array","null"],"prefixItems":[{"type":"number"},{"type":"number"}]},"bbox":{"type":["array","null"],"prefixItems":[{"type":"number"},{"type":"number"},{"type":"number"},{"type":"number"}]},"polylines":{"type":"array","items":{"type":"string"}}},"required":["id","layer","kind","country","name","uri","parent_id","level"]}}},"required":["point","country","anchor","hierarchy","contains"]},"AutocompleteResponse":{"type":"object","properties":{"query":{"type":"string"},"results":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"layer":{"type":"string","enum":["locations","postcodes","zones"]},"kind":{"type":"string"},"country":{"type":"string","minLength":2,"maxLength":2},"name":{"type":"string"},"label":{"type":"string"},"uri":{"type":["string","null"]},"parent_id":{"type":["string","null"]},"level":{"type":["integer","null"],"minimum":0,"maximum":7},"is_final":{"type":"boolean"},"centroid":{"type":["array","null"],"prefixItems":[{"type":"number"},{"type":"number"}]},"bbox":{"type":["array","null"],"prefixItems":[{"type":"number"},{"type":"number"},{"type":"number"},{"type":"number"}]},"polylines":{"type":"array","items":{"type":"string"}},"score":{"type":"number"}},"required":["id","layer","kind","country","name","label","uri","parent_id","level","score"]}}},"required":["query","results"]},"PostcodeListResponse":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"code":{"type":"string"},"country":{"type":"string","minLength":2,"maxLength":2},"gisco_id":{"type":["string","null"]},"lau_name":{"type":["string","null"]},"centroid":{"type":["array","null"],"prefixItems":[{"type":"number"},{"type":"number"}]},"location_id":{"type":["string","null"]},"location":{"type":["object","null"],"properties":{"id":{"type":"string"},"layer":{"type":"string","enum":["locations","postcodes","zones"]},"kind":{"type":"string"},"country":{"type":"string","minLength":2,"maxLength":2},"name":{"type":"string"},"label":{"type":"string"},"uri":{"type":["string","null"]},"parent_id":{"type":["string","null"]},"level":{"type":["integer","null"],"minimum":0,"maximum":7},"is_final":{"type":"boolean"},"centroid":{"type":["array","null"],"prefixItems":[{"type":"number"},{"type":"number"}]},"bbox":{"type":["array","null"],"prefixItems":[{"type":"number"},{"type":"number"},{"type":"number"},{"type":"number"}]},"polylines":{"type":"array","items":{"type":"string"}},"has_boundary":{"type":"boolean"}},"required":["id","layer","kind","country","name","uri","parent_id","level","is_final","has_boundary"]}},"required":["id","code","country","gisco_id","lau_name","location_id","location"]}},"meta":{"type":"object","properties":{"limit":{"type":"integer"},"next_cursor":{"type":["string","null"]}},"required":["limit","next_cursor"]}},"required":["data","meta"]},"Postcode":{"type":"object","properties":{"id":{"type":"string"},"code":{"type":"string"},"country":{"type":"string","minLength":2,"maxLength":2},"gisco_id":{"type":["string","null"]},"lau_name":{"type":["string","null"]},"centroid":{"type":["array","null"],"prefixItems":[{"type":"number"},{"type":"number"}]},"location_id":{"type":["string","null"]},"location":{"type":["object","null"],"properties":{"id":{"type":"string"},"layer":{"type":"string","enum":["locations","postcodes","zones"]},"kind":{"type":"string"},"country":{"type":"string","minLength":2,"maxLength":2},"name":{"type":"string"},"label":{"type":"string"},"uri":{"type":["string","null"]},"parent_id":{"type":["string","null"]},"level":{"type":["integer","null"],"minimum":0,"maximum":7},"is_final":{"type":"boolean"},"centroid":{"type":["array","null"],"prefixItems":[{"type":"number"},{"type":"number"}]},"bbox":{"type":["array","null"],"prefixItems":[{"type":"number"},{"type":"number"},{"type":"number"},{"type":"number"}]},"polylines":{"type":"array","items":{"type":"string"}},"has_boundary":{"type":"boolean"}},"required":["id","layer","kind","country","name","uri","parent_id","level","is_final","has_boundary"]}},"required":["id","code","country","gisco_id","lau_name","location_id","location"],"example":{"id":"mb_cod_UFRfMTEwMC0wNjI","code":"1100-062","country":"PT","gisco_id":"PT_110665","lau_name":"Santa Maria Maior","centroid":[-9.138168592,38.710022004],"location_id":"mb_loc_MC1FVS1QVC0xMS0wNi0wNjUtNjUtMDI","location":{"id":"mb_loc_MC1FVS1QVC0xMS0wNi0wNjUtNjUtMDI","layer":"locations","kind":"neighborhood","country":"PT","name":"Baixa, Lisboa","uri":"santa-maria-maior/baixa","parent_id":"0-EU-PT-11-06-065-65","level":6,"is_final":true,"centroid":[-9.136837163,38.708410674],"bbox":[-9.141969,38.705318,-9.13082,38.713488],"has_boundary":true}}},"PostcodeDetail":{"type":"object","properties":{"id":{"type":"string"},"code":{"type":"string"},"country":{"type":"string","minLength":2,"maxLength":2},"gisco_id":{"type":["string","null"]},"lau_name":{"type":["string","null"]},"centroid":{"type":["array","null"],"prefixItems":[{"type":"number"},{"type":"number"}]},"location_id":{"type":["string","null"]},"location":{"type":["object","null"],"properties":{"id":{"type":"string"},"layer":{"type":"string","enum":["locations","postcodes","zones"]},"kind":{"type":"string"},"country":{"type":"string","minLength":2,"maxLength":2},"name":{"type":"string"},"label":{"type":"string"},"uri":{"type":["string","null"]},"parent_id":{"type":["string","null"]},"level":{"type":["integer","null"],"minimum":0,"maximum":7},"is_final":{"type":"boolean"},"centroid":{"type":["array","null"],"prefixItems":[{"type":"number"},{"type":"number"}]},"bbox":{"type":["array","null"],"prefixItems":[{"type":"number"},{"type":"number"},{"type":"number"},{"type":"number"}]},"polylines":{"type":"array","items":{"type":"string"}},"has_boundary":{"type":"boolean"}},"required":["id","layer","kind","country","name","uri","parent_id","level","is_final","has_boundary"]},"parent":{"type":["object","null"],"properties":{"id":{"type":"string"},"layer":{"type":"string","enum":["locations","postcodes","zones"]},"kind":{"type":"string"},"country":{"type":"string","minLength":2,"maxLength":2},"name":{"type":"string"},"label":{"type":"string"},"uri":{"type":["string","null"]},"parent_id":{"type":["string","null"]},"level":{"type":["integer","null"],"minimum":0,"maximum":7},"is_final":{"type":"boolean"},"centroid":{"type":["array","null"],"prefixItems":[{"type":"number"},{"type":"number"}]},"bbox":{"type":["array","null"],"prefixItems":[{"type":"number"},{"type":"number"},{"type":"number"},{"type":"number"}]},"polylines":{"type":"array","items":{"type":"string"}},"has_boundary":{"type":"boolean"}},"required":["id","layer","kind","country","name","uri","parent_id","level","is_final","has_boundary"]},"hierarchy":{"type":"object","additionalProperties":{"type":"object","properties":{"id":{"type":"string"},"layer":{"type":"string","enum":["locations","postcodes","zones"]},"kind":{"type":"string"},"country":{"type":"string","minLength":2,"maxLength":2},"name":{"type":"string"},"label":{"type":"string"},"uri":{"type":["string","null"]},"parent_id":{"type":["string","null"]},"level":{"type":["integer","null"],"minimum":0,"maximum":7},"is_final":{"type":"boolean"},"centroid":{"type":["array","null"],"prefixItems":[{"type":"number"},{"type":"number"}]},"bbox":{"type":["array","null"],"prefixItems":[{"type":"number"},{"type":"number"},{"type":"number"},{"type":"number"}]},"polylines":{"type":"array","items":{"type":"string"}},"has_boundary":{"type":"boolean"}},"required":["id","layer","kind","country","name","uri","parent_id","level","is_final","has_boundary"]}}},"required":["id","code","country","gisco_id","lau_name","location_id","location"],"example":{"id":"mb_cod_UFRfMTEwMC0wNjI","code":"1100-062","country":"PT","gisco_id":"PT_110665","lau_name":"Santa Maria Maior","centroid":[-9.138168592,38.710022004],"location_id":"mb_loc_MC1FVS1QVC0xMS0wNi0wNjUtNjUtMDI","location":{"id":"mb_loc_MC1FVS1QVC0xMS0wNi0wNjUtNjUtMDI","layer":"locations","kind":"neighborhood","country":"PT","name":"Baixa, Lisboa","uri":"santa-maria-maior/baixa","parent_id":"0-EU-PT-11-06-065-65","level":6,"is_final":true,"centroid":[-9.136837163,38.708410674],"bbox":[-9.141969,38.705318,-9.13082,38.713488],"has_boundary":true}}},"Zone":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"uri":{"type":"string"},"kind":{"type":"string"},"country":{"type":"string","minLength":2,"maxLength":2},"status":{"type":"string","enum":["active","inactive"]},"location_id":{"type":["string","null"]},"location":{"type":["object","null"],"properties":{"id":{"type":"string"},"layer":{"type":"string","enum":["locations","postcodes","zones"]},"kind":{"type":"string"},"country":{"type":"string","minLength":2,"maxLength":2},"name":{"type":"string"},"label":{"type":"string"},"uri":{"type":["string","null"]},"parent_id":{"type":["string","null"]},"level":{"type":["integer","null"],"minimum":0,"maximum":7},"is_final":{"type":"boolean"},"centroid":{"type":["array","null"],"prefixItems":[{"type":"number"},{"type":"number"}]},"bbox":{"type":["array","null"],"prefixItems":[{"type":"number"},{"type":"number"},{"type":"number"},{"type":"number"}]},"polylines":{"type":"array","items":{"type":"string"}},"has_boundary":{"type":"boolean"}},"required":["id","layer","kind","country","name","uri","parent_id","level","is_final","has_boundary"]},"centroid":{"type":["array","null"],"prefixItems":[{"type":"number"},{"type":"number"}]},"polylines":{"type":"array","items":{"type":"string"}},"has_boundary":{"type":"boolean"}},"required":["id","name","uri","kind","country","status","location_id","location","has_boundary"]},"ZoneSubmission":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"zone_id":{"type":["string","null"]},"tenant_id":{"type":"string"},"created_by":{"type":"string"},"status":{"type":"string","enum":["draft","submitted","approved","rejected"]},"name":{"type":"string"},"uri":{"type":["string","null"]},"kind":{"type":"string"},"country":{"type":"string","minLength":2,"maxLength":2},"location_id":{"type":["string","null"]},"geometry":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","enum":["Point"]},"coordinates":{"type":"array","prefixItems":[{"type":"number"},{"type":"number"}]}},"required":["type","coordinates"]},{"type":"object","properties":{"type":{"type":"string","enum":["Polygon"]},"coordinates":{"type":"array","items":{"type":"array","items":{"type":"array","prefixItems":[{"type":"number"},{"type":"number"}]}}}},"required":["type","coordinates"]},{"type":"object","properties":{"type":{"type":"string","enum":["MultiPolygon"]},"coordinates":{"type":"array","items":{"type":"array","items":{"type":"array","items":{"type":"array","prefixItems":[{"type":"number"},{"type":"number"}]}}}}},"required":["type","coordinates"]},{"type":"null"}]},"centroid":{"type":["object","null"],"properties":{"lng":{"type":"number"},"lat":{"type":"number"}},"required":["lng","lat"]},"polylines":{"type":"array","items":{"type":"string"}},"notes":{"type":["string","null"]},"rejection_reason":{"type":["string","null"]},"submitted_at":{"type":["string","null"],"format":"date-time"},"approved_at":{"type":["string","null"],"format":"date-time"},"rejected_at":{"type":["string","null"],"format":"date-time"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"required":["id","zone_id","tenant_id","created_by","status","name","uri","kind","country","location_id","created_at","updated_at"]},"ZoneSubmissionCreate":{"type":"object","properties":{"name":{"type":"string","minLength":1,"example":"Test zone"},"uri":{"type":"string","minLength":1,"maxLength":80,"pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$","example":"test-zone"},"kind":{"type":"string","minLength":1,"default":"custom_zone","example":"neighborhood"},"country":{"type":"string","minLength":2,"maxLength":2,"example":"PT"},"geometry":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","enum":["Point"]},"coordinates":{"type":"array","prefixItems":[{"type":"number"},{"type":"number"}]}},"required":["type","coordinates"]},{"type":"object","properties":{"type":{"type":"string","enum":["Polygon"]},"coordinates":{"type":"array","items":{"type":"array","items":{"type":"array","prefixItems":[{"type":"number"},{"type":"number"}]}}}},"required":["type","coordinates"]},{"type":"object","properties":{"type":{"type":"string","enum":["MultiPolygon"]},"coordinates":{"type":"array","items":{"type":"array","items":{"type":"array","items":{"type":"array","prefixItems":[{"type":"number"},{"type":"number"}]}}}}},"required":["type","coordinates"]}],"example":{"type":"Polygon","coordinates":[[[-9.148168592,38.700022004000004],[-9.128168592,38.700022004000004],[-9.128168592,38.720022004],[-9.148168592,38.720022004],[-9.148168592,38.700022004000004]]]}},"notes":{"type":"string","example":"Example submission"}},"required":["name","uri","country","geometry"]},"ZoneSubmissionListResponse":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"zone_id":{"type":["string","null"]},"tenant_id":{"type":"string"},"created_by":{"type":"string"},"status":{"type":"string","enum":["draft","submitted","approved","rejected"]},"name":{"type":"string"},"uri":{"type":["string","null"]},"kind":{"type":"string"},"country":{"type":"string","minLength":2,"maxLength":2},"location_id":{"type":["string","null"]},"geometry":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","enum":["Point"]},"coordinates":{"type":"array","prefixItems":[{"type":"number"},{"type":"number"}]}},"required":["type","coordinates"]},{"type":"object","properties":{"type":{"type":"string","enum":["Polygon"]},"coordinates":{"type":"array","items":{"type":"array","items":{"type":"array","prefixItems":[{"type":"number"},{"type":"number"}]}}}},"required":["type","coordinates"]},{"type":"object","properties":{"type":{"type":"string","enum":["MultiPolygon"]},"coordinates":{"type":"array","items":{"type":"array","items":{"type":"array","items":{"type":"array","prefixItems":[{"type":"number"},{"type":"number"}]}}}}},"required":["type","coordinates"]},{"type":"null"}]},"centroid":{"type":["object","null"],"properties":{"lng":{"type":"number"},"lat":{"type":"number"}},"required":["lng","lat"]},"polylines":{"type":"array","items":{"type":"string"}},"notes":{"type":["string","null"]},"rejection_reason":{"type":["string","null"]},"submitted_at":{"type":["string","null"],"format":"date-time"},"approved_at":{"type":["string","null"],"format":"date-time"},"rejected_at":{"type":["string","null"],"format":"date-time"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"required":["id","zone_id","tenant_id","created_by","status","name","uri","kind","country","location_id","created_at","updated_at"]}},"meta":{"type":"object","properties":{"limit":{"type":"number"},"offset":{"type":"number"}},"required":["limit","offset"]}},"required":["data","meta"]},"ZoneSubmissionUpdate":{"type":"object","properties":{"name":{"type":"string","minLength":1,"example":"Renamed submission"},"uri":{"type":"string","minLength":1,"maxLength":80,"pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$"},"kind":{"type":"string","minLength":1,"default":"custom_zone"},"country":{"type":"string","minLength":2,"maxLength":2},"geometry":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","enum":["Point"]},"coordinates":{"type":"array","prefixItems":[{"type":"number"},{"type":"number"}]}},"required":["type","coordinates"]},{"type":"object","properties":{"type":{"type":"string","enum":["Polygon"]},"coordinates":{"type":"array","items":{"type":"array","items":{"type":"array","prefixItems":[{"type":"number"},{"type":"number"}]}}}},"required":["type","coordinates"]},{"type":"object","properties":{"type":{"type":"string","enum":["MultiPolygon"]},"coordinates":{"type":"array","items":{"type":"array","items":{"type":"array","items":{"type":"array","prefixItems":[{"type":"number"},{"type":"number"}]}}}}},"required":["type","coordinates"]}]},"notes":{"type":"string","example":"Updated notes"}}},"ZoneSubmissionDeleteResponse":{"type":"object","properties":{"id":{"type":"string","format":"uuid"}},"required":["id"]},"BoundaryListResponse":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"layer":{"type":"string","enum":["locations","zones"]},"name":{"type":"string"},"kind":{"type":"string"},"country":{"type":"string"},"level":{"type":["integer","null"]},"bbox":{"type":"array","prefixItems":[{"type":"number"},{"type":"number"},{"type":"number"},{"type":"number"}]},"srid":{"type":"integer"},"format":{"type":"string","enum":["geojson","polyline"]},"geometry":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","enum":["Point"]},"coordinates":{"type":"array","prefixItems":[{"type":"number"},{"type":"number"}]}},"required":["type","coordinates"]},{"type":"object","properties":{"type":{"type":"string","enum":["Polygon"]},"coordinates":{"type":"array","items":{"type":"array","items":{"type":"array","prefixItems":[{"type":"number"},{"type":"number"}]}}}},"required":["type","coordinates"]},{"type":"object","properties":{"type":{"type":"string","enum":["MultiPolygon"]},"coordinates":{"type":"array","items":{"type":"array","items":{"type":"array","items":{"type":"array","prefixItems":[{"type":"number"},{"type":"number"}]}}}}},"required":["type","coordinates"]}]},"polylines":{"type":"array","items":{"type":"string"}},"is_final":{"type":"boolean"}},"required":["id","layer","bbox","srid","format"]}},"meta":{"type":"object","properties":{"limit":{"type":"integer"},"next_cursor":{"type":["string","null"]}},"required":["limit","next_cursor"]}},"required":["data","meta"]},"SeoPageResponse":{"type":"object","properties":{"entity":{"type":"object","properties":{"id":{"type":"string"},"layer":{"type":"string","enum":["locations","postcodes","zones"]},"name":{"type":"string"},"uri":{"type":["string","null"]},"country":{"type":"string","enum":["PT","ES","IT","UK","FR"]},"kind":{"type":["string","null"]},"level":{"type":["integer","null"],"minimum":0,"maximum":7},"path":{"type":["string","null"]},"href":{"type":["string","null"],"format":"uri"}},"required":["id","layer","name","uri","country","kind","level","path","href"]},"breadcrumbs":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"uri":{"type":"string"},"layer":{"type":"string"},"kind":{"type":["string","null"]},"level":{"type":["integer","null"],"minimum":0,"maximum":7},"path":{"type":"string"},"href":{"type":["string","null"],"format":"uri"}},"required":["name","uri","layer","kind","level","path","href"]}},"meta":{"type":"object","properties":{"title":{"type":"string"},"description":{"type":"string"},"canonical_path":{"type":"string"},"canonical_url":{"type":["string","null"],"format":"uri"},"og_title":{"type":"string"},"og_description":{"type":"string"}},"required":["title","description","canonical_path","canonical_url","og_title","og_description"]},"json_ld":{"type":"object","additionalProperties":{}},"sections":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"title":{"type":"string"},"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"layer":{"type":"string"},"name":{"type":"string"},"uri":{"type":["string","null"]},"path":{"type":"string"},"href":{"type":["string","null"],"format":"uri"}},"required":["id","layer","name"]}}},"required":["key","title","items"]}}},"required":["entity","breadcrumbs","meta","json_ld"]},"SeoTreeResponse":{"type":"object","properties":{"country":{"type":"string","enum":["PT","ES","IT","UK","FR"]},"parent":{"type":["object","null"],"properties":{"id":{"type":"string"},"source_id":{"type":"string"},"layer":{"type":"string"},"country":{"type":"string","enum":["PT","ES","IT","UK","FR"]},"name":{"type":"string"},"kind":{"type":["string","null"]},"uri":{"type":["string","null"]},"path":{"type":"string"},"level":{"type":["integer","null"],"minimum":0,"maximum":7}},"required":["id","layer","country","name"]},"breadcrumbs":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"uri":{"type":"string"},"layer":{"type":"string"},"kind":{"type":["string","null"]},"level":{"type":["integer","null"],"minimum":0,"maximum":7},"path":{"type":"string"},"href":{"type":["string","null"],"format":"uri"}},"required":["name","uri","layer","kind","level","path","href"]}},"sections":{"type":"array","items":{"type":"object","properties":{"layer":{"type":"string","enum":["locations","postcodes","zones"]},"title":{"type":"string"},"nodes":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"source_id":{"type":"string"},"layer":{"type":"string","enum":["locations","postcodes","zones"]},"country":{"type":"string","enum":["PT","ES","IT","UK","FR"]},"name":{"type":"string"},"label":{"type":"string"},"centroid":{"type":["array","null"],"prefixItems":[{"type":"number"},{"type":"number"}]},"kind":{"type":["string","null"]},"uri":{"type":["string","null"]},"path":{"type":"string"},"parent_id":{"type":["string","null"]},"level":{"type":["integer","null"],"minimum":0,"maximum":7},"has_children":{"type":"boolean"},"child_count":{"type":"integer","minimum":0}},"required":["id","layer","country","name"]}},"meta":{"type":"object","properties":{"limit":{"type":"integer"},"next_cursor":{"type":["string","null"]}},"required":["limit","next_cursor"]}},"required":["layer","title","nodes","meta"]}}},"required":["country","parent","breadcrumbs","sections"]},"SeoSitemapResponse":{"type":"object","properties":{"shards":{"type":"array","items":{"type":"object","properties":{"slug":{"type":"string"},"lastmod":{"type":["string","null"]}},"required":["slug","lastmod"]}},"entries":{"type":"array","items":{"type":"object","properties":{"uri":{"type":"string"},"loc":{"type":"string","format":"uri"},"country":{"type":"string","enum":["PT","ES","IT","UK","FR"]},"layer":{"type":"string","enum":["locations","postcodes","zones"]},"kind":{"type":["string","null"]},"lastmod":{"type":["string","null"]}},"required":["uri","country","layer","lastmod"]}},"meta":{"type":"object","properties":{"shard":{"type":"string"},"count":{"type":"integer","minimum":0}},"required":["shard","count"]}}},"GoogleAutocompleteResponse":{},"GooglePlaceDetailsResponse":{},"GoogleGeocodeResponse":{},"GoogleReverseGeocodeResponse":{},"GeoapifyAutocompleteResponse":{"type":"object","properties":{"results":{"type":"array","items":{"type":"object","properties":{"place_id":{"type":"string"},"formatted":{"type":"string"},"country_code":{"type":"string"},"name":{"type":"string"}},"required":["place_id","formatted"]}}},"required":["results"]},"GeoapifyBoundariesResponse":{}},"parameters":{"CountryQueryParam":{"name":"country","in":"query","required":false,"schema":{"$ref":"#/components/schemas/CountryCode"},"description":"ISO 3166-1 alpha-2 country code. PT, ES, IT, UK, or FR on location and address surfaces.","example":"PT"},"KindsQueryParam":{"name":"kinds","in":"query","required":false,"schema":{"$ref":"#/components/schemas/FilterKinds"},"example":"town,district"},"LevelsQueryParam":{"name":"levels","in":"query","required":false,"schema":{"$ref":"#/components/schemas/FilterLevels"},"example":"4,5"},"ParentQueryParam":{"name":"parent_id","in":"query","required":false,"schema":{"$ref":"#/components/schemas/FilterParentId"},"example":"0-EU-PT-11"},"BboxQueryParam":{"name":"bbox","in":"query","required":false,"schema":{"$ref":"#/components/schemas/FilterBbox"},"example":"-9.2,38.7,-9.0,38.8"},"NearQueryParam":{"name":"near","in":"query","required":false,"schema":{"$ref":"#/components/schemas/FilterNear"},"example":"-9.138168592,38.710022004"},"RadiusQueryParam":{"name":"radius_m","in":"query","required":false,"schema":{"$ref":"#/components/schemas/FilterRadiusM"},"example":5000},"LangQueryParam":{"name":"lang","in":"query","required":false,"schema":{"$ref":"#/components/schemas/FilterLang"},"example":"en"},"PaginationQueryParam":{"name":"pagination","in":"query","required":false,"schema":{"$ref":"#/components/schemas/PaginationQueryParam"}},"LimitQueryParam":{"name":"limit","in":"query","required":false,"schema":{"$ref":"#/components/schemas/FilterLimit"},"example":25},"OffsetQueryParam":{"name":"offset","in":"query","required":false,"schema":{"$ref":"#/components/schemas/FilterOffset"},"example":0},"CursorQueryParam":{"name":"cursor","in":"query","required":false,"schema":{"$ref":"#/components/schemas/FilterCursor"}},"SridQueryParam":{"name":"srid","in":"query","required":false,"schema":{"$ref":"#/components/schemas/FilterSrid"},"example":4326}},"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"x-api-key","description":"API key required on all /v1 routes. Set REFERENCE_API_KEY in .env to pre-fill the Scalar reference UI. Provider routes: REFERENCE_GOOGLE_API_KEY and REFERENCE_GEOAPIFY_API_KEY.","example":""},"GoogleApiKeyAuth":{"type":"apiKey","in":"header","name":"x-google-api-key","description":"Customer Google Maps/Places API key (BYO). Required on `/v1/providers/google/*` routes. Set REFERENCE_GOOGLE_API_KEY in .env to pre-fill Scalar.","example":"your-google-maps-api-key"},"GeoapifyApiKeyAuth":{"type":"apiKey","in":"header","name":"x-geoapify-api-key","description":"Customer Geoapify API key (BYO). Required on `/v1/providers/geoapify/*` routes. Set REFERENCE_GEOAPIFY_API_KEY in .env to pre-fill Scalar.","example":"your-geoapify-api-key"}},"headers":{"RateLimitLimit":{"description":"Requests permitted in the current window.","schema":{"type":"integer"}},"RateLimitRemaining":{"description":"Requests remaining in the current window.","schema":{"type":"integer"}},"RateLimitReset":{"description":"Seconds until the current window resets.","schema":{"type":"integer"}},"RateLimitPolicy":{"description":"Active rate-limit policy descriptor.","schema":{"type":"string"}},"RetryAfter":{"description":"Seconds to wait before retrying (sent on 429).","schema":{"type":"integer"}},"MapbaseCredits":{"description":"Credit cost charged for this successful request. Request-aware (autocomplete limit/include, boundaries format, include=polylines). The x-mapbase-credits operation extension is the base path cost only.","schema":{"type":"integer","minimum":0}}},"responses":{"Unauthorized":{"description":"Missing or invalid API key (`auth_missing_key` / `auth_invalid_key`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"Forbidden":{"description":"Request origin or IP is not allowed (`domain_forbidden` / `ip_forbidden`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"RateLimited":{"description":"Rate limit or quota exceeded (`rate_limited` / `daily_quota_exceeded` / `monthly_quota_exceeded`).","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"PaymentRequired":{"description":"Credits exhausted or payment blocked (`payment_required`). Update billing to continue.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"InternalError":{"description":"Unexpected server error (`internal_error`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"ServiceUnavailable":{"description":"A data dependency is temporarily unavailable (`service_unavailable`). Retry shortly.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}}}},"paths":{"/health":{"get":{"tags":["health"],"summary":"Liveness probe","description":"Unversioned health check for load balancers and uptime monitors. Does not require an API key.","responses":{"200":{"description":"Service is up.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HealthResponse"}}}}}}},"/redis-health":{"get":{"tags":["health"],"summary":"Redis connectivity probe","description":"Unversioned Redis health check for ops debugging. Does not require an API key. Returns 503 when Redis is unreachable.","responses":{"200":{"description":"Redis is reachable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RedisHealthResponse"}}}},"503":{"description":"Redis is unreachable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RedisHealthResponse"}}}}}}},"/layers":{"get":{"tags":["layers"],"summary":"List registry layers","description":"Unversioned registry layer counts. Does not require an API key.","responses":{"200":{"description":"Layer counts from search_registry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LayersResponse"}}}}}}},"/v1/locations":{"get":{"tags":["locations"],"summary":"List locations","description":"List and filter locations. Supports text search via `q`, but typeahead belongs to `/v1/autocomplete`.\n\nExamples:\n- `GET /v1/locations?country=PT&kind=municipality`\n- `GET /v1/locations?q=lisboa&country=PT`","parameters":[{"schema":{"type":"integer","minimum":1,"maximum":200,"default":25,"example":25},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string"},"required":false,"name":"cursor","in":"query"},{"schema":{"type":"string","minLength":2,"maxLength":2,"example":"PT"},"required":false,"name":"country","in":"query"},{"schema":{"type":"string","enum":["arrondissement","autonomous_city","autonomous_region","comarca","continent","country","country_division","county","department","district","external_region","island","municipality","microstate","neighborhood","overseas_department","parish","province","region","town","ward"],"example":"municipality"},"required":false,"name":"kind","in":"query"},{"schema":{"type":"string","example":"mb_loc_MC1FVS1QVC0xMQ"},"required":false,"name":"parent_id","in":"query"},{"schema":{"type":["integer","null"],"minimum":0,"maximum":7,"example":4},"required":false,"name":"level","in":"query"},{"schema":{"type":"string","example":"lisboa"},"required":false,"name":"q","in":"query"},{"schema":{"type":"array","items":{"type":"string","enum":["centroid","bbox","polylines"]},"example":["centroid","polylines"]},"required":false,"name":"include","in":"query"}],"responses":{"200":{"description":"A page of locations.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LocationListResponse"}}},"headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"},"X-Mapbase-Credits":{"$ref":"#/components/headers/MapbaseCredits"}}},"400":{"description":"Invalid query parameters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}},"security":[{"ApiKeyAuth":[]}],"x-mapbase-credits":1,"x-mapbase-credits-formula":"limit (×2 with include=polylines or format=geojson)"}},"/v1/locations/{identifier}/relations":{"get":{"tags":["locations"],"summary":"Get location hierarchy","description":"Navigate parent, children, siblings, and ancestors for a location.\n\nDefault `relations=parent,children,ancestors`. Use `include` for geometry on nodes only.\n\nExample: `GET /v1/locations/mb_loc_MC1FVS1QVC0xMS0wNg/relations?relations=children,ancestors`","parameters":[{"schema":{"type":"string","example":"mb_loc_MC1FVS1QVC0xMS0wNg"},"required":true,"name":"identifier","in":"path"},{"schema":{"type":"integer","minimum":1,"maximum":200,"default":25,"example":25},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string"},"required":false,"name":"cursor","in":"query"},{"schema":{"type":["integer","null"],"minimum":0},"required":false,"name":"offset","in":"query"},{"schema":{"type":"string","minLength":2,"maxLength":2,"example":"PT"},"required":false,"name":"country","in":"query"},{"schema":{"type":"array","items":{"type":"string","enum":["parent","children","siblings","ancestors"]},"example":["parent","children","ancestors","siblings"]},"required":false,"name":"relations","in":"query"},{"schema":{"type":"array","items":{"type":"string","enum":["arrondissement","autonomous_city","autonomous_region","comarca","continent","country","country_division","county","department","district","external_region","island","municipality","microstate","neighborhood","overseas_department","parish","province","region","town","ward"]},"example":["municipality"]},"required":false,"name":"kind","in":"query"},{"schema":{"type":"array","items":{"type":["integer","null"],"minimum":0,"maximum":7},"example":[5,6]},"required":false,"name":"level","in":"query"},{"schema":{"type":"array","items":{"type":"string","enum":["centroid","bbox","polylines"]},"example":["centroid","polylines"]},"required":false,"name":"include","in":"query"}],"responses":{"200":{"description":"Selected location relations.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LocationRelationsResponse"}}},"headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"},"X-Mapbase-Credits":{"$ref":"#/components/headers/MapbaseCredits"}}},"400":{"description":"Invalid query or ambiguous URI.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"Location not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Duplicate uri rows.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"503":{"$ref":"#/components/responses/ServiceUnavailable"}},"security":[{"ApiKeyAuth":[]}],"x-mapbase-credits":1,"x-mapbase-credits-formula":"limit (×2 with include=polylines or format=geojson)"}},"/v1/locations/{identifier}/boundary":{"get":{"tags":["locations"],"summary":"Get location boundary","description":"Polygon geometry for a location. Accepts canonical `mb_loc_*` id only (no URI).\n\nExample: `GET /v1/locations/mb_loc_MC1FVS1QVC0xMS0wNg/boundary?simplify=0.001&srid=4326`","parameters":[{"schema":{"type":"string","example":"mb_loc_MC1FVS1QVC0xMS0wNg"},"required":true,"name":"identifier","in":"path"},{"schema":{"type":["number","null"],"minimum":0,"example":0.001},"required":false,"name":"simplify","in":"query"},{"schema":{"type":["integer","null"],"example":4326},"required":false,"name":"srid","in":"query"}],"responses":{"200":{"description":"GeoJSON boundary for the location.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BoundaryResponse"}}},"headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"},"X-Mapbase-Credits":{"$ref":"#/components/headers/MapbaseCredits"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"Location or boundary not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}},"security":[{"ApiKeyAuth":[]}],"x-mapbase-credits":1,"x-mapbase-credits-formula":"1 (×2 with include=polylines or format=geojson)"}},"/v1/locations/{identifier}/zones":{"get":{"tags":["locations"],"summary":"List location zones","description":"Returns active zones anchored to the location (`search_registry.parent_id` = location `mb_loc_*` id).\n\nExample: `GET /v1/locations/mb_loc_MC1FVS1QVC0xMS0wNg/zones`","parameters":[{"schema":{"type":"string","example":"mb_loc_MC1FVS1QVC0xMS0wNg"},"required":true,"name":"identifier","in":"path"},{"schema":{"type":"integer","minimum":1,"maximum":200,"default":25,"example":25},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string"},"required":false,"name":"cursor","in":"query"},{"schema":{"type":["integer","null"],"minimum":0},"required":false,"name":"offset","in":"query"},{"schema":{"type":"array","items":{"type":"string","enum":["arrondissement","autonomous_city","autonomous_region","comarca","continent","country","country_division","county","department","district","external_region","island","municipality","microstate","neighborhood","overseas_department","parish","province","region","town","ward"]},"example":["municipality"]},"required":false,"name":"kind","in":"query"},{"schema":{"type":"array","items":{"type":["integer","null"],"minimum":0,"maximum":7}},"required":false,"name":"level","in":"query"},{"schema":{"type":"array","items":{"type":"string","enum":["centroid","bbox","polylines"]}},"required":false,"name":"include","in":"query"},{"schema":{"type":"string","minLength":2,"maxLength":2,"example":"PT"},"required":false,"name":"country","in":"query"}],"responses":{"200":{"description":"Zones anchored to the location.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ZoneListResponse"}}},"headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"},"X-Mapbase-Credits":{"$ref":"#/components/headers/MapbaseCredits"}}},"400":{"description":"Invalid query parameters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"Location not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Duplicate uri rows.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"503":{"$ref":"#/components/responses/ServiceUnavailable"}},"security":[{"ApiKeyAuth":[]}],"x-mapbase-credits":1,"x-mapbase-credits-formula":"1 (×2 with include=polylines or format=geojson)"}},"/v1/locations/{identifier}":{"get":{"tags":["locations"],"summary":"Get location","description":"Fetch one location by canonical `mb_loc_*` id, upstream ingestion id, or URL-encoded URI.\n\nOptional `parent=true` and `hierarchy=true` embed the immediate parent and depth-keyed ancestor chain. Use `include` for geometry on returned nodes; `postcodes` embeds Eurostat codes linked to this location and its subdivisions.\n\nExamples:\n- `GET /v1/locations/mb_loc_MC1FVS1QVC0xMS0wNg`\n- `GET /v1/locations/0-EU-PT-11-06?parent=true&hierarchy=true`\n- `GET /v1/locations/lisboa?country=PT&include=postcodes`\n- `GET /v1/locations/santa-maria-maior%2Fbaixa?country=PT`","parameters":[{"schema":{"type":"string","example":"mb_loc_MC1FVS1QVC0xMS0wNg"},"required":true,"name":"identifier","in":"path"},{"schema":{"type":"string","minLength":2,"maxLength":2,"example":"PT"},"required":false,"name":"country","in":"query"},{"schema":{"type":"array","items":{"type":"string","enum":["centroid","bbox","polylines","postcodes"]},"example":["centroid","polylines","postcodes"]},"required":false,"name":"include","in":"query"},{"schema":{"type":["boolean","null"],"example":true},"required":false,"name":"parent","in":"query"},{"schema":{"type":["boolean","null"],"example":true},"required":false,"name":"hierarchy","in":"query"}],"responses":{"200":{"description":"A single location.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LocationDetail"}}},"headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"},"X-Mapbase-Credits":{"$ref":"#/components/headers/MapbaseCredits"}}},"400":{"description":"Ambiguous URI without country.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"Location not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Duplicate uri rows.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"503":{"$ref":"#/components/responses/ServiceUnavailable"}},"security":[{"ApiKeyAuth":[]}],"x-mapbase-credits":1,"x-mapbase-credits-formula":"1 (×2 with include=polylines or format=geojson)"}},"/v1/points/resolve":{"get":{"tags":["points"],"summary":"Resolve a coordinate","description":"Resolve WGS84 coordinates to administrative context: anchor, hierarchy, and zones at the point.\n\nOptional `include=postcodes` adds `anchor.postcode` — the Eurostat code at the input coordinates (same lookup as `GET /v1/postcodes/by-point`), or `null` when none matches — and embeds Eurostat codes linked to the anchor location and its subdivisions on `anchor.postcodes`.\n\nCredits per request:\n- **2** base\n- **5** with `include=polylines`","parameters":[{"schema":{"type":"string","example":"38.710022004"},"required":true,"name":"lat","in":"query"},{"schema":{"type":"string","example":"-9.138168592"},"required":true,"name":"lng","in":"query"},{"schema":{"type":"string","minLength":2,"maxLength":2,"example":"PT"},"required":false,"name":"country","in":"query"},{"schema":{"type":"array","items":{"type":"string","enum":["locations","zones"]},"default":["locations","zones"],"example":["locations","zones"]},"required":false,"name":"layers","in":"query"},{"schema":{"type":"array","items":{"type":"string","enum":["centroid","bbox","polylines","postcodes"]},"example":["centroid","polylines","postcodes"]},"required":false,"name":"include","in":"query"}],"responses":{"200":{"description":"Point resolve result.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PointResolveResponse"}}},"headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"},"X-Mapbase-Credits":{"$ref":"#/components/headers/MapbaseCredits"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"No matching layers at the point.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}},"security":[{"ApiKeyAuth":[]}],"x-mapbase-credits":2,"x-mapbase-credits-formula":"2 (×2 with include=polylines or format=geojson)"}},"/v1/autocomplete":{"get":{"tags":["autocomplete"],"summary":"Unified autocomplete","description":"Search-as-you-type across registry layers - locations, postcodes, and zones. Pass `layers` to scope results.\n\nExample: `GET /v1/autocomplete?layers=locations&q=lisboa`","parameters":[{"schema":{"type":"string","minLength":1,"example":"lisboa"},"required":true,"name":"q","in":"query"},{"schema":{"type":"string","minLength":2,"maxLength":2,"example":"PT"},"required":false,"name":"country","in":"query"},{"schema":{"type":"array","items":{"type":"string","enum":["locations","postcodes","zones"]},"example":["locations","zones"]},"required":false,"name":"layers","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":50,"default":5,"example":10},"required":false,"name":"limit","in":"query"},{"schema":{"type":["number","null"],"example":38.710022004},"required":false,"name":"lat","in":"query"},{"schema":{"type":["number","null"],"example":-9.138168592},"required":false,"name":"lng","in":"query"},{"schema":{"type":"array","items":{"type":"string","enum":["centroid","bbox","polylines"]},"example":["centroid","polylines"]},"required":false,"name":"include","in":"query"},{"schema":{"type":"string","description":"Comma-separated list of location kinds to include. Defaults to all kinds.","example":"town,district"},"required":false,"description":"Comma-separated list of location kinds to include. Defaults to all kinds.","name":"kinds","in":"query"}],"responses":{"200":{"description":"Autocomplete suggestions.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AutocompleteResponse"}}},"headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"},"X-Mapbase-Credits":{"$ref":"#/components/headers/MapbaseCredits"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}},"security":[{"ApiKeyAuth":[]}],"x-mapbase-credits":1,"x-mapbase-credits-formula":"limit (×2 with include=polylines or format=geojson)"}},"/v1/postcodes":{"get":{"tags":["postcodes"],"summary":"List postcodes","description":"Paginated list of Eurostat postcodes from the registry matview.\n\nFilter by `country`, exact `code`, parent LAU `gisco_id`, linked `location_id` (canonical `mb_loc_*`), or free-text `q` on the normalized code. Keyset pagination uses `cursor` on `pc_cntr`.\n\nOptional `include`: `centroid`, `bbox`, or `polylines` embed geometry on each row.\n\nExamples:\n- `GET /v1/postcodes?country=PT&code=1000-001&limit=1`\n- `GET /v1/postcodes?country=PT&gisco_id=PT_110665&include=centroid`","parameters":[{"schema":{"type":"integer","minimum":1,"maximum":200,"default":25,"example":25},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string"},"required":false,"name":"cursor","in":"query"},{"schema":{"type":"string","minLength":2,"maxLength":2,"example":"PT"},"required":false,"name":"country","in":"query"},{"schema":{"type":"string","example":"1100-062"},"required":false,"name":"code","in":"query"},{"schema":{"type":"string"},"required":false,"name":"gisco_id","in":"query"},{"schema":{"type":"string","example":"mb_loc_MC1FVS1QVC0xMS0wNi0wNjUtNjUtMDI"},"required":false,"name":"location_id","in":"query"},{"schema":{"type":"string","example":"lisboa"},"required":false,"name":"q","in":"query"},{"schema":{"type":"array","items":{"type":"string","enum":["centroid","bbox","polylines"]},"example":["centroid","polylines"]},"required":false,"name":"include","in":"query"}],"responses":{"200":{"description":"A page of postcodes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PostcodeListResponse"}}},"headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"},"X-Mapbase-Credits":{"$ref":"#/components/headers/MapbaseCredits"}}},"400":{"description":"Invalid query parameters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}},"security":[{"ApiKeyAuth":[]}],"x-mapbase-credits":1,"x-mapbase-credits-formula":"limit (×2 with include=polylines or format=geojson)"}},"/v1/postcodes/by-point":{"get":{"tags":["postcodes"],"summary":"Get postcode by coordinates","description":"Reverse geocode a WGS84 point to the Eurostat postcode that contains it.\n\nThe query builds a PostGIS point and searches `postal_codes` (joined to LAU regions): a hit matches when the postcode polygon contains the point, or when the postcode has no geometry and the linked LAU polygon does.\n\nOptional `country` filters to registry countries (PT, ES, IT, UK, FR); a country mismatch returns 404. Optional `include` embeds `centroid`, `bbox`, or `polylines` on the response.\n\nExamples:\n- `GET /v1/postcodes/by-point?lat=38.7223&lng=-9.1393`\n- `GET /v1/postcodes/by-point?lat=38.7223&lng=-9.1393&country=PT&include=centroid`","parameters":[{"schema":{"type":"string","example":"38.710022004"},"required":true,"name":"lat","in":"query"},{"schema":{"type":"string","example":"-9.138168592"},"required":true,"name":"lng","in":"query"},{"schema":{"type":"string","minLength":2,"maxLength":2,"example":"PT"},"required":false,"name":"country","in":"query"},{"schema":{"type":"array","items":{"type":"string","enum":["centroid","bbox","polylines"]},"example":["centroid","polylines"]},"required":false,"name":"include","in":"query"}],"responses":{"200":{"description":"Postcode containing the point.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Postcode"}}},"headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"},"X-Mapbase-Credits":{"$ref":"#/components/headers/MapbaseCredits"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"No postcode covers the point.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}},"security":[{"ApiKeyAuth":[]}],"x-mapbase-credits":1,"x-mapbase-credits-formula":"1 (×2 with include=polylines or format=geojson)"}},"/v1/postcodes/{identifier}":{"get":{"tags":["postcodes"],"summary":"Get postcode","description":"Fetch one postcode by canonical `mb_cod_*` id or Eurostat `pc_cntr`.\n\nWhen the postcode is linked to a location, optional `parent=true` and `hierarchy=true` embed that location's immediate parent and depth-keyed ancestor chain (same shape as location detail). Use `include` for geometry on returned nodes.\n\nOptional `include`: `centroid`, `bbox`, or `polylines` embed geometry from the registry matview.\n\nExamples:\n- `GET /v1/postcodes/mb_cod_abc123`\n- `GET /v1/postcodes/PT-1000-001?country=PT&include=centroid`\n- `GET /v1/postcodes/PT-1000-001?parent=true&hierarchy=true`","parameters":[{"schema":{"type":"string","example":"mb_cod_UFRfMTEwMC0wNjI"},"required":true,"name":"identifier","in":"path"},{"schema":{"type":"string","minLength":2,"maxLength":2,"example":"PT"},"required":false,"name":"country","in":"query"},{"schema":{"type":"array","items":{"type":"string","enum":["centroid","bbox","polylines"]},"example":["centroid","polylines"]},"required":false,"name":"include","in":"query"},{"schema":{"type":["boolean","null"],"example":true},"required":false,"name":"parent","in":"query"},{"schema":{"type":["boolean","null"],"example":true},"required":false,"name":"hierarchy","in":"query"}],"responses":{"200":{"description":"A single postcode.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PostcodeDetail"}}},"headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"},"X-Mapbase-Credits":{"$ref":"#/components/headers/MapbaseCredits"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"Postcode not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}},"security":[{"ApiKeyAuth":[]}],"x-mapbase-credits":1,"x-mapbase-credits-formula":"1 (×2 with include=polylines or format=geojson)"}},"/v1/zones":{"get":{"tags":["zones"],"summary":"List zones","description":"Lists active zones from the registry. Filter by canonical location id (`mb_loc_*` on `location_id`). Only active zones are indexed in `search_registry`.","parameters":[{"schema":{"type":"integer","minimum":1,"maximum":200,"default":25,"example":25},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string"},"required":false,"name":"cursor","in":"query"},{"schema":{"type":"string","minLength":2,"maxLength":2,"example":"PT"},"required":false,"name":"country","in":"query"},{"schema":{"type":"string","example":"zone"},"required":false,"name":"kind","in":"query"},{"schema":{"type":"string","example":"mb_loc_MC1FVS1QVC0xMS0wNg"},"required":false,"name":"location_id","in":"query"},{"schema":{"type":"string","example":"baixa"},"required":false,"name":"q","in":"query"},{"schema":{"type":"array","items":{"type":"string","enum":["centroid","bbox","polylines"]},"example":["centroid","polylines"]},"required":false,"name":"include","in":"query"}],"responses":{"200":{"description":"A page of zones.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ZoneListResponse"}}},"headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"},"X-Mapbase-Credits":{"$ref":"#/components/headers/MapbaseCredits"}}},"400":{"description":"Invalid query parameters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}},"security":[{"ApiKeyAuth":[]}],"x-mapbase-credits":1,"x-mapbase-credits-formula":"limit (×2 with include=polylines or format=geojson)"}},"/v1/zones/{identifier}/boundary":{"get":{"tags":["zones"],"summary":"Get zone boundary","description":"Polygon geometry for a zone. Accepts canonical `mb_zon_*` id or upstream zone id (no URI).\n\nExample: `GET /v1/zones/mb_zon_UFQtWi0xMDAwOQ/boundary?simplify=0.001&srid=4326`","parameters":[{"schema":{"type":"string","example":"mb_zon_UFQtWi0xMDAwOQ"},"required":true,"name":"identifier","in":"path"},{"schema":{"type":["number","null"],"minimum":0,"example":0.001},"required":false,"name":"simplify","in":"query"},{"schema":{"type":["integer","null"],"example":4326},"required":false,"name":"srid","in":"query"}],"responses":{"200":{"description":"GeoJSON boundary for the zone.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BoundaryResponse"}}},"headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"},"X-Mapbase-Credits":{"$ref":"#/components/headers/MapbaseCredits"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"No boundary stored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}},"security":[{"ApiKeyAuth":[]}],"x-mapbase-credits":1,"x-mapbase-credits-formula":"1 (×2 with include=polylines or format=geojson)"}},"/v1/zones/{identifier}":{"get":{"tags":["zones"],"summary":"Get zone","description":"Fetch one zone by canonical `mb_zon_*` id, upstream zone id, or URL-encoded URI.\n\nExamples:\n- `GET /v1/zones/mb_zon_UFQtWi0xMDAwOQ`\n- `GET /v1/zones/PT-Z-10009`\n- `GET /v1/zones/baixa-chiado?country=PT`","parameters":[{"schema":{"type":"string","example":"mb_zon_UFQtWi0xMDAwOQ"},"required":true,"name":"identifier","in":"path"},{"schema":{"type":"string","minLength":2,"maxLength":2,"example":"PT"},"required":false,"name":"country","in":"query"},{"schema":{"type":"array","items":{"type":"string","enum":["centroid","bbox","polylines"]},"example":["centroid","polylines"]},"required":false,"name":"include","in":"query"}],"responses":{"200":{"description":"A single zone.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Zone"}}},"headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"},"X-Mapbase-Credits":{"$ref":"#/components/headers/MapbaseCredits"}}},"400":{"description":"Ambiguous URI without country.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"Zone not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Duplicate uri rows.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"503":{"$ref":"#/components/responses/ServiceUnavailable"}},"security":[{"ApiKeyAuth":[]}],"x-mapbase-credits":1,"x-mapbase-credits-formula":"1 (×2 with include=polylines or format=geojson)"}},"/v1/zone-submissions":{"post":{"tags":["zone-submissions"],"summary":"Create a zone submission draft","description":"Creates a draft zone submission for admin review. Does not publish to the zones registry.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ZoneSubmissionCreate"}}}},"responses":{"201":{"description":"Draft submission created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ZoneSubmission"}}},"headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"},"X-Mapbase-Credits":{"$ref":"#/components/headers/MapbaseCredits"}}},"400":{"description":"Invalid request body.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"description":"URI conflict.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Internal error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"503":{"$ref":"#/components/responses/ServiceUnavailable"}},"security":[{"ApiKeyAuth":[]}],"x-mapbase-credits":0,"x-mapbase-credits-formula":"0 (not billed)"},"get":{"tags":["zone-submissions"],"summary":"List zone submissions","description":"Lists zone submissions owned by the authenticated user.","parameters":[{"schema":{"type":"integer","minimum":1,"maximum":50,"default":50,"example":50},"required":false,"name":"limit","in":"query"},{"schema":{"type":["integer","null"],"minimum":0,"default":0,"example":0},"required":false,"name":"offset","in":"query"},{"schema":{"type":"string","enum":["draft","submitted","approved","rejected"],"example":"draft"},"required":false,"name":"status","in":"query"}],"responses":{"200":{"description":"A page of submissions.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ZoneSubmissionListResponse"}}},"headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"},"X-Mapbase-Credits":{"$ref":"#/components/headers/MapbaseCredits"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}},"security":[{"ApiKeyAuth":[]}],"x-mapbase-credits":0,"x-mapbase-credits-formula":"0 (not billed)"}},"/v1/zone-submissions/{id}":{"get":{"tags":["zone-submissions"],"summary":"Get a zone submission","parameters":[{"schema":{"type":"string","format":"uuid","example":"00000000-0000-4000-8000-000000000001"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Submission details.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ZoneSubmission"}}},"headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"},"X-Mapbase-Credits":{"$ref":"#/components/headers/MapbaseCredits"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"Submission not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}},"security":[{"ApiKeyAuth":[]}],"x-mapbase-credits":0,"x-mapbase-credits-formula":"0 (not billed)"},"patch":{"tags":["zone-submissions"],"summary":"Update a zone submission","description":"Updates a draft or rejected submission owned by the caller.","parameters":[{"schema":{"type":"string","format":"uuid","example":"00000000-0000-4000-8000-000000000001"},"required":true,"name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ZoneSubmissionUpdate"}}}},"responses":{"200":{"description":"Updated submission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ZoneSubmission"}}},"headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"},"X-Mapbase-Credits":{"$ref":"#/components/headers/MapbaseCredits"}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"Submission not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"409":{"description":"Conflict (not editable or URI taken).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Internal error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"503":{"$ref":"#/components/responses/ServiceUnavailable"}},"security":[{"ApiKeyAuth":[]}],"x-mapbase-credits":0,"x-mapbase-credits-formula":"0 (not billed)"},"delete":{"tags":["zone-submissions"],"summary":"Delete a zone submission","description":"Deletes a draft or rejected submission owned by the caller.","parameters":[{"schema":{"type":"string","format":"uuid","example":"00000000-0000-4000-8000-000000000001"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Submission deleted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ZoneSubmissionDeleteResponse"}}},"headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"},"X-Mapbase-Credits":{"$ref":"#/components/headers/MapbaseCredits"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"description":"Submission cannot be deleted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"404":{"description":"Submission not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}},"security":[{"ApiKeyAuth":[]}],"x-mapbase-credits":0,"x-mapbase-credits-formula":"0 (not billed)"}},"/v1/zone-submissions/{id}/submit":{"post":{"tags":["zone-submissions"],"summary":"Submit a zone submission for review","description":"Transitions a draft or rejected submission to submitted status for admin review.","parameters":[{"schema":{"type":"string","format":"uuid","example":"00000000-0000-4000-8000-000000000001"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Submitted submission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ZoneSubmission"}}},"headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"},"X-Mapbase-Credits":{"$ref":"#/components/headers/MapbaseCredits"}}},"400":{"description":"Invalid submission state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"Submission not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"409":{"description":"Conflict.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Internal error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"503":{"$ref":"#/components/responses/ServiceUnavailable"}},"security":[{"ApiKeyAuth":[]}],"x-mapbase-credits":0,"x-mapbase-credits-formula":"0 (not billed)"}},"/v1/boundaries":{"get":{"tags":["boundaries"],"summary":"Get boundaries","description":"Bulk boundary fetch with spatial and registry filters. Default output is encoded polylines (`format=polyline`); GeoJSON is capped aggressively.\n\n`country` defaults to `PT`. Requires at least one narrowing filter: `identifier`, `country`, `bbox`, `near`, or `parent_id`.\n\nFor a single known entity, use the layer route: `/v1/locations/{identifier}/boundary`, `/v1/zones/{identifier}/boundary`, or `/v1/lau/{identifier}/boundary`.\n\nExamples:\n- `GET /v1/boundaries?layer=locations&country=PT&level=4`\n- `GET /v1/boundaries?layer=zones&bbox=-9.2,38.7,-9.0,38.8&format=polyline`\n- `GET /v1/boundaries?identifier=mb_loc_a,mb_zon_b,mb_lau_c`","parameters":[{"schema":{"type":"integer","minimum":1,"maximum":10000,"default":25,"example":25},"required":true,"name":"limit","in":"query"},{"schema":{"type":"string"},"required":false,"name":"cursor","in":"query"},{"schema":{"type":["array","null"],"items":{"type":"string","enum":["locations","zones"]},"minItems":1,"default":["locations"],"example":["locations"]},"required":true,"name":"layer","in":"query","style":"form","explode":true},{"schema":{"type":["array","null"],"items":{"type":"string"},"minItems":1,"example":["mb_loc_MC1FVS1QVC0xMS0wNg"]},"required":false,"name":"identifier","in":"query"},{"schema":{"type":"string","enum":["PT","ES","IT","UK","FR"],"default":"PT","example":"PT"},"required":true,"name":"country","in":"query"},{"schema":{"type":"array","items":{"type":"string","enum":["arrondissement","autonomous_city","autonomous_region","comarca","continent","country","country_division","county","department","district","external_region","island","municipality","microstate","neighborhood","overseas_department","parish","province","region","town","ward","beach","zone"]},"minItems":1},"required":false,"name":"kind","in":"query"},{"schema":{"type":"array","items":{"type":"integer","minimum":0,"maximum":7,"enum":[0,1,2,3,4,5,6,7]},"minItems":1,"example":[4],"default":[4]},"required":false,"name":"level","in":"query","style":"form","explode":true},{"schema":{"type":"string","example":"-9.2,38.7,-9.0,38.8"},"required":false,"name":"bbox","in":"query"},{"schema":{"type":"string","example":"-9.138168592,38.710022004"},"required":false,"name":"near","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":50000,"example":5000},"required":false,"name":"radius_m","in":"query"},{"schema":{"type":"string","example":"mb_loc_MC1FVS1QVC0xMQ"},"required":false,"name":"parent_id","in":"query"},{"schema":{"type":"string","enum":["geojson","polyline"],"default":"polyline","example":"polyline"},"required":true,"name":"format","in":"query"},{"schema":{"type":["number","null"],"minimum":0,"example":0.001},"required":false,"name":"simplify","in":"query"},{"schema":{"type":["integer","null"],"example":4326},"required":false,"name":"srid","in":"query"}],"responses":{"200":{"description":"A page of boundary items.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BoundaryListResponse"}}},"headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"},"X-Mapbase-Credits":{"$ref":"#/components/headers/MapbaseCredits"}}},"400":{"description":"Invalid or ambiguous query.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"Referenced location not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"422":{"description":"Result set too large (GeoJSON).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}},"security":[{"ApiKeyAuth":[]}],"x-mapbase-credits":1,"x-mapbase-credits-formula":"limit (×2 with include=polylines or format=geojson)"}},"/v1/seo/page":{"get":{"tags":["seo"],"summary":"Full page SEO","description":"Returns entity context, breadcrumbs, meta tags, JSON-LD, and optional internal-link sections for a registry entity or coordinate. Resolve by `identifier`, `uri`+`country`, or `lng`+`lat` (exactly one mode). With `uri`+`country`, matches locations and zones by crawl uri, and postcodes by URL slug (e.g. `1000-001`, `SW1A-1AA`). Postcode `identifier` accepts `mb_cod_*`, Eurostat `pc_cntr`, or bare code with `country`.","parameters":[{"schema":{"type":["boolean","null"],"default":true},"required":false,"name":"include_country_prefix","in":"query"},{"schema":{"type":["integer","null"],"minimum":0,"maximum":7},"required":false,"name":"from_level","in":"query"},{"schema":{"type":["integer","null"],"minimum":0,"maximum":7,"default":0},"required":false,"name":"filter_level","in":"query"},{"schema":{"type":["boolean","null"],"default":false},"required":false,"name":"include_intermediate_regions","in":"query"},{"schema":{"type":"string","example":"mb_loc_MC1FVS1QVC0xMS0wNg","default":"mb_loc_MC1FVS1QVC0xMS0wNg"},"required":false,"name":"identifier","in":"query"},{"schema":{"type":"string","example":"lisboa"},"required":false,"name":"uri","in":"query","examples":{"default":{"value":"lisboa","x-disabled":false},"postcode":{"summary":"Postcode URL slug","description":"Postcode slug with country, e.g. ?uri=1100-062&country=PT","value":"1100-062"}}},{"schema":{"type":["number","null"],"minimum":-180,"maximum":180,"example":"-9.138168592"},"required":false,"name":"lng","in":"query"},{"schema":{"type":["number","null"],"minimum":-90,"maximum":90,"example":"38.710022004"},"required":false,"name":"lat","in":"query"},{"schema":{"type":"string","enum":["PT","ES","IT","UK","FR"],"example":"PT","default":"PT"},"required":false,"name":"country","in":"query","examples":{"default":{"value":"PT","x-disabled":false}}},{"schema":{"type":"string","format":"uri","example":"https://mapbase.dev"},"required":false,"name":"base_url","in":"query","examples":{"default":{"value":"https://mapbase.dev","x-disabled":false}}},{"schema":{"type":"string","minLength":1,"maxLength":120,"example":"Mapbase"},"required":false,"name":"site_name","in":"query","examples":{"default":{"value":"Mapbase","x-disabled":false}}},{"schema":{"type":"string","minLength":2,"maxLength":10},"required":false,"name":"locale","in":"query"},{"schema":{"type":"string","minLength":1,"maxLength":64},"required":false,"name":"template","in":"query"},{"schema":{"type":"string"},"required":false,"name":"include","in":"query"}],"responses":{"200":{"description":"SEO page bundle.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SeoPageResponse"}}},"headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"},"X-Mapbase-Credits":{"$ref":"#/components/headers/MapbaseCredits"}}},"400":{"description":"Invalid or ambiguous request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"Entity not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Duplicate uri rows.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"503":{"$ref":"#/components/responses/ServiceUnavailable"}},"security":[{"ApiKeyAuth":[]}],"x-mapbase-credits":0,"x-mapbase-credits-formula":"0 (not billed)"}},"/v1/seo/tree":{"get":{"tags":["seo"],"summary":"SEO directory tree nodes","description":"Returns paginated child nodes and internal-link sections for SEO navigation.","parameters":[{"schema":{"type":"string","enum":["PT","ES","IT","UK","FR"],"example":"PT"},"required":true,"name":"country","in":"query"},{"schema":{"type":"string","enum":["locations","postcodes","zones"],"example":"locations"},"required":false,"name":"layer","in":"query"},{"schema":{"type":"string","example":"mb_loc_MC1FVS1QVC0xMS0wNg"},"required":false,"name":"parent_id","in":"query"},{"schema":{"type":"string","example":"mb_loc_MC1FVS1QVC0xMS0wNg"},"required":false,"name":"identifier","in":"query"},{"schema":{"type":"string"},"required":false,"name":"uri","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":200,"default":50,"example":25},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string"},"required":false,"name":"cursor","in":"query"}],"responses":{"200":{"description":"SEO directory tree sections.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SeoTreeResponse"}}},"headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"},"X-Mapbase-Credits":{"$ref":"#/components/headers/MapbaseCredits"}}},"400":{"description":"Invalid query parameters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"Parent entity not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}},"security":[{"ApiKeyAuth":[]}],"x-mapbase-credits":0,"x-mapbase-credits-formula":"0 (not billed)"}},"/v1/seo/sitemap":{"get":{"tags":["seo"],"summary":"Sitemap","description":"Use `mode=shards` for the sitemap index manifest, or `shard=pt-locations-0` for up to 10k canonical URLs in one shard. Optional `base_url` adds absolute `loc` on shard entries.","parameters":[{"schema":{"type":"string","enum":["shards"],"example":"shards"},"required":false,"name":"mode","in":"query"},{"schema":{"type":"string"},"required":false,"name":"shard","in":"query"},{"schema":{"type":"string","format":"uri"},"required":false,"name":"base_url","in":"query"}],"responses":{"200":{"description":"Sitemap shard manifest or shard entries.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SeoSitemapResponse"}}},"headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"},"X-Mapbase-Credits":{"$ref":"#/components/headers/MapbaseCredits"}}},"400":{"description":"Invalid query parameters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}},"security":[{"ApiKeyAuth":[]}],"x-mapbase-credits":0,"x-mapbase-credits-formula":"0 (not billed)"}},"/v1/providers/google/autocomplete":{"get":{"tags":["providers"],"summary":"Google Places autocomplete","parameters":[{"schema":{"type":"string","minLength":1,"example":"Rua Augusta, Lisboa"},"required":true,"name":"q","in":"query"},{"schema":{"type":"array","items":{"type":"string","minLength":2,"maxLength":2},"maxItems":5,"example":["PT","ES"]},"required":false,"name":"country","in":"query"},{"schema":{"type":["string","null"],"example":"38.710022004"},"required":false,"name":"lat","in":"query"},{"schema":{"type":["string","null"],"example":"-9.138168592"},"required":false,"name":"lng","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":20,"default":5,"example":5},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","pattern":"^[a-z]{2}$/i","example":"pt"},"required":false,"name":"language","in":"query"},{"schema":{"type":"string","minLength":1,"default":"geocode","example":"geocode"},"required":false,"name":"types","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":50000,"example":50000},"required":false,"name":"radius","in":"query"},{"schema":{"type":["boolean","null"]},"required":false,"name":"strictbounds","in":"query"},{"schema":{"type":"string","minLength":1},"required":false,"name":"sessiontoken","in":"query"},{"schema":{"type":"string","minLength":2,"maxLength":2},"required":false,"name":"region","in":"query"}],"responses":{"200":{"description":"Raw upstream Google autocomplete JSON.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GoogleAutocompleteResponse"}}},"headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"},"X-Mapbase-Credits":{"$ref":"#/components/headers/MapbaseCredits"}}},"400":{"description":"Missing provider API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"},"502":{"description":"Upstream provider error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"503":{"$ref":"#/components/responses/ServiceUnavailable"}},"security":[{"ApiKeyAuth":[],"GoogleApiKeyAuth":[]}],"x-mapbase-credits":1,"x-mapbase-credits-formula":"limit (×2 with include=polylines or format=geojson)"}},"/v1/providers/google/place":{"get":{"tags":["providers"],"summary":"Google Place details","parameters":[{"schema":{"type":"string","minLength":1,"example":"ChIJgUbEo8cfqokR5lP9_Wh_DaM"},"required":true,"name":"place_id","in":"query"},{"schema":{"type":"string","pattern":"^[a-z]{2}$/i","example":"pt"},"required":false,"name":"language","in":"query"},{"schema":{"type":"string","minLength":2,"maxLength":2},"required":false,"name":"region","in":"query"}],"responses":{"200":{"description":"Raw upstream Google geocode JSON for a place_id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GooglePlaceDetailsResponse"}}},"headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"},"X-Mapbase-Credits":{"$ref":"#/components/headers/MapbaseCredits"}}},"400":{"description":"Missing provider API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"},"502":{"description":"Upstream provider error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"503":{"$ref":"#/components/responses/ServiceUnavailable"}},"security":[{"ApiKeyAuth":[],"GoogleApiKeyAuth":[]}],"x-mapbase-credits":1,"x-mapbase-credits-formula":"1 (×2 with include=polylines or format=geojson)"}},"/v1/providers/google/geocode":{"get":{"tags":["providers"],"summary":"Google geocode","parameters":[{"schema":{"type":"string","minLength":1,"example":"Rua Augusta, Lisboa"},"required":true,"name":"address","in":"query"},{"schema":{"type":"array","items":{"type":"string","minLength":2,"maxLength":2},"maxItems":5,"example":["PT"]},"required":false,"name":"country","in":"query"},{"schema":{"type":"string","pattern":"^[a-z]{2}$/i","example":"pt"},"required":false,"name":"language","in":"query"},{"schema":{"type":"string","minLength":2,"maxLength":2},"required":false,"name":"region","in":"query"},{"schema":{"type":"string","minLength":1},"required":false,"name":"bounds","in":"query"}],"responses":{"200":{"description":"Raw upstream Google geocode JSON.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GoogleGeocodeResponse"}}},"headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"},"X-Mapbase-Credits":{"$ref":"#/components/headers/MapbaseCredits"}}},"400":{"description":"Missing provider API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"},"502":{"description":"Upstream provider error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"503":{"$ref":"#/components/responses/ServiceUnavailable"}},"security":[{"ApiKeyAuth":[],"GoogleApiKeyAuth":[]}],"x-mapbase-credits":1,"x-mapbase-credits-formula":"1 (×2 with include=polylines or format=geojson)"}},"/v1/providers/google/reverse-geocode":{"get":{"tags":["providers"],"summary":"Google reverse geocode","parameters":[{"schema":{"type":"string","example":"38.710022004"},"required":true,"name":"lat","in":"query"},{"schema":{"type":"string","example":"-9.138168592"},"required":true,"name":"lng","in":"query"},{"schema":{"type":"string","pattern":"^[a-z]{2}$/i","example":"pt"},"required":false,"name":"language","in":"query"},{"schema":{"type":"string","minLength":2,"maxLength":2},"required":false,"name":"region","in":"query"},{"schema":{"type":"string","minLength":1,"example":"street_address"},"required":false,"name":"result_type","in":"query"},{"schema":{"type":"string","enum":["ROOFTOP","RANGE_INTERPOLATED","GEOMETRIC_CENTER","APPROXIMATE"],"example":"ROOFTOP"},"required":false,"name":"location_type","in":"query"}],"responses":{"200":{"description":"Raw upstream Google reverse geocode JSON.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GoogleReverseGeocodeResponse"}}},"headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"},"X-Mapbase-Credits":{"$ref":"#/components/headers/MapbaseCredits"}}},"400":{"description":"Missing provider API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"},"502":{"description":"Upstream provider error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"503":{"$ref":"#/components/responses/ServiceUnavailable"}},"security":[{"ApiKeyAuth":[],"GoogleApiKeyAuth":[]}],"x-mapbase-credits":1,"x-mapbase-credits-formula":"1 (×2 with include=polylines or format=geojson)"}},"/v1/providers/geoapify/autocomplete":{"get":{"tags":["providers"],"summary":"Geoapify place autocomplete","parameters":[{"schema":{"type":"string","minLength":1,"example":"Lisboa"},"required":true,"name":"q","in":"query"},{"schema":{"type":"string","minLength":2,"maxLength":2,"example":"PT"},"required":false,"name":"country","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":20,"default":5,"example":8},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","enum":["country","state","city","postcode","street","amenity","locality"],"example":"city"},"required":false,"name":"type","in":"query"},{"schema":{"type":"string","pattern":"^[a-z]{2}$/i","example":"pt"},"required":false,"name":"lang","in":"query"},{"schema":{"type":"string","minLength":1},"required":false,"name":"filter","in":"query"},{"schema":{"type":"string","minLength":1},"required":false,"name":"bias","in":"query"},{"schema":{"type":"string","enum":["json","xml","geojson"],"default":"json","example":"json"},"required":false,"name":"format","in":"query"}],"responses":{"200":{"description":"Autocomplete results.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GeoapifyAutocompleteResponse"}}},"headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"},"X-Mapbase-Credits":{"$ref":"#/components/headers/MapbaseCredits"}}},"400":{"description":"Missing provider API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"},"502":{"description":"Upstream provider error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"503":{"$ref":"#/components/responses/ServiceUnavailable"}},"security":[{"ApiKeyAuth":[],"GeoapifyApiKeyAuth":[]}],"x-mapbase-credits":1,"x-mapbase-credits-formula":"limit (×2 with include=polylines or format=geojson)"}},"/v1/providers/geoapify/boundaries":{"get":{"tags":["providers"],"summary":"Geoapify boundary polygons","parameters":[{"schema":{"type":"string","minLength":1,"example":"5109cc9e5fef4522c0594d1c2f93975a4340f00101f9013a69520000000000c00208"},"required":false,"name":"place_id","in":"query"},{"schema":{"type":["string","null"]},"required":false,"name":"lat","in":"query"},{"schema":{"type":["string","null"]},"required":false,"name":"lon","in":"query"},{"schema":{"type":"string","enum":["point","geometry_1000","geometry_5000","geometry_10000"],"default":"geometry_1000","example":"geometry_1000"},"required":false,"name":"geometry","in":"query"},{"schema":{"type":"string","enum":["administrative","postal_code","political","low_emission_zone"],"example":"administrative"},"required":false,"name":"boundaries","in":"query"},{"schema":{"type":"string","pattern":"^[a-z]{2}$/i","example":"pt"},"required":false,"name":"lang","in":"query"}],"responses":{"200":{"description":"GeoJSON FeatureCollection from Geoapify.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GeoapifyBoundariesResponse"}}},"headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"},"X-Mapbase-Credits":{"$ref":"#/components/headers/MapbaseCredits"}}},"400":{"description":"Missing provider API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"},"502":{"description":"Upstream provider error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"503":{"$ref":"#/components/responses/ServiceUnavailable"}},"security":[{"ApiKeyAuth":[],"GeoapifyApiKeyAuth":[]}],"x-mapbase-credits":1,"x-mapbase-credits-formula":"1 (×2 with include=polylines or format=geojson)"}}},"webhooks":{}}