{"openapi":"3.1.0","info":{"title":"Geocode AI API","version":"1.0.0","summary":"Boundaries and areas API for every place on Earth","description":"Look up any administrative boundary in the world (country, state, county, city, district, postcode) by name or point and get its polygon in one call, or describe an area in plain language and get a validated polygon back. REST, MCP, CLI and plugins for Claude and Codex.\n\nEvery op has a resource route and an RPC route (`POST /v1/ops/{name}`); both take the same input. Public ops work without a key (20 calls a minute per IP). Errors are RFC 9457 problems with `code` and `request_id`. `x-units` is what one call costs.","contact":{"email":"jonathan@geocodeai.dev"}},"servers":[{"url":"https://geo-coder-service.vercel.app"}],"externalDocs":{"description":"Docs for agents","url":"https://geo-coder-service.vercel.app/llms-full.txt"},"tags":[{"name":"meta"},{"name":"auth"},{"name":"boundaries"},{"name":"areas"},{"name":"account"},{"name":"usage"},{"name":"keys"},{"name":"feedback"}],"paths":{"/v1":{"get":{"operationId":"list_ops","summary":"List every op","description":"The machine-readable catalog: every op with its input JSON Schema, units, routes and example. The CLI and SDKs build themselves from it.","tags":["meta"],"security":[{}],"responses":{"200":{"description":"The catalog","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/v1/auth/device":{"post":{"operationId":"start_device_login","summary":"Start a device sign-in","description":"What `geocode login` calls: returns a secret device_code and a user_code the person approves at verification_uri while signed in. Poll /v1/auth/device/token every `interval` seconds.","tags":["auth"],"security":[{}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"client_name":{"type":"string","maxLength":80}}}}}},"responses":{"200":{"description":"The code pair","content":{"application/json":{"schema":{"type":"object","required":["device_code","user_code","verification_uri","verification_uri_complete","expires_in","interval"],"properties":{"device_code":{"type":"string"},"user_code":{"type":"string","examples":["ABCD-EFGH"]},"verification_uri":{"type":"string","format":"uri"},"verification_uri_complete":{"type":"string","format":"uri"},"expires_in":{"type":"integer"},"interval":{"type":"integer"}}}}}},"500":{"description":"Our failure; quote `request_id`.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/auth/device/token":{"post":{"operationId":"poll_device_login","summary":"Poll a device sign-in","description":"428 `authorization_pending` until the person approves; then the new API key, exactly once. 400 `access_denied`, `expired_token` or `invalid_grant` end the flow.","tags":["auth"],"security":[{}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["device_code"],"properties":{"device_code":{"type":"string"}}}}}},"responses":{"200":{"description":"Approved: the API key","content":{"application/json":{"schema":{"type":"object","required":["api_key"],"properties":{"api_key":{"type":"string"},"email":{"type":["string","null"]}}}}}},"400":{"description":"Denied, expired or already used.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"428":{"description":"Not approved yet; poll again after `interval` seconds.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Our failure; quote `request_id`.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/boundaries/search":{"get":{"operationId":"search_boundaries","summary":"Search boundaries","description":"Finds administrative boundaries (countries, states, counties, cities, districts) and postcode areas by name, in any language. Filter by country, kind or admin_level; bias toward a point with near. Free and public. Returns candidates with id, kind, admin_level, country, parents, bbox, centroid and population, but no polygon: pass the id to get_boundary for that.","tags":["boundaries"],"security":[{},{"bearerAuth":[]},{"apiKeyHeader":[]},{"oauth2":[]}],"x-units":0,"x-units-label":"free","x-public":true,"x-mcp-tool":"search_boundaries","x-cli":"geocode search-boundaries","responses":{"200":{"description":"Search boundaries","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"The input failed validation (`code: invalid_input`, with `issues`).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"No credential, or an invalid or revoked one. The `WWW-Authenticate` header names the OAuth resource metadata.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"402":{"description":"This month's units on the plan are used up (`code: quota_exceeded`).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limited; retry after `retry_after` seconds.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Our failure; quote `request_id`.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"parameters":[{"name":"q","in":"query","required":true,"description":"A place name, e.g. \"Berlin\", \"Alameda County\", \"75011\".","schema":{"type":"string","minLength":1,"maxLength":200,"description":"A place name, e.g. \"Berlin\", \"Alameda County\", \"75011\"."},"example":"Alameda County"},{"name":"country","in":"query","required":false,"description":"Limit to countries: ISO 3166-1 alpha-2, comma-separated (e.g. US or de,at,ch).","schema":{"description":"Limit to countries: ISO 3166-1 alpha-2, comma-separated (e.g. US or de,at,ch).","type":"string","pattern":"^[A-Za-z]{2}(,[A-Za-z]{2})*$"},"example":"US"},{"name":"kind","in":"query","required":false,"description":"Only this kind (normalized across countries): country, state, region, province, county, district, municipality, city, borough, ward, neighbourhood, postal_code.","schema":{"description":"Only this kind (normalized across countries): country, state, region, province, county, district, municipality, city, borough, ward, neighbourhood, postal_code.","type":"string","enum":["country","state","region","province","county","district","municipality","city","borough","ward","neighbourhood","postal_code"]}},{"name":"admin_level","in":"query","required":false,"description":"Only this OSM admin_level (2 = country; meaning varies by country below that).","schema":{"description":"Only this OSM admin_level (2 = country; meaning varies by country below that).","type":"integer","minimum":1,"maximum":12}},{"name":"near","in":"query","required":false,"description":"lat,lon to prefer results near, e.g. 37.77,-122.42.","schema":{"description":"lat,lon to prefer results near, e.g. 37.77,-122.42.","type":"string","pattern":"^\\s*-?\\d+(\\.\\d+)?\\s*,\\s*-?\\d+(\\.\\d+)?\\s*$"}},{"name":"limit","in":"query","required":false,"description":"At most this many results (1–40, default 10).","schema":{"default":10,"description":"At most this many results (1–40, default 10).","type":"integer","minimum":1,"maximum":40}}]}},"/v1/ops/search_boundaries":{"post":{"operationId":"search_boundaries_rpc","summary":"Search boundaries","description":"RPC form of `search_boundaries` (same input as JSON). Finds administrative boundaries (countries, states, counties, cities, districts) and postcode areas by name, in any language. Filter by country, kind or admin_level; bias toward a point with near. Free and public. Returns candidates with id, kind, admin_level, country, parents, bbox, centroid and population, but no polygon: pass the id to get_boundary for that.","tags":["boundaries"],"security":[{},{"bearerAuth":[]},{"apiKeyHeader":[]},{"oauth2":[]}],"x-units":0,"x-units-label":"free","x-public":true,"x-mcp-tool":"search_boundaries","x-cli":"geocode search-boundaries","responses":{"200":{"description":"Search boundaries","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"The input failed validation (`code: invalid_input`, with `issues`).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"No credential, or an invalid or revoked one. The `WWW-Authenticate` header names the OAuth resource metadata.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"402":{"description":"This month's units on the plan are used up (`code: quota_exceeded`).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limited; retry after `retry_after` seconds.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Our failure; quote `request_id`.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"q":{"type":"string","minLength":1,"maxLength":200,"description":"A place name, e.g. \"Berlin\", \"Alameda County\", \"75011\"."},"country":{"description":"Limit to countries: ISO 3166-1 alpha-2, comma-separated (e.g. US or de,at,ch).","type":"string","pattern":"^[A-Za-z]{2}(,[A-Za-z]{2})*$"},"kind":{"description":"Only this kind (normalized across countries): country, state, region, province, county, district, municipality, city, borough, ward, neighbourhood, postal_code.","type":"string","enum":["country","state","region","province","county","district","municipality","city","borough","ward","neighbourhood","postal_code"]},"admin_level":{"description":"Only this OSM admin_level (2 = country; meaning varies by country below that).","type":"integer","minimum":1,"maximum":12},"near":{"description":"lat,lon to prefer results near, e.g. 37.77,-122.42.","type":"string","pattern":"^\\s*-?\\d+(\\.\\d+)?\\s*,\\s*-?\\d+(\\.\\d+)?\\s*$"},"limit":{"default":10,"description":"At most this many results (1–40, default 10).","type":"integer","minimum":1,"maximum":40}},"required":["q"]},"example":{"q":"Alameda County","country":"US"}}}}}},"/v1/boundaries/{id}":{"get":{"operationId":"get_boundary","summary":"Get boundary polygon","description":"Returns one boundary as a GeoJSON Feature: its polygon at a chosen detail plus properties (name, kind, admin_level, parents, bbox, area_km2, population, wikidata). Fetched from OpenStreetMap the first time anyone asks, then served from cache. Costs 1 unit; detail=low is also public without a key (for map previews). include=parents adds the full hierarchy, include=children the direct subdivisions. If the polygon is too big for one response, geometry is null and download_url points to the file.","tags":["boundaries"],"security":[{},{"bearerAuth":[]},{"apiKeyHeader":[]},{"oauth2":[]}],"x-units":1,"x-units-label":"1 unit","x-public":true,"x-mcp-tool":"get_boundary","x-cli":"geocode get-boundary","responses":{"200":{"description":"Get boundary polygon","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"The input failed validation (`code: invalid_input`, with `issues`).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"No credential, or an invalid or revoked one. The `WWW-Authenticate` header names the OAuth resource metadata.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"402":{"description":"This month's units on the plan are used up (`code: quota_exceeded`).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limited; retry after `retry_after` seconds.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Our failure; quote `request_id`.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":200,"description":"Boundary id: r<OSM relation id> (e.g. r62422 for Berlin) or w<way id>. Also accepts R62422, relation/62422, -62422, an openstreetmap.org URL, wikidata:Q64 or iso:US-CA."},"description":"Boundary id: r<OSM relation id> (e.g. r62422 for Berlin) or w<way id>. Also accepts R62422, relation/62422, -62422, an openstreetmap.org URL, wikidata:Q64 or iso:US-CA.","example":"r62422"},{"name":"detail","in":"query","required":false,"description":"Simplification relative to the boundary's size: low (~1,000 points across; the default without a key), medium (the default with a key, ~5,000), high (~25,000), full (unsimplified OSM).","schema":{"description":"Simplification relative to the boundary's size: low (~1,000 points across; the default without a key), medium (the default with a key, ~5,000), high (~25,000), full (unsimplified OSM).","type":"string","enum":["low","medium","high","full"]},"example":"low"},{"name":"precision","in":"query","required":false,"description":"Coordinate decimals (3–7). Defaults to what the detail level needs.","schema":{"description":"Coordinate decimals (3–7). Defaults to what the detail level needs.","type":"integer","minimum":3,"maximum":7}},{"name":"include","in":"query","required":true,"description":"Comma-separated extras: parents, children.","content":{"application/json":{"schema":{"description":"Comma-separated extras: parents, children.","type":"array","items":{"type":"string","enum":["parents","children"]}}}},"example":["parents"]}]}},"/v1/ops/get_boundary":{"post":{"operationId":"get_boundary_rpc","summary":"Get boundary polygon","description":"RPC form of `get_boundary` (same input as JSON). Returns one boundary as a GeoJSON Feature: its polygon at a chosen detail plus properties (name, kind, admin_level, parents, bbox, area_km2, population, wikidata). Fetched from OpenStreetMap the first time anyone asks, then served from cache. Costs 1 unit; detail=low is also public without a key (for map previews). include=parents adds the full hierarchy, include=children the direct subdivisions. If the polygon is too big for one response, geometry is null and download_url points to the file.","tags":["boundaries"],"security":[{},{"bearerAuth":[]},{"apiKeyHeader":[]},{"oauth2":[]}],"x-units":1,"x-units-label":"1 unit","x-public":true,"x-mcp-tool":"get_boundary","x-cli":"geocode get-boundary","responses":{"200":{"description":"Get boundary polygon","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"The input failed validation (`code: invalid_input`, with `issues`).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"No credential, or an invalid or revoked one. The `WWW-Authenticate` header names the OAuth resource metadata.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"402":{"description":"This month's units on the plan are used up (`code: quota_exceeded`).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limited; retry after `retry_after` seconds.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Our failure; quote `request_id`.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":200,"description":"Boundary id: r<OSM relation id> (e.g. r62422 for Berlin) or w<way id>. Also accepts R62422, relation/62422, -62422, an openstreetmap.org URL, wikidata:Q64 or iso:US-CA."},"detail":{"description":"Simplification relative to the boundary's size: low (~1,000 points across; the default without a key), medium (the default with a key, ~5,000), high (~25,000), full (unsimplified OSM).","type":"string","enum":["low","medium","high","full"]},"precision":{"description":"Coordinate decimals (3–7). Defaults to what the detail level needs.","type":"integer","minimum":3,"maximum":7},"include":{"description":"Comma-separated extras: parents, children.","type":"array","items":{"type":"string","enum":["parents","children"]}}},"required":["id","include"]},"example":{"id":"r62422","detail":"low","include":["parents"]}}}}}},"/v1/boundaries/{id}.{format}":{"get":{"operationId":"export_boundary","summary":"Export boundary file","description":"Builds a boundary's polygon as a file (geojson, kml, wkt, svg or gml) at a detail level and returns a permanent public URL on our CDN; the REST route redirects straight to it. Use it for large polygons, GIS tools and bulk downloads. Costs 1 unit; each file is built once and then shared.","tags":["boundaries"],"security":[{"bearerAuth":[]},{"apiKeyHeader":[]},{"oauth2":[]}],"x-units":1,"x-units-label":"1 unit","x-public":false,"x-mcp-tool":"export_boundary","x-cli":"geocode export-boundary","responses":{"200":{"description":"Export boundary file","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"The input failed validation (`code: invalid_input`, with `issues`).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"No credential, or an invalid or revoked one. The `WWW-Authenticate` header names the OAuth resource metadata.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"402":{"description":"This month's units on the plan are used up (`code: quota_exceeded`).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limited; retry after `retry_after` seconds.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Our failure; quote `request_id`.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":200,"description":"Boundary id: r<OSM relation id> (e.g. r62422 for Berlin) or w<way id>. Also accepts R62422, relation/62422, -62422, an openstreetmap.org URL, wikidata:Q64 or iso:US-CA."},"description":"Boundary id: r<OSM relation id> (e.g. r62422 for Berlin) or w<way id>. Also accepts R62422, relation/62422, -62422, an openstreetmap.org URL, wikidata:Q64 or iso:US-CA.","example":"r62422"},{"name":"format","in":"path","required":true,"schema":{"default":"geojson","description":"geojson (a Feature), kml, wkt, svg or gml.","type":"string","enum":["geojson","kml","wkt","svg","gml"]},"description":"geojson (a Feature), kml, wkt, svg or gml.","example":"kml"},{"name":"detail","in":"query","required":false,"description":"Simplification relative to the boundary's size: low (~1,000 points across, maps and previews), medium (default, ~5,000), high (~25,000), full (unsimplified OSM).","schema":{"default":"medium","description":"Simplification relative to the boundary's size: low (~1,000 points across, maps and previews), medium (default, ~5,000), high (~25,000), full (unsimplified OSM).","type":"string","enum":["low","medium","high","full"]},"example":"medium"}]}},"/v1/ops/export_boundary":{"post":{"operationId":"export_boundary_rpc","summary":"Export boundary file","description":"RPC form of `export_boundary` (same input as JSON). Builds a boundary's polygon as a file (geojson, kml, wkt, svg or gml) at a detail level and returns a permanent public URL on our CDN; the REST route redirects straight to it. Use it for large polygons, GIS tools and bulk downloads. Costs 1 unit; each file is built once and then shared.","tags":["boundaries"],"security":[{"bearerAuth":[]},{"apiKeyHeader":[]},{"oauth2":[]}],"x-units":1,"x-units-label":"1 unit","x-public":false,"x-mcp-tool":"export_boundary","x-cli":"geocode export-boundary","responses":{"200":{"description":"Export boundary file","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"The input failed validation (`code: invalid_input`, with `issues`).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"No credential, or an invalid or revoked one. The `WWW-Authenticate` header names the OAuth resource metadata.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"402":{"description":"This month's units on the plan are used up (`code: quota_exceeded`).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limited; retry after `retry_after` seconds.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Our failure; quote `request_id`.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":200,"description":"Boundary id: r<OSM relation id> (e.g. r62422 for Berlin) or w<way id>. Also accepts R62422, relation/62422, -62422, an openstreetmap.org URL, wikidata:Q64 or iso:US-CA."},"format":{"default":"geojson","description":"geojson (a Feature), kml, wkt, svg or gml.","type":"string","enum":["geojson","kml","wkt","svg","gml"]},"detail":{"default":"medium","description":"Simplification relative to the boundary's size: low (~1,000 points across, maps and previews), medium (default, ~5,000), high (~25,000), full (unsimplified OSM).","type":"string","enum":["low","medium","high","full"]}},"required":["id"]},"example":{"id":"r62422","format":"kml","detail":"medium"}}}}}},"/v1/boundaries/reverse":{"get":{"operationId":"reverse_boundaries","summary":"Boundaries at a point","description":"Every administrative boundary containing a point, country first down to the smallest district, plus postcode areas. Use it to tag an address, a store or a delivery with its country, state, county and city in one call. Costs 1 unit. Returns ids you can pass to get_boundary.","tags":["boundaries"],"security":[{"bearerAuth":[]},{"apiKeyHeader":[]},{"oauth2":[]}],"x-units":1,"x-units-label":"1 unit","x-public":false,"x-mcp-tool":"reverse_boundaries","x-cli":"geocode reverse-boundaries","responses":{"200":{"description":"Boundaries at a point","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"The input failed validation (`code: invalid_input`, with `issues`).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"No credential, or an invalid or revoked one. The `WWW-Authenticate` header names the OAuth resource metadata.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"402":{"description":"This month's units on the plan are used up (`code: quota_exceeded`).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limited; retry after `retry_after` seconds.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Our failure; quote `request_id`.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"parameters":[{"name":"lat","in":"query","required":true,"description":"Latitude, -90 to 90.","schema":{"type":"number","minimum":-90,"maximum":90,"description":"Latitude, -90 to 90."},"example":52.52},{"name":"lon","in":"query","required":true,"description":"Longitude, -180 to 180.","schema":{"type":"number","minimum":-180,"maximum":180,"description":"Longitude, -180 to 180."},"example":13.405}]}},"/v1/ops/reverse_boundaries":{"post":{"operationId":"reverse_boundaries_rpc","summary":"Boundaries at a point","description":"RPC form of `reverse_boundaries` (same input as JSON). Every administrative boundary containing a point, country first down to the smallest district, plus postcode areas. Use it to tag an address, a store or a delivery with its country, state, county and city in one call. Costs 1 unit. Returns ids you can pass to get_boundary.","tags":["boundaries"],"security":[{"bearerAuth":[]},{"apiKeyHeader":[]},{"oauth2":[]}],"x-units":1,"x-units-label":"1 unit","x-public":false,"x-mcp-tool":"reverse_boundaries","x-cli":"geocode reverse-boundaries","responses":{"200":{"description":"Boundaries at a point","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"The input failed validation (`code: invalid_input`, with `issues`).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"No credential, or an invalid or revoked one. The `WWW-Authenticate` header names the OAuth resource metadata.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"402":{"description":"This month's units on the plan are used up (`code: quota_exceeded`).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limited; retry after `retry_after` seconds.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Our failure; quote `request_id`.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"lat":{"type":"number","minimum":-90,"maximum":90,"description":"Latitude, -90 to 90."},"lon":{"type":"number","minimum":-180,"maximum":180,"description":"Longitude, -180 to 180."}},"required":["lat","lon"]},"example":{"lat":52.52,"lon":13.405}}}}}},"/v1/boundaries/{id}/children":{"get":{"operationId":"list_children","summary":"List subdivisions","description":"The direct subdivisions of a boundary: a country's states, a state's counties, a city's districts. Without admin_level it picks the next level that exists. Free and public. Use it to build drill-down pickers or to cover a region with its parts.","tags":["boundaries"],"security":[{},{"bearerAuth":[]},{"apiKeyHeader":[]},{"oauth2":[]}],"x-units":0,"x-units-label":"free","x-public":true,"x-mcp-tool":"list_children","x-cli":"geocode list-children","responses":{"200":{"description":"List subdivisions","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"The input failed validation (`code: invalid_input`, with `issues`).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"No credential, or an invalid or revoked one. The `WWW-Authenticate` header names the OAuth resource metadata.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"402":{"description":"This month's units on the plan are used up (`code: quota_exceeded`).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limited; retry after `retry_after` seconds.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Our failure; quote `request_id`.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":200,"description":"Boundary id: r<OSM relation id> (e.g. r62422 for Berlin) or w<way id>. Also accepts R62422, relation/62422, -62422, an openstreetmap.org URL, wikidata:Q64 or iso:US-CA."},"description":"Boundary id: r<OSM relation id> (e.g. r62422 for Berlin) or w<way id>. Also accepts R62422, relation/62422, -62422, an openstreetmap.org URL, wikidata:Q64 or iso:US-CA.","example":"r165475"},{"name":"admin_level","in":"query","required":false,"description":"Subdivision admin_level; default: the next level below the parent that exists.","schema":{"description":"Subdivision admin_level; default: the next level below the parent that exists.","type":"integer","minimum":3,"maximum":12}}]}},"/v1/ops/list_children":{"post":{"operationId":"list_children_rpc","summary":"List subdivisions","description":"RPC form of `list_children` (same input as JSON). The direct subdivisions of a boundary: a country's states, a state's counties, a city's districts. Without admin_level it picks the next level that exists. Free and public. Use it to build drill-down pickers or to cover a region with its parts.","tags":["boundaries"],"security":[{},{"bearerAuth":[]},{"apiKeyHeader":[]},{"oauth2":[]}],"x-units":0,"x-units-label":"free","x-public":true,"x-mcp-tool":"list_children","x-cli":"geocode list-children","responses":{"200":{"description":"List subdivisions","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"The input failed validation (`code: invalid_input`, with `issues`).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"No credential, or an invalid or revoked one. The `WWW-Authenticate` header names the OAuth resource metadata.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"402":{"description":"This month's units on the plan are used up (`code: quota_exceeded`).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limited; retry after `retry_after` seconds.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Our failure; quote `request_id`.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":200,"description":"Boundary id: r<OSM relation id> (e.g. r62422 for Berlin) or w<way id>. Also accepts R62422, relation/62422, -62422, an openstreetmap.org URL, wikidata:Q64 or iso:US-CA."},"admin_level":{"description":"Subdivision admin_level; default: the next level below the parent that exists.","type":"integer","minimum":3,"maximum":12}},"required":["id"]},"example":{"id":"r165475"}}}}}},"/v1/boundaries/{id}/contains":{"post":{"operationId":"contains_points","summary":"Points in boundary","description":"Tests up to 10,000 points ([lon, lat] pairs) against one boundary and returns a boolean per point plus the inside count. Use it for geofencing, service-area checks and filtering customer lists. Costs 1 unit per 1,000 points.","tags":["boundaries"],"security":[{"bearerAuth":[]},{"apiKeyHeader":[]},{"oauth2":[]}],"x-units":"varies","x-units-label":"units vary with the input","x-public":false,"x-mcp-tool":"contains_points","x-cli":"geocode contains-points","responses":{"200":{"description":"Points in boundary","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"The input failed validation (`code: invalid_input`, with `issues`).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"No credential, or an invalid or revoked one. The `WWW-Authenticate` header names the OAuth resource metadata.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"402":{"description":"This month's units on the plan are used up (`code: quota_exceeded`).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limited; retry after `retry_after` seconds.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Our failure; quote `request_id`.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"points":{"minItems":1,"maxItems":10000,"type":"array","items":{"type":"array","prefixItems":[{"type":"number","minimum":-180,"maximum":180},{"type":"number","minimum":-90,"maximum":90}],"items":false,"minItems":2,"maxItems":2},"description":"Points as [lon, lat] (GeoJSON order)."}},"required":["points"]},"example":{"points":[[13.405,52.52],[2.35,48.86]]}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":200,"description":"Boundary id: r<OSM relation id> (e.g. r62422 for Berlin) or w<way id>. Also accepts R62422, relation/62422, -62422, an openstreetmap.org URL, wikidata:Q64 or iso:US-CA."},"description":"Boundary id: r<OSM relation id> (e.g. r62422 for Berlin) or w<way id>. Also accepts R62422, relation/62422, -62422, an openstreetmap.org URL, wikidata:Q64 or iso:US-CA.","example":"r62422"}]}},"/v1/ops/contains_points":{"post":{"operationId":"contains_points_rpc","summary":"Points in boundary","description":"RPC form of `contains_points` (same input as JSON). Tests up to 10,000 points ([lon, lat] pairs) against one boundary and returns a boolean per point plus the inside count. Use it for geofencing, service-area checks and filtering customer lists. Costs 1 unit per 1,000 points.","tags":["boundaries"],"security":[{"bearerAuth":[]},{"apiKeyHeader":[]},{"oauth2":[]}],"x-units":"varies","x-units-label":"units vary with the input","x-public":false,"x-mcp-tool":"contains_points","x-cli":"geocode contains-points","responses":{"200":{"description":"Points in boundary","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"The input failed validation (`code: invalid_input`, with `issues`).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"No credential, or an invalid or revoked one. The `WWW-Authenticate` header names the OAuth resource metadata.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"402":{"description":"This month's units on the plan are used up (`code: quota_exceeded`).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limited; retry after `retry_after` seconds.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Our failure; quote `request_id`.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":200,"description":"Boundary id: r<OSM relation id> (e.g. r62422 for Berlin) or w<way id>. Also accepts R62422, relation/62422, -62422, an openstreetmap.org URL, wikidata:Q64 or iso:US-CA."},"points":{"minItems":1,"maxItems":10000,"type":"array","items":{"type":"array","prefixItems":[{"type":"number","minimum":-180,"maximum":180},{"type":"number","minimum":-90,"maximum":90}],"items":false,"minItems":2,"maxItems":2},"description":"Points as [lon, lat] (GeoJSON order)."}},"required":["id","points"]},"example":{"id":"r62422","points":[[13.405,52.52],[2.35,48.86]]}}}}}},"/v1/boundaries/union":{"post":{"operationId":"union_boundaries","summary":"Merge boundaries","description":"Merges boundaries into one polygon: the union of include minus the union of exclude (e.g. three counties minus one city). Use it for sales territories, delivery zones and service areas. Up to 50 boundaries; costs 1 unit per boundary. Returns a GeoJSON Feature with area_km2. To describe an area in words instead, use create_area.","tags":["boundaries"],"security":[{"bearerAuth":[]},{"apiKeyHeader":[]},{"oauth2":[]}],"x-units":"varies","x-units-label":"units vary with the input","x-public":false,"x-mcp-tool":"union_boundaries","x-cli":"geocode union-boundaries","responses":{"200":{"description":"Merge boundaries","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"The input failed validation (`code: invalid_input`, with `issues`).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"No credential, or an invalid or revoked one. The `WWW-Authenticate` header names the OAuth resource metadata.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"402":{"description":"This month's units on the plan are used up (`code: quota_exceeded`).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limited; retry after `retry_after` seconds.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Our failure; quote `request_id`.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"include":{"minItems":1,"maxItems":50,"type":"array","items":{"type":"string","minLength":1,"maxLength":200,"description":"Boundary id: r<OSM relation id> (e.g. r62422 for Berlin) or w<way id>. Also accepts R62422, relation/62422, -62422, an openstreetmap.org URL, wikidata:Q64 or iso:US-CA."},"description":"Boundary ids to merge."},"exclude":{"default":[],"description":"Boundary ids to cut out.","maxItems":50,"type":"array","items":{"type":"string","minLength":1,"maxLength":200,"description":"Boundary id: r<OSM relation id> (e.g. r62422 for Berlin) or w<way id>. Also accepts R62422, relation/62422, -62422, an openstreetmap.org URL, wikidata:Q64 or iso:US-CA."}},"detail":{"default":"medium","description":"Simplification relative to the boundary's size: low (~1,000 points across, maps and previews), medium (default, ~5,000), high (~25,000), full (unsimplified OSM).","type":"string","enum":["low","medium","high","full"]}},"required":["include"]},"example":{"include":["r396499","r396479"],"exclude":["r2833530"],"detail":"low"}}}}}},"/v1/ops/union_boundaries":{"post":{"operationId":"union_boundaries_rpc","summary":"Merge boundaries","description":"RPC form of `union_boundaries` (same input as JSON). Merges boundaries into one polygon: the union of include minus the union of exclude (e.g. three counties minus one city). Use it for sales territories, delivery zones and service areas. Up to 50 boundaries; costs 1 unit per boundary. Returns a GeoJSON Feature with area_km2. To describe an area in words instead, use create_area.","tags":["boundaries"],"security":[{"bearerAuth":[]},{"apiKeyHeader":[]},{"oauth2":[]}],"x-units":"varies","x-units-label":"units vary with the input","x-public":false,"x-mcp-tool":"union_boundaries","x-cli":"geocode union-boundaries","responses":{"200":{"description":"Merge boundaries","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"The input failed validation (`code: invalid_input`, with `issues`).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"No credential, or an invalid or revoked one. The `WWW-Authenticate` header names the OAuth resource metadata.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"402":{"description":"This month's units on the plan are used up (`code: quota_exceeded`).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limited; retry after `retry_after` seconds.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Our failure; quote `request_id`.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"include":{"minItems":1,"maxItems":50,"type":"array","items":{"type":"string","minLength":1,"maxLength":200,"description":"Boundary id: r<OSM relation id> (e.g. r62422 for Berlin) or w<way id>. Also accepts R62422, relation/62422, -62422, an openstreetmap.org URL, wikidata:Q64 or iso:US-CA."},"description":"Boundary ids to merge."},"exclude":{"default":[],"description":"Boundary ids to cut out.","maxItems":50,"type":"array","items":{"type":"string","minLength":1,"maxLength":200,"description":"Boundary id: r<OSM relation id> (e.g. r62422 for Berlin) or w<way id>. Also accepts R62422, relation/62422, -62422, an openstreetmap.org URL, wikidata:Q64 or iso:US-CA."}},"detail":{"default":"medium","description":"Simplification relative to the boundary's size: low (~1,000 points across, maps and previews), medium (default, ~5,000), high (~25,000), full (unsimplified OSM).","type":"string","enum":["low","medium","high","full"]}},"required":["include"]},"example":{"include":["r396499","r396479"],"exclude":["r2833530"],"detail":"low"}}}}}},"/v1/areas":{"post":{"operationId":"create_area","summary":"Create area from a description","description":"Turns a plain-language description of an area (\"Alameda and Contra Costa counties excluding San Jose, plus SFO\") or wording from a contract or policy into one validated land-only polygon. An AI agent plans includes/excludes from real administrative boundaries; you get GeoJSON plus each part's source, or a 422 explaining what could not be mapped. Takes 30 s to a few minutes. For a single named place use search_boundaries + get_boundary instead: it is instant and costs 1 unit.","tags":["areas"],"security":[{"bearerAuth":[]},{"apiKeyHeader":[]},{"oauth2":[]}],"x-units":50,"x-units-label":"50 units","x-public":false,"x-mcp-tool":"create_area","x-cli":"geocode create-area","responses":{"200":{"description":"Create area from a description","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"The input failed validation (`code: invalid_input`, with `issues`).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"No credential, or an invalid or revoked one. The `WWW-Authenticate` header names the OAuth resource metadata.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"402":{"description":"This month's units on the plan are used up (`code: quota_exceeded`).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limited; retry after `retry_after` seconds.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Our failure; quote `request_id`.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"text":{"type":"string","minLength":1,"maxLength":3000,"description":"The description of the area."},"country":{"description":"ISO 3166-1 alpha-2 country code, if known.","type":"string","minLength":2,"maxLength":2},"source":{"description":"Who wrote the description (agency, company). Optional context.","type":"string","maxLength":200},"seed":{"description":"A point that must be inside the area.","type":"object","properties":{"lat":{"type":"number","minimum":-90,"maximum":90},"lon":{"type":"number","minimum":-180,"maximum":180}},"required":["lat","lon"]}},"required":["text"]},"example":{"text":"Alameda and Contra Costa counties, excluding the City of Oakland","country":"US"}}}}}},"/v1/ops/create_area":{"post":{"operationId":"create_area_rpc","summary":"Create area from a description","description":"RPC form of `create_area` (same input as JSON). Turns a plain-language description of an area (\"Alameda and Contra Costa counties excluding San Jose, plus SFO\") or wording from a contract or policy into one validated land-only polygon. An AI agent plans includes/excludes from real administrative boundaries; you get GeoJSON plus each part's source, or a 422 explaining what could not be mapped. Takes 30 s to a few minutes. For a single named place use search_boundaries + get_boundary instead: it is instant and costs 1 unit.","tags":["areas"],"security":[{"bearerAuth":[]},{"apiKeyHeader":[]},{"oauth2":[]}],"x-units":50,"x-units-label":"50 units","x-public":false,"x-mcp-tool":"create_area","x-cli":"geocode create-area","responses":{"200":{"description":"Create area from a description","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"The input failed validation (`code: invalid_input`, with `issues`).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"No credential, or an invalid or revoked one. The `WWW-Authenticate` header names the OAuth resource metadata.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"402":{"description":"This month's units on the plan are used up (`code: quota_exceeded`).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limited; retry after `retry_after` seconds.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Our failure; quote `request_id`.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"text":{"type":"string","minLength":1,"maxLength":3000,"description":"The description of the area."},"country":{"description":"ISO 3166-1 alpha-2 country code, if known.","type":"string","minLength":2,"maxLength":2},"source":{"description":"Who wrote the description (agency, company). Optional context.","type":"string","maxLength":200},"seed":{"description":"A point that must be inside the area.","type":"object","properties":{"lat":{"type":"number","minimum":-90,"maximum":90},"lon":{"type":"number","minimum":-180,"maximum":180}},"required":["lat","lon"]}},"required":["text"]},"example":{"text":"Alameda and Contra Costa counties, excluding the City of Oakland","country":"US"}}}}}},"/v1/account":{"get":{"operationId":"get_account","summary":"Get account","description":"The signed-in account: email, plan, this month's usage against the plan's limit, and rate limit. Call it to check remaining quota before a large batch.","tags":["account"],"security":[{"bearerAuth":[]},{"apiKeyHeader":[]},{"oauth2":[]}],"x-units":0,"x-units-label":"free","x-public":false,"x-mcp-tool":"get_account","x-cli":"geocode get-account","responses":{"200":{"description":"Get account","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"The input failed validation (`code: invalid_input`, with `issues`).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"No credential, or an invalid or revoked one. The `WWW-Authenticate` header names the OAuth resource metadata.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"402":{"description":"This month's units on the plan are used up (`code: quota_exceeded`).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limited; retry after `retry_after` seconds.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Our failure; quote `request_id`.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"post":{"operationId":"update_profile","summary":"Update profile","description":"Sets the account's name, company and use case (what you are building). Send only the fields to change; an empty string clears one. Free. Returns the updated profile.","tags":["account"],"security":[{"bearerAuth":[]},{"apiKeyHeader":[]},{"oauth2":[]}],"x-units":0,"x-units-label":"free","x-public":false,"x-mcp-tool":"update_profile","x-cli":"geocode update-profile","responses":{"200":{"description":"Update profile","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"The input failed validation (`code: invalid_input`, with `issues`).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"No credential, or an invalid or revoked one. The `WWW-Authenticate` header names the OAuth resource metadata.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"402":{"description":"This month's units on the plan are used up (`code: quota_exceeded`).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limited; retry after `retry_after` seconds.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Our failure; quote `request_id`.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"description":"Your name, used in emails (\"Hey {first name},\").","type":"string","maxLength":120},"company":{"description":"Company or project.","type":"string","maxLength":120},"use_case":{"description":"What you are building with boundaries and areas.","type":"string","maxLength":1000}},"required":[]},"example":{"name":"Ada Lovelace","company":"Analytical Engines","use_case":"Delivery zones from postcodes"}}}}}},"/v1/ops/get_account":{"post":{"operationId":"get_account_rpc","summary":"Get account","description":"RPC form of `get_account` (same input as JSON). The signed-in account: email, plan, this month's usage against the plan's limit, and rate limit. Call it to check remaining quota before a large batch.","tags":["account"],"security":[{"bearerAuth":[]},{"apiKeyHeader":[]},{"oauth2":[]}],"x-units":0,"x-units-label":"free","x-public":false,"x-mcp-tool":"get_account","x-cli":"geocode get-account","responses":{"200":{"description":"Get account","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"The input failed validation (`code: invalid_input`, with `issues`).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"No credential, or an invalid or revoked one. The `WWW-Authenticate` header names the OAuth resource metadata.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"402":{"description":"This month's units on the plan are used up (`code: quota_exceeded`).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limited; retry after `retry_after` seconds.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Our failure; quote `request_id`.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{},"required":[]}}}}}},"/v1/ops/update_profile":{"post":{"operationId":"update_profile_rpc","summary":"Update profile","description":"RPC form of `update_profile` (same input as JSON). Sets the account's name, company and use case (what you are building). Send only the fields to change; an empty string clears one. Free. Returns the updated profile.","tags":["account"],"security":[{"bearerAuth":[]},{"apiKeyHeader":[]},{"oauth2":[]}],"x-units":0,"x-units-label":"free","x-public":false,"x-mcp-tool":"update_profile","x-cli":"geocode update-profile","responses":{"200":{"description":"Update profile","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"The input failed validation (`code: invalid_input`, with `issues`).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"No credential, or an invalid or revoked one. The `WWW-Authenticate` header names the OAuth resource metadata.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"402":{"description":"This month's units on the plan are used up (`code: quota_exceeded`).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limited; retry after `retry_after` seconds.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Our failure; quote `request_id`.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"description":"Your name, used in emails (\"Hey {first name},\").","type":"string","maxLength":120},"company":{"description":"Company or project.","type":"string","maxLength":120},"use_case":{"description":"What you are building with boundaries and areas.","type":"string","maxLength":1000}},"required":[]},"example":{"name":"Ada Lovelace","company":"Analytical Engines","use_case":"Delivery zones from postcodes"}}}}}},"/v1/usage":{"get":{"operationId":"get_usage","summary":"Get usage","description":"Daily usage for the last N days (default 30), by op, with cache hit counts. Use it to explain a bill or spot a runaway client.","tags":["usage"],"security":[{"bearerAuth":[]},{"apiKeyHeader":[]},{"oauth2":[]}],"x-units":0,"x-units-label":"free","x-public":false,"x-mcp-tool":"get_usage","x-cli":"geocode get-usage","responses":{"200":{"description":"Get usage","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"The input failed validation (`code: invalid_input`, with `issues`).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"No credential, or an invalid or revoked one. The `WWW-Authenticate` header names the OAuth resource metadata.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"402":{"description":"This month's units on the plan are used up (`code: quota_exceeded`).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limited; retry after `retry_after` seconds.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Our failure; quote `request_id`.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"parameters":[{"name":"days","in":"query","required":false,"description":"How many days back.","schema":{"default":30,"description":"How many days back.","type":"integer","minimum":1,"maximum":90}}]}},"/v1/ops/get_usage":{"post":{"operationId":"get_usage_rpc","summary":"Get usage","description":"RPC form of `get_usage` (same input as JSON). Daily usage for the last N days (default 30), by op, with cache hit counts. Use it to explain a bill or spot a runaway client.","tags":["usage"],"security":[{"bearerAuth":[]},{"apiKeyHeader":[]},{"oauth2":[]}],"x-units":0,"x-units-label":"free","x-public":false,"x-mcp-tool":"get_usage","x-cli":"geocode get-usage","responses":{"200":{"description":"Get usage","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"The input failed validation (`code: invalid_input`, with `issues`).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"No credential, or an invalid or revoked one. The `WWW-Authenticate` header names the OAuth resource metadata.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"402":{"description":"This month's units on the plan are used up (`code: quota_exceeded`).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limited; retry after `retry_after` seconds.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Our failure; quote `request_id`.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"days":{"default":30,"description":"How many days back.","type":"integer","minimum":1,"maximum":90}},"required":[]}}}}}},"/v1/keys":{"get":{"operationId":"list_api_keys","summary":"List API keys","description":"The account's API keys (prefix, name, last use; never the secret).","tags":["keys"],"security":[{"bearerAuth":[]},{"apiKeyHeader":[]},{"oauth2":[]}],"x-units":0,"x-units-label":"free","x-public":false,"x-mcp-tool":"list_api_keys","x-cli":"geocode list-api-keys","responses":{"200":{"description":"List API keys","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"The input failed validation (`code: invalid_input`, with `issues`).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"No credential, or an invalid or revoked one. The `WWW-Authenticate` header names the OAuth resource metadata.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"402":{"description":"This month's units on the plan are used up (`code: quota_exceeded`).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limited; retry after `retry_after` seconds.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Our failure; quote `request_id`.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"parameters":[{"name":"include_revoked","in":"query","required":false,"schema":{"default":false,"type":"boolean"}}]},"post":{"operationId":"create_api_key","summary":"Create API key","description":"Creates an API key and returns the secret once. Store it in an environment variable (GEOCODE_API_KEY); it cannot be shown again.","tags":["keys"],"security":[{"bearerAuth":[]},{"apiKeyHeader":[]},{"oauth2":[]}],"x-units":0,"x-units-label":"free","x-public":false,"x-mcp-tool":"create_api_key","x-cli":"geocode create-api-key","responses":{"200":{"description":"Create API key","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"The input failed validation (`code: invalid_input`, with `issues`).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"No credential, or an invalid or revoked one. The `WWW-Authenticate` header names the OAuth resource metadata.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"402":{"description":"This month's units on the plan are used up (`code: quota_exceeded`).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limited; retry after `retry_after` seconds.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Our failure; quote `request_id`.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"default":"Default key","description":"A label, e.g. the app or environment.","type":"string","minLength":1,"maxLength":80}},"required":[]},"example":{"name":"production"}}}}}},"/v1/ops/list_api_keys":{"post":{"operationId":"list_api_keys_rpc","summary":"List API keys","description":"RPC form of `list_api_keys` (same input as JSON). The account's API keys (prefix, name, last use; never the secret).","tags":["keys"],"security":[{"bearerAuth":[]},{"apiKeyHeader":[]},{"oauth2":[]}],"x-units":0,"x-units-label":"free","x-public":false,"x-mcp-tool":"list_api_keys","x-cli":"geocode list-api-keys","responses":{"200":{"description":"List API keys","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"The input failed validation (`code: invalid_input`, with `issues`).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"No credential, or an invalid or revoked one. The `WWW-Authenticate` header names the OAuth resource metadata.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"402":{"description":"This month's units on the plan are used up (`code: quota_exceeded`).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limited; retry after `retry_after` seconds.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Our failure; quote `request_id`.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"include_revoked":{"default":false,"type":"boolean"}},"required":[]}}}}}},"/v1/ops/create_api_key":{"post":{"operationId":"create_api_key_rpc","summary":"Create API key","description":"RPC form of `create_api_key` (same input as JSON). Creates an API key and returns the secret once. Store it in an environment variable (GEOCODE_API_KEY); it cannot be shown again.","tags":["keys"],"security":[{"bearerAuth":[]},{"apiKeyHeader":[]},{"oauth2":[]}],"x-units":0,"x-units-label":"free","x-public":false,"x-mcp-tool":"create_api_key","x-cli":"geocode create-api-key","responses":{"200":{"description":"Create API key","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"The input failed validation (`code: invalid_input`, with `issues`).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"No credential, or an invalid or revoked one. The `WWW-Authenticate` header names the OAuth resource metadata.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"402":{"description":"This month's units on the plan are used up (`code: quota_exceeded`).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limited; retry after `retry_after` seconds.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Our failure; quote `request_id`.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"default":"Default key","description":"A label, e.g. the app or environment.","type":"string","minLength":1,"maxLength":80}},"required":[]},"example":{"name":"production"}}}}}},"/v1/keys/{id}":{"delete":{"operationId":"revoke_api_key","summary":"Revoke API key","description":"Revokes an API key by id. Requests with it fail with 401 immediately.","tags":["keys"],"security":[{"bearerAuth":[]},{"apiKeyHeader":[]},{"oauth2":[]}],"x-units":0,"x-units-label":"free","x-public":false,"x-mcp-tool":"revoke_api_key","x-cli":"geocode revoke-api-key","responses":{"200":{"description":"Revoke API key","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"The input failed validation (`code: invalid_input`, with `issues`).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"No credential, or an invalid or revoked one. The `WWW-Authenticate` header names the OAuth resource metadata.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"402":{"description":"This month's units on the plan are used up (`code: quota_exceeded`).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limited; retry after `retry_after` seconds.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Our failure; quote `request_id`.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"The key's id from list_api_keys."},"description":"The key's id from list_api_keys."}]}},"/v1/ops/revoke_api_key":{"post":{"operationId":"revoke_api_key_rpc","summary":"Revoke API key","description":"RPC form of `revoke_api_key` (same input as JSON). Revokes an API key by id. Requests with it fail with 401 immediately.","tags":["keys"],"security":[{"bearerAuth":[]},{"apiKeyHeader":[]},{"oauth2":[]}],"x-units":0,"x-units-label":"free","x-public":false,"x-mcp-tool":"revoke_api_key","x-cli":"geocode revoke-api-key","responses":{"200":{"description":"Revoke API key","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"The input failed validation (`code: invalid_input`, with `issues`).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"No credential, or an invalid or revoked one. The `WWW-Authenticate` header names the OAuth resource metadata.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"402":{"description":"This month's units on the plan are used up (`code: quota_exceeded`).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limited; retry after `retry_after` seconds.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Our failure; quote `request_id`.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"The key's id from list_api_keys."}},"required":["id"]}}}}}},"/v1/account/email-preferences":{"get":{"operationId":"get_email_preferences","summary":"Get email preferences","description":"Which automated emails the account receives: the global subscription and one switch per kind (getting-started notes, first boundary, usage milestones, quota warnings, check-ins, monthly digest). Free. Sign-in codes are always sent.","tags":["account"],"security":[{"bearerAuth":[]},{"apiKeyHeader":[]},{"oauth2":[]}],"x-units":0,"x-units-label":"free","x-public":false,"x-mcp-tool":"get_email_preferences","x-cli":"geocode get-email-preferences","responses":{"200":{"description":"Get email preferences","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"The input failed validation (`code: invalid_input`, with `issues`).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"No credential, or an invalid or revoked one. The `WWW-Authenticate` header names the OAuth resource metadata.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"402":{"description":"This month's units on the plan are used up (`code: quota_exceeded`).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limited; retry after `retry_after` seconds.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Our failure; quote `request_id`.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"post":{"operationId":"update_email_preferences","summary":"Update email preferences","description":"Turns automated emails on or off: `subscribed: false` stops all of them (the same as the unsubscribe link), `subscribed: true` resubscribes, and `kinds` switches individual kinds. Kinds not named keep their setting. Free. Returns the preferences after the change.","tags":["account"],"security":[{"bearerAuth":[]},{"apiKeyHeader":[]},{"oauth2":[]}],"x-units":0,"x-units-label":"free","x-public":false,"x-mcp-tool":"update_email_preferences","x-cli":"geocode update-email-preferences","responses":{"200":{"description":"Update email preferences","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"The input failed validation (`code: invalid_input`, with `issues`).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"No credential, or an invalid or revoked one. The `WWW-Authenticate` header names the OAuth resource metadata.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"402":{"description":"This month's units on the plan are used up (`code: quota_exceeded`).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limited; retry after `retry_after` seconds.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Our failure; quote `request_id`.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"subscribed":{"description":"false = unsubscribe from every automated email; true = resubscribe.","type":"boolean"},"kinds":{"description":"Per-kind switches, e.g. {\"digest\": false}.","type":"object","properties":{"journey":{"description":"A few short notes in your first two weeks, each with the next step.","type":"boolean"},"first_boundary":{"description":"One note when you fetch your first boundary.","type":"boolean"},"milestone":{"description":"When your account passes 100, 1,000, 10,000 or 100,000 requests.","type":"boolean"},"quota":{"description":"When you have used 80% and 100% of this month's plan.","type":"boolean"},"winback":{"description":"A note if your API keys go quiet for a few weeks.","type":"boolean"},"digest":{"description":"On the 1st: last month's requests, cache hits and top operations.","type":"boolean"}}}},"required":[]},"example":{"kinds":{"digest":false}}}}}}},"/v1/ops/get_email_preferences":{"post":{"operationId":"get_email_preferences_rpc","summary":"Get email preferences","description":"RPC form of `get_email_preferences` (same input as JSON). Which automated emails the account receives: the global subscription and one switch per kind (getting-started notes, first boundary, usage milestones, quota warnings, check-ins, monthly digest). Free. Sign-in codes are always sent.","tags":["account"],"security":[{"bearerAuth":[]},{"apiKeyHeader":[]},{"oauth2":[]}],"x-units":0,"x-units-label":"free","x-public":false,"x-mcp-tool":"get_email_preferences","x-cli":"geocode get-email-preferences","responses":{"200":{"description":"Get email preferences","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"The input failed validation (`code: invalid_input`, with `issues`).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"No credential, or an invalid or revoked one. The `WWW-Authenticate` header names the OAuth resource metadata.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"402":{"description":"This month's units on the plan are used up (`code: quota_exceeded`).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limited; retry after `retry_after` seconds.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Our failure; quote `request_id`.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{},"required":[]}}}}}},"/v1/ops/update_email_preferences":{"post":{"operationId":"update_email_preferences_rpc","summary":"Update email preferences","description":"RPC form of `update_email_preferences` (same input as JSON). Turns automated emails on or off: `subscribed: false` stops all of them (the same as the unsubscribe link), `subscribed: true` resubscribes, and `kinds` switches individual kinds. Kinds not named keep their setting. Free. Returns the preferences after the change.","tags":["account"],"security":[{"bearerAuth":[]},{"apiKeyHeader":[]},{"oauth2":[]}],"x-units":0,"x-units-label":"free","x-public":false,"x-mcp-tool":"update_email_preferences","x-cli":"geocode update-email-preferences","responses":{"200":{"description":"Update email preferences","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"The input failed validation (`code: invalid_input`, with `issues`).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"No credential, or an invalid or revoked one. The `WWW-Authenticate` header names the OAuth resource metadata.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"402":{"description":"This month's units on the plan are used up (`code: quota_exceeded`).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limited; retry after `retry_after` seconds.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Our failure; quote `request_id`.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"subscribed":{"description":"false = unsubscribe from every automated email; true = resubscribe.","type":"boolean"},"kinds":{"description":"Per-kind switches, e.g. {\"digest\": false}.","type":"object","properties":{"journey":{"description":"A few short notes in your first two weeks, each with the next step.","type":"boolean"},"first_boundary":{"description":"One note when you fetch your first boundary.","type":"boolean"},"milestone":{"description":"When your account passes 100, 1,000, 10,000 or 100,000 requests.","type":"boolean"},"quota":{"description":"When you have used 80% and 100% of this month's plan.","type":"boolean"},"winback":{"description":"A note if your API keys go quiet for a few weeks.","type":"boolean"},"digest":{"description":"On the 1st: last month's requests, cache hits and top operations.","type":"boolean"}}}},"required":[]},"example":{"kinds":{"digest":false}}}}}}},"/v1/feedback":{"get":{"operationId":"list_feedback","summary":"List feature requests and issues","description":"The public feedback board: feature requests and issue reports with their status and upvotes, most upvoted first. Free and needs no key (with a key, each item says whether you voted). Call it before request_feature or report_issue to find an existing item to upvote instead of filing a duplicate, or when the human asks what is planned.","tags":["feedback"],"security":[{},{"bearerAuth":[]},{"apiKeyHeader":[]},{"oauth2":[]}],"x-units":0,"x-units-label":"free","x-public":true,"x-mcp-tool":"list_feedback","x-cli":"geocode list-feedback","responses":{"200":{"description":"List feature requests and issues","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"The input failed validation (`code: invalid_input`, with `issues`).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"No credential, or an invalid or revoked one. The `WWW-Authenticate` header names the OAuth resource metadata.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"402":{"description":"This month's units on the plan are used up (`code: quota_exceeded`).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limited; retry after `retry_after` seconds.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Our failure; quote `request_id`.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"parameters":[{"name":"kind","in":"query","required":false,"description":"feature = feature requests, issue = bug reports.","schema":{"default":"all","description":"feature = feature requests, issue = bug reports.","type":"string","enum":["feature","issue","all"]},"example":"feature"},{"name":"status","in":"query","required":false,"description":"active = open, planned or in progress.","schema":{"default":"active","description":"active = open, planned or in progress.","type":"string","enum":["active","all","open","planned","in_progress","done","declined","duplicate"]}},{"name":"sort","in":"query","required":false,"description":"top = most upvoted, new = most recent.","schema":{"default":"top","description":"top = most upvoted, new = most recent.","type":"string","enum":["top","new"]}},{"name":"q","in":"query","required":false,"description":"Words to find in the title.","schema":{"description":"Words to find in the title.","type":"string","maxLength":100},"example":"postcode"},{"name":"mine","in":"query","required":false,"description":"Only items you filed (needs a key).","content":{"application/json":{"schema":{"description":"Only items you filed (needs a key).","anyOf":[{"type":"boolean"},{"type":"string","enum":["true","false"]}]}}}},{"name":"limit","in":"query","required":false,"description":"Page size, at most 100.","schema":{"default":20,"description":"Page size, at most 100.","type":"integer","minimum":1,"maximum":100}},{"name":"offset","in":"query","required":false,"schema":{"default":0,"type":"integer","minimum":0,"maximum":9007199254740991}}]}},"/v1/ops/list_feedback":{"post":{"operationId":"list_feedback_rpc","summary":"List feature requests and issues","description":"RPC form of `list_feedback` (same input as JSON). The public feedback board: feature requests and issue reports with their status and upvotes, most upvoted first. Free and needs no key (with a key, each item says whether you voted). Call it before request_feature or report_issue to find an existing item to upvote instead of filing a duplicate, or when the human asks what is planned.","tags":["feedback"],"security":[{},{"bearerAuth":[]},{"apiKeyHeader":[]},{"oauth2":[]}],"x-units":0,"x-units-label":"free","x-public":true,"x-mcp-tool":"list_feedback","x-cli":"geocode list-feedback","responses":{"200":{"description":"List feature requests and issues","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"The input failed validation (`code: invalid_input`, with `issues`).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"No credential, or an invalid or revoked one. The `WWW-Authenticate` header names the OAuth resource metadata.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"402":{"description":"This month's units on the plan are used up (`code: quota_exceeded`).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limited; retry after `retry_after` seconds.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Our failure; quote `request_id`.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"kind":{"default":"all","description":"feature = feature requests, issue = bug reports.","type":"string","enum":["feature","issue","all"]},"status":{"default":"active","description":"active = open, planned or in progress.","type":"string","enum":["active","all","open","planned","in_progress","done","declined","duplicate"]},"sort":{"default":"top","description":"top = most upvoted, new = most recent.","type":"string","enum":["top","new"]},"q":{"description":"Words to find in the title.","type":"string","maxLength":100},"mine":{"description":"Only items you filed (needs a key).","anyOf":[{"type":"boolean"},{"type":"string","enum":["true","false"]}]},"limit":{"default":20,"description":"Page size, at most 100.","type":"integer","minimum":1,"maximum":100},"offset":{"default":0,"type":"integer","minimum":0,"maximum":9007199254740991}},"required":[]},"example":{"kind":"feature","q":"postcode"}}}}}},"/v1/feedback/{id}":{"get":{"operationId":"get_feedback","summary":"Get a feature request or issue","description":"One feedback item with its status, upvotes and comments. Free and needs no key.","tags":["feedback"],"security":[{},{"bearerAuth":[]},{"apiKeyHeader":[]},{"oauth2":[]}],"x-units":0,"x-units-label":"free","x-public":true,"x-mcp-tool":"get_feedback","x-cli":"geocode get-feedback","responses":{"200":{"description":"Get a feature request or issue","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"The input failed validation (`code: invalid_input`, with `issues`).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"No credential, or an invalid or revoked one. The `WWW-Authenticate` header names the OAuth resource metadata.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"402":{"description":"This month's units on the plan are used up (`code: quota_exceeded`).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limited; retry after `retry_after` seconds.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Our failure; quote `request_id`.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991,"description":"The item's id from list_feedback, request_feature or report_issue (e.g. 42)."},"description":"The item's id from list_feedback, request_feature or report_issue (e.g. 42).","example":1}]}},"/v1/ops/get_feedback":{"post":{"operationId":"get_feedback_rpc","summary":"Get a feature request or issue","description":"RPC form of `get_feedback` (same input as JSON). One feedback item with its status, upvotes and comments. Free and needs no key.","tags":["feedback"],"security":[{},{"bearerAuth":[]},{"apiKeyHeader":[]},{"oauth2":[]}],"x-units":0,"x-units-label":"free","x-public":true,"x-mcp-tool":"get_feedback","x-cli":"geocode get-feedback","responses":{"200":{"description":"Get a feature request or issue","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"The input failed validation (`code: invalid_input`, with `issues`).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"No credential, or an invalid or revoked one. The `WWW-Authenticate` header names the OAuth resource metadata.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"402":{"description":"This month's units on the plan are used up (`code: quota_exceeded`).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limited; retry after `retry_after` seconds.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Our failure; quote `request_id`.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991,"description":"The item's id from list_feedback, request_feature or report_issue (e.g. 42)."}},"required":["id"]},"example":{"id":1}}}}}},"/v1/feedback/features":{"post":{"operationId":"request_feature","summary":"Request a feature","description":"Files a feature request on the public board and upvotes it for you. Use it when the human wants something the API cannot do yet (a boundary type, export format, op or option). Check list_feedback first and upvote an existing request instead of filing a duplicate. Free; needs a key; 10 new items per account a day. Returns the item and similar existing requests. Everything on the board is public (never the author's email). Do not include API keys, personal data or customer data.","tags":["feedback"],"security":[{"bearerAuth":[]},{"apiKeyHeader":[]},{"oauth2":[]}],"x-units":0,"x-units-label":"free","x-public":false,"x-mcp-tool":"request_feature","x-cli":"geocode request-feature","responses":{"200":{"description":"Request a feature","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"The input failed validation (`code: invalid_input`, with `issues`).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"No credential, or an invalid or revoked one. The `WWW-Authenticate` header names the OAuth resource metadata.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"402":{"description":"This month's units on the plan are used up (`code: quota_exceeded`).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limited; retry after `retry_after` seconds.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Our failure; quote `request_id`.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string","minLength":3,"maxLength":140,"description":"What you want, in one line."},"details":{"default":"","description":"Why you need it and what you are building; concrete examples help it get planned.","type":"string","maxLength":5000}},"required":["title"]},"example":{"title":"Export boundaries as Shapefile","details":"Our GIS team imports zones into ArcGIS, which wants .shp."}}}}}},"/v1/ops/request_feature":{"post":{"operationId":"request_feature_rpc","summary":"Request a feature","description":"RPC form of `request_feature` (same input as JSON). Files a feature request on the public board and upvotes it for you. Use it when the human wants something the API cannot do yet (a boundary type, export format, op or option). Check list_feedback first and upvote an existing request instead of filing a duplicate. Free; needs a key; 10 new items per account a day. Returns the item and similar existing requests. Everything on the board is public (never the author's email). Do not include API keys, personal data or customer data.","tags":["feedback"],"security":[{"bearerAuth":[]},{"apiKeyHeader":[]},{"oauth2":[]}],"x-units":0,"x-units-label":"free","x-public":false,"x-mcp-tool":"request_feature","x-cli":"geocode request-feature","responses":{"200":{"description":"Request a feature","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"The input failed validation (`code: invalid_input`, with `issues`).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"No credential, or an invalid or revoked one. The `WWW-Authenticate` header names the OAuth resource metadata.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"402":{"description":"This month's units on the plan are used up (`code: quota_exceeded`).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limited; retry after `retry_after` seconds.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Our failure; quote `request_id`.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string","minLength":3,"maxLength":140,"description":"What you want, in one line."},"details":{"default":"","description":"Why you need it and what you are building; concrete examples help it get planned.","type":"string","maxLength":5000}},"required":["title"]},"example":{"title":"Export boundaries as Shapefile","details":"Our GIS team imports zones into ArcGIS, which wants .shp."}}}}}},"/v1/feedback/issues":{"post":{"operationId":"report_issue","summary":"Report an issue","description":"Reports a problem on the public board: a failing or wrong API call (pass its request_id from the X-Request-Id header or the error's request_id, and the op), a wrong or missing boundary, a docs error, or anything else broken. Check list_feedback with kind=issue first and upvote a matching report instead. Free; needs a key; 10 new items per account a day. Only you see the request_id. Everything on the board is public (never the author's email). Do not include API keys, personal data or customer data.","tags":["feedback"],"security":[{"bearerAuth":[]},{"apiKeyHeader":[]},{"oauth2":[]}],"x-units":0,"x-units-label":"free","x-public":false,"x-mcp-tool":"report_issue","x-cli":"geocode report-issue","responses":{"200":{"description":"Report an issue","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"The input failed validation (`code: invalid_input`, with `issues`).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"No credential, or an invalid or revoked one. The `WWW-Authenticate` header names the OAuth resource metadata.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"402":{"description":"This month's units on the plan are used up (`code: quota_exceeded`).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limited; retry after `retry_after` seconds.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Our failure; quote `request_id`.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string","minLength":3,"maxLength":140,"description":"What is wrong, in one line."},"details":{"default":"","description":"What you did, what you expected and what happened (status, error code, boundary id).","type":"string","maxLength":5000},"request_id":{"description":"The request_id of the failing call, if there was one.","type":"string","maxLength":100},"op":{"description":"The op the failing call used, e.g. get_boundary.","type":"string","maxLength":80}},"required":["title"]},"example":{"title":"get_boundary returns 404 for r62422","details":"Berlin by relation id: 404 not_found since this morning.","op":"get_boundary"}}}}}},"/v1/ops/report_issue":{"post":{"operationId":"report_issue_rpc","summary":"Report an issue","description":"RPC form of `report_issue` (same input as JSON). Reports a problem on the public board: a failing or wrong API call (pass its request_id from the X-Request-Id header or the error's request_id, and the op), a wrong or missing boundary, a docs error, or anything else broken. Check list_feedback with kind=issue first and upvote a matching report instead. Free; needs a key; 10 new items per account a day. Only you see the request_id. Everything on the board is public (never the author's email). Do not include API keys, personal data or customer data.","tags":["feedback"],"security":[{"bearerAuth":[]},{"apiKeyHeader":[]},{"oauth2":[]}],"x-units":0,"x-units-label":"free","x-public":false,"x-mcp-tool":"report_issue","x-cli":"geocode report-issue","responses":{"200":{"description":"Report an issue","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"The input failed validation (`code: invalid_input`, with `issues`).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"No credential, or an invalid or revoked one. The `WWW-Authenticate` header names the OAuth resource metadata.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"402":{"description":"This month's units on the plan are used up (`code: quota_exceeded`).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limited; retry after `retry_after` seconds.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Our failure; quote `request_id`.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string","minLength":3,"maxLength":140,"description":"What is wrong, in one line."},"details":{"default":"","description":"What you did, what you expected and what happened (status, error code, boundary id).","type":"string","maxLength":5000},"request_id":{"description":"The request_id of the failing call, if there was one.","type":"string","maxLength":100},"op":{"description":"The op the failing call used, e.g. get_boundary.","type":"string","maxLength":80}},"required":["title"]},"example":{"title":"get_boundary returns 404 for r62422","details":"Berlin by relation id: 404 not_found since this morning.","op":"get_boundary"}}}}}},"/v1/feedback/{id}/vote":{"post":{"operationId":"upvote_feedback","summary":"Upvote a feature request or issue","description":"Adds your upvote to a feature request or issue; votes decide what gets built and fixed first. Idempotent: one vote per account. A vote on a duplicate goes to the original. Free; needs a key. Returns the item with its new vote count.","tags":["feedback"],"security":[{"bearerAuth":[]},{"apiKeyHeader":[]},{"oauth2":[]}],"x-units":0,"x-units-label":"free","x-public":false,"x-mcp-tool":"upvote_feedback","x-cli":"geocode upvote-feedback","responses":{"200":{"description":"Upvote a feature request or issue","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"The input failed validation (`code: invalid_input`, with `issues`).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"No credential, or an invalid or revoked one. The `WWW-Authenticate` header names the OAuth resource metadata.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"402":{"description":"This month's units on the plan are used up (`code: quota_exceeded`).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limited; retry after `retry_after` seconds.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Our failure; quote `request_id`.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{},"required":[]},"example":{}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991,"description":"The item's id from list_feedback, request_feature or report_issue (e.g. 42)."},"description":"The item's id from list_feedback, request_feature or report_issue (e.g. 42).","example":1}]},"delete":{"operationId":"remove_feedback_vote","summary":"Remove an upvote","description":"Takes back your upvote on a feature request or issue. Free; needs a key. Returns the item with its new vote count.","tags":["feedback"],"security":[{"bearerAuth":[]},{"apiKeyHeader":[]},{"oauth2":[]}],"x-units":0,"x-units-label":"free","x-public":false,"x-mcp-tool":"remove_feedback_vote","x-cli":"geocode remove-feedback-vote","responses":{"200":{"description":"Remove an upvote","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"The input failed validation (`code: invalid_input`, with `issues`).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"No credential, or an invalid or revoked one. The `WWW-Authenticate` header names the OAuth resource metadata.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"402":{"description":"This month's units on the plan are used up (`code: quota_exceeded`).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limited; retry after `retry_after` seconds.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Our failure; quote `request_id`.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991,"description":"The item's id from list_feedback, request_feature or report_issue (e.g. 42)."},"description":"The item's id from list_feedback, request_feature or report_issue (e.g. 42).","example":1}]}},"/v1/ops/upvote_feedback":{"post":{"operationId":"upvote_feedback_rpc","summary":"Upvote a feature request or issue","description":"RPC form of `upvote_feedback` (same input as JSON). Adds your upvote to a feature request or issue; votes decide what gets built and fixed first. Idempotent: one vote per account. A vote on a duplicate goes to the original. Free; needs a key. Returns the item with its new vote count.","tags":["feedback"],"security":[{"bearerAuth":[]},{"apiKeyHeader":[]},{"oauth2":[]}],"x-units":0,"x-units-label":"free","x-public":false,"x-mcp-tool":"upvote_feedback","x-cli":"geocode upvote-feedback","responses":{"200":{"description":"Upvote a feature request or issue","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"The input failed validation (`code: invalid_input`, with `issues`).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"No credential, or an invalid or revoked one. The `WWW-Authenticate` header names the OAuth resource metadata.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"402":{"description":"This month's units on the plan are used up (`code: quota_exceeded`).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limited; retry after `retry_after` seconds.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Our failure; quote `request_id`.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991,"description":"The item's id from list_feedback, request_feature or report_issue (e.g. 42)."}},"required":["id"]},"example":{"id":1}}}}}},"/v1/ops/remove_feedback_vote":{"post":{"operationId":"remove_feedback_vote_rpc","summary":"Remove an upvote","description":"RPC form of `remove_feedback_vote` (same input as JSON). Takes back your upvote on a feature request or issue. Free; needs a key. Returns the item with its new vote count.","tags":["feedback"],"security":[{"bearerAuth":[]},{"apiKeyHeader":[]},{"oauth2":[]}],"x-units":0,"x-units-label":"free","x-public":false,"x-mcp-tool":"remove_feedback_vote","x-cli":"geocode remove-feedback-vote","responses":{"200":{"description":"Remove an upvote","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"The input failed validation (`code: invalid_input`, with `issues`).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"No credential, or an invalid or revoked one. The `WWW-Authenticate` header names the OAuth resource metadata.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"402":{"description":"This month's units on the plan are used up (`code: quota_exceeded`).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limited; retry after `retry_after` seconds.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Our failure; quote `request_id`.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991,"description":"The item's id from list_feedback, request_feature or report_issue (e.g. 42)."}},"required":["id"]},"example":{"id":1}}}}}},"/v1/feedback/{id}/comments":{"post":{"operationId":"comment_on_feedback","summary":"Comment on a feature request or issue","description":"Adds context to an existing feature request or issue: your use case, another failing request, a workaround. Prefer it (with upvote_feedback) over filing a near-duplicate. Free; needs a key; 50 comments per account a day. Everything on the board is public (never the author's email). Do not include API keys, personal data or customer data.","tags":["feedback"],"security":[{"bearerAuth":[]},{"apiKeyHeader":[]},{"oauth2":[]}],"x-units":0,"x-units-label":"free","x-public":false,"x-mcp-tool":"comment_on_feedback","x-cli":"geocode comment-on-feedback","responses":{"200":{"description":"Comment on a feature request or issue","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"The input failed validation (`code: invalid_input`, with `issues`).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"No credential, or an invalid or revoked one. The `WWW-Authenticate` header names the OAuth resource metadata.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"402":{"description":"This month's units on the plan are used up (`code: quota_exceeded`).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limited; retry after `retry_after` seconds.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Our failure; quote `request_id`.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"body":{"type":"string","minLength":1,"maxLength":5000,"description":"The comment."}},"required":["body"]},"example":{"body":"Same for us: we need this for French départements."}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991,"description":"The item's id from list_feedback, request_feature or report_issue (e.g. 42)."},"description":"The item's id from list_feedback, request_feature or report_issue (e.g. 42).","example":1}]}},"/v1/ops/comment_on_feedback":{"post":{"operationId":"comment_on_feedback_rpc","summary":"Comment on a feature request or issue","description":"RPC form of `comment_on_feedback` (same input as JSON). Adds context to an existing feature request or issue: your use case, another failing request, a workaround. Prefer it (with upvote_feedback) over filing a near-duplicate. Free; needs a key; 50 comments per account a day. Everything on the board is public (never the author's email). Do not include API keys, personal data or customer data.","tags":["feedback"],"security":[{"bearerAuth":[]},{"apiKeyHeader":[]},{"oauth2":[]}],"x-units":0,"x-units-label":"free","x-public":false,"x-mcp-tool":"comment_on_feedback","x-cli":"geocode comment-on-feedback","responses":{"200":{"description":"Comment on a feature request or issue","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"The input failed validation (`code: invalid_input`, with `issues`).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"No credential, or an invalid or revoked one. The `WWW-Authenticate` header names the OAuth resource metadata.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"402":{"description":"This month's units on the plan are used up (`code: quota_exceeded`).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limited; retry after `retry_after` seconds.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Our failure; quote `request_id`.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991,"description":"The item's id from list_feedback, request_feature or report_issue (e.g. 42)."},"body":{"type":"string","minLength":1,"maxLength":5000,"description":"The comment."}},"required":["id","body"]},"example":{"id":1,"body":"Same for us: we need this for French départements."}}}}}},"/v1/pricing":{"get":{"operationId":"get_pricing","summary":"Get plans and prices","description":"The plans (monthly price, included units, rate limit) and what each kind of call costs in units. Free and needs no key. Call it before a large batch, or when the human asks what something costs; never quote prices from memory.","tags":["account"],"security":[{},{"bearerAuth":[]},{"apiKeyHeader":[]},{"oauth2":[]}],"x-units":0,"x-units-label":"free","x-public":true,"x-mcp-tool":"get_pricing","x-cli":"geocode get-pricing","responses":{"200":{"description":"Get plans and prices","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"The input failed validation (`code: invalid_input`, with `issues`).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"No credential, or an invalid or revoked one. The `WWW-Authenticate` header names the OAuth resource metadata.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"402":{"description":"This month's units on the plan are used up (`code: quota_exceeded`).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limited; retry after `retry_after` seconds.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Our failure; quote `request_id`.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/ops/get_pricing":{"post":{"operationId":"get_pricing_rpc","summary":"Get plans and prices","description":"RPC form of `get_pricing` (same input as JSON). The plans (monthly price, included units, rate limit) and what each kind of call costs in units. Free and needs no key. Call it before a large batch, or when the human asks what something costs; never quote prices from memory.","tags":["account"],"security":[{},{"bearerAuth":[]},{"apiKeyHeader":[]},{"oauth2":[]}],"x-units":0,"x-units-label":"free","x-public":true,"x-mcp-tool":"get_pricing","x-cli":"geocode get-pricing","responses":{"200":{"description":"Get plans and prices","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"The input failed validation (`code: invalid_input`, with `issues`).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"No credential, or an invalid or revoked one. The `WWW-Authenticate` header names the OAuth resource metadata.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"402":{"description":"This month's units on the plan are used up (`code: quota_exceeded`).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limited; retry after `retry_after` seconds.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Our failure; quote `request_id`.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{},"required":[]},"example":{}}}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"An API key (geo_…) from https://geo-coder-service.vercel.app/dashboard, or an OAuth access token."},"apiKeyHeader":{"type":"apiKey","in":"header","name":"X-Api-Key","description":"The same API key (geo_…) in a header of its own."},"oauth2":{"type":"oauth2","description":"Supabase Auth's OAuth 2.1 server (authorization code + PKCE, dynamic client registration). For apps that act for a person, like chat connectors.","flows":{"authorizationCode":{"authorizationUrl":"https://ythnblmpijftrtdlobcq.supabase.co/auth/v1/oauth/authorize","tokenUrl":"https://ythnblmpijftrtdlobcq.supabase.co/auth/v1/oauth/token","scopes":{"openid":"OpenID openid","email":"OpenID email","profile":"OpenID profile"}}}}},"schemas":{"Problem":{"type":"object","description":"RFC 9457 problem details.","required":["type","title","status","detail","request_id"],"properties":{"type":{"type":"string","format":"uri"},"title":{"type":"string","description":"Same as code."},"status":{"type":"integer"},"detail":{"type":"string","description":"What went wrong and what to do, for a human or an agent."},"code":{"type":"string","examples":["invalid_input","unauthorized","quota_exceeded","not_found","rate_limited"]},"request_id":{"type":"string"}},"additionalProperties":true}}}}