{"components":{"schemas":{"AddressDetails":{"additionalProperties":false,"properties":{"aerialway":{"type":"string"},"aeroway":{"type":"string"},"allotments":{"type":"string"},"amenity":{"type":"string"},"borough":{"type":"string"},"boundary":{"type":"string"},"bridge":{"type":"string"},"city":{"type":"string"},"cityBlock":{"type":"string"},"cityDistrict":{"type":"string"},"club":{"type":"string"},"commercial":{"type":"string"},"continent":{"type":"string"},"country":{"type":"string"},"countryCode":{"type":"string"},"county":{"type":"string"},"craft":{"type":"string"},"croft":{"type":"string"},"district":{"type":"string"},"emergency":{"type":"string"},"farm":{"type":"string"},"farmyard":{"type":"string"},"hamlet":{"type":"string"},"highway":{"type":"string"},"historic":{"type":"string"},"houseName":{"type":"string"},"houseNumber":{"type":"string"},"industrial":{"type":"string"},"isolatedDwelling":{"type":"string"},"landuse":{"type":"string"},"leisure":{"type":"string"},"manMade":{"type":"string"},"military":{"type":"string"},"mountainPass":{"type":"string"},"municipality":{"type":"string"},"natural":{"type":"string"},"neighbourhood":{"type":"string"},"office":{"type":"string"},"place":{"type":"string"},"postcode":{"type":"string"},"province":{"type":"string"},"quarter":{"type":"string"},"railway":{"type":"string"},"region":{"type":"string"},"regionCodes":{"description":"ISO 3166-2 codes for the address.","items":{"$ref":"#/components/schemas/ISO3166_2"},"type":"array"},"regions":{"description":"Administrative regions for the address.","items":{"$ref":"#/components/schemas/Region"},"type":"array"},"residential":{"type":"string"},"retail":{"type":"string"},"road":{"type":"string"},"shop":{"type":"string"},"state":{"type":"string"},"stateDistrict":{"type":"string"},"subdivision":{"type":"string"},"suburb":{"type":"string"},"tourism":{"type":"string"},"town":{"type":"string"},"tunnel":{"type":"string"},"village":{"type":"string"},"waterway":{"type":"string"}},"type":"object"},"AutocompleteRequest":{"additionalProperties":false,"properties":{"countryCode":{"description":"Optional ISO 3166-1 alpha-2 country filter, for example dk.","type":"string"},"focus":{"$ref":"#/components/schemas/SuggestFocus","description":"Optional: the user's position. Places near it rank higher."},"includeLandmarks":{"default":false,"description":"Include notable OSM landmarks linked to Wikidata. Coverage is uneven; this is not a general business directory.","type":"boolean"},"limit":{"default":5,"description":"Maximum suggestions. Omitted or 0 uses the default of 5.","format":"int64","maximum":15,"minimum":0,"type":"integer"},"text":{"description":"Address or place prefix. The last word may be unfinished. Trimmed; cannot be blank.","maxLength":500,"minLength":1,"type":"string"}},"required":["text"],"type":"object"},"AutocompleteResponse":{"additionalProperties":false,"properties":{"suggestions":{"description":"Ranked suggestions.","items":{"$ref":"#/components/schemas/Suggestion"},"type":"array"}},"type":"object"},"BoundingBox":{"additionalProperties":false,"properties":{"maxLat":{"description":"Northern latitude in degrees.","format":"float","type":"number"},"maxLon":{"description":"Eastern longitude in degrees.","format":"float","type":"number"},"minLat":{"description":"Southern latitude in degrees.","format":"float","type":"number"},"minLon":{"description":"Western longitude in degrees.","format":"float","type":"number"}},"type":"object"},"Error":{"properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"type":"object"},"FullAddress":{"additionalProperties":false,"properties":{"addressDetails":{"$ref":"#/components/schemas/AddressDetails"},"displayName":{"description":"Human-readable address or place name.","type":"string"},"geoCoordinates":{"$ref":"#/components/schemas/GeoCoordinates"},"goodMatch":{"description":"True for a good match. False or omitted for a partial match, such as a street without the requested house number.","type":"boolean"}},"type":"object"},"GeoCoordinates":{"additionalProperties":false,"properties":{"boundingBox":{"$ref":"#/components/schemas/BoundingBox"},"lat":{"description":"Latitude in degrees, from -90 to 90. Omission uses the protobuf default of 0.","format":"float","type":"number"},"lon":{"description":"Longitude in degrees, from -180 to 180. Omission uses the protobuf default of 0.","format":"float","type":"number"}},"type":"object"},"ISO3166_2":{"additionalProperties":false,"properties":{"adminLevel":{"description":"Administrative level.","format":"int64","maximum":4294967295,"minimum":0,"type":"integer"},"code":{"description":"ISO 3166-2 region code.","type":"string"}},"type":"object"},"Region":{"additionalProperties":false,"properties":{"adminCode":{"description":"ISO 3166-2 administrative region code.","type":"string"},"adminLevel":{"description":"Administrative level.","format":"int64","maximum":4294967295,"minimum":0,"type":"integer"},"countryCode":{"description":"ISO 3166-1 alpha-2 country code.","type":"string"},"countryName":{"description":"Country name.","type":"string"},"enName":{"description":"English region name.","type":"string"},"localName":{"description":"Local region name.","type":"string"},"parentAdminCode":{"description":"Parent administrative region code, when available.","type":"string"}},"type":"object"},"RegionsRequest":{"additionalProperties":false,"properties":{},"type":"object"},"RegionsResponse":{"additionalProperties":false,"properties":{"regions":{"description":"Countries and administrative regions known to the index.","items":{"$ref":"#/components/schemas/Region"},"type":"array"}},"type":"object"},"RetrieveRequest":{"additionalProperties":false,"properties":{"id":{"description":"Opaque ID returned by autocomplete. Do not parse or construct it.","maxLength":256,"minLength":1,"type":"string"}},"required":["id"],"type":"object"},"RetrievedSuggestion":{"additionalProperties":false,"properties":{"category":{"description":"Landmarks only: airport, station, attraction, museum, university, hospital or stadium.\n Empty for every other type.","type":"string"},"countryCode":{"type":"string"},"displayName":{"type":"string"},"geoCoordinates":{"$ref":"#/components/schemas/GeoCoordinates","description":"The point of the place, street, house, postcode or landmark. Places also carry their\n bounding box."},"id":{"description":"Stable for one index, and opaque: a place, street, house, postcode or landmark.","type":"string"},"type":{"description":"country, region, county, municipality, city, town, village, neighbourhood, street, address,\n postcode or landmark.","type":"string"},"unverifiedSuffix":{"description":"User-entered floor/unit text, also kept in display_name. Not verified: id and point\n still identify the building. Empty when no suffix interpretation was needed.","type":"string"}},"type":"object"},"ReverseRequest":{"additionalProperties":false,"properties":{"lat":{"description":"Latitude in degrees, from -90 to 90. Omission uses 0.","format":"float","type":"number"},"lon":{"description":"Longitude in degrees, from -180 to 180. Omission uses 0.","format":"float","type":"number"},"radiusM":{"default":500,"description":"Search radius in metres. Omitted or 0 uses 500.","format":"int64","maximum":2000,"minimum":0,"type":"integer"},"size":{"default":1,"description":"Maximum results. Omitted or 0 uses 1.","format":"int64","maximum":10,"minimum":0,"type":"integer"}},"type":"object"},"ReverseResponse":{"additionalProperties":false,"properties":{"results":{"description":"Nearest first. Empty or omitted when nothing is in range.","items":{"$ref":"#/components/schemas/ReverseResult"},"type":"array"}},"type":"object"},"ReverseResult":{"additionalProperties":false,"properties":{"address":{"$ref":"#/components/schemas/FullAddress"},"distanceM":{"description":"Distance from the requested point, in metres.","format":"float","type":"number"},"layer":{"description":"address: a house in range; street: no house in range; locality: neither, so the nearest locality within about 50 km.","type":"string"}},"type":"object"},"SearchRequest":{"additionalProperties":false,"properties":{"addressString":{"description":"Free-text address or place. Trimmed before searching; cannot be blank.","maxLength":500,"minLength":1,"type":"string"}},"required":["addressString"],"type":"object"},"SuggestFocus":{"additionalProperties":false,"properties":{"lat":{"description":"Latitude of the position to bias results toward.","format":"float","type":"number"},"lon":{"description":"Longitude of the position to bias results toward.","format":"float","type":"number"},"scaleKm":{"default":100,"description":"Distance scale of the location bias, in kilometres. Omitted or 0 uses 100.","format":"int64","maximum":20000,"minimum":0,"type":"integer"}},"type":"object"},"Suggestion":{"additionalProperties":false,"properties":{"category":{"description":"Landmarks only: airport, station, attraction, museum, university, hospital or stadium. Empty or omitted otherwise.","type":"string"},"countryCode":{"description":"ISO 3166-1 alpha-2 country code.","type":"string"},"displayName":{"description":"Human-readable label.","type":"string"},"id":{"description":"Opaque identifier, stable for one index.","type":"string"},"type":{"description":"country, region, county, municipality, city, town, village, neighbourhood, street, address, postcode or landmark.","type":"string"},"unverifiedSuffix":{"description":"User-entered floor/unit text, also kept in display_name. Not verified: id and point\n still identify the building. Empty when no suffix interpretation was needed.","type":"string"}},"type":"object"}},"securitySchemes":{"ApiKey":{"description":"Create an API key in the dashboard.","in":"header","name":"x-api-key","type":"apiKey"},"BearerAuth":{"description":"Use a dashboard API key or an OpenGeocoding MCP OAuth access token with the geocoding:read scope. OAuth access shares the account's credits and rate limits.","scheme":"bearer","type":"http"}}},"info":{"description":"Geocoding, autocomplete, reverse geocoding and administrative regions. POST requests use Connect JSON (camelCase; protobuf snake_case is also accepted). Unknown fields are rejected. Bodies are limited to 64 KiB. Default scalar values and empty lists may be omitted from responses. Examples are illustrative, not measured API results. The production domain is not final; replace the example server URL before calling the API. Native unary gRPC is documented separately at /docs/protocols.","title":"OpenGeocoding API","version":"1.0.0"},"openapi":"3.1.0","paths":{"/v1/autocomplete":{"post":{"description":"Complete an address or place while the last word is still unfinished. Free of credit charges, authenticated and rate-limited, including with zero credits. Returns labels and opaque IDs without coordinates or bounding boxes. Call /v1/retrieve with a selected ID to get its location for one credit. Filter by country, bias toward a position, or include notable landmarks linked to Wikidata.","operationId":"Autocomplete","parameters":[{"description":"Optional. Must be 1 when supplied.","in":"header","name":"Connect-Protocol-Version","required":false,"schema":{"enum":["1"],"type":"string"}}],"requestBody":{"content":{"application/json":{"example":{"countryCode":"dk","focus":{"lat":55.676,"lon":12.568,"scaleKm":100},"includeLandmarks":true,"limit":5,"text":"Copenh"},"schema":{"$ref":"#/components/schemas/AutocompleteRequest"}}},"required":true},"responses":{"200":{"content":{"application/json":{"example":{"suggestions":[{"countryCode":"dk","displayName":"Copenhagen, Denmark","id":"example-place-id","type":"city"}]},"schema":{"$ref":"#/components/schemas/AutocompleteResponse"}}},"description":"Successful response. No credits consumed."},"400":{"content":{"application/json":{"example":{"code":"invalid_argument","message":"Invalid JSON, unknown fields, unsupported Connect protocol version, oversized body, invalid query or unverifiable client address."},"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Invalid JSON, unknown fields, unsupported Connect protocol version, oversized body, invalid query or unverifiable client address."},"401":{"content":{"application/json":{"example":{"code":"unauthenticated","message":"The API key is missing, invalid or revoked."},"schema":{"$ref":"#/components/schemas/Error"}}},"description":"The API key is missing, invalid or revoked."},"404":{"content":{"application/json":{"example":{"code":"not_found","message":"The suggestion ID is unknown or belongs to an older index. Request autocomplete suggestions again."},"schema":{"$ref":"#/components/schemas/Error"}}},"description":"The suggestion ID is unknown or belongs to an older index. Request autocomplete suggestions again."},"429":{"content":{"application/json":{"example":{"code":"resource_exhausted","message":"The per-second limit was reached, a billable operation has no remaining credits, or the client IP is temporarily locked after failed API authentication. Autocomplete and regions remain available with zero credits. IP lockouts include Retry-After and also block valid keys from that IP until expiry."},"schema":{"$ref":"#/components/schemas/Error"}}},"description":"The per-second limit was reached, a billable operation has no remaining credits, or the client IP is temporarily locked after failed API authentication. Autocomplete and regions remain available with zero credits. IP lockouts include Retry-After and also block valid keys from that IP until expiry.","headers":{"Retry-After":{"description":"Seconds to wait for a per-second rate limit or temporary IP authentication lockout. Not returned for exhausted credits.","schema":{"type":"integer"}}}},"503":{"content":{"application/json":{"example":{"code":"unavailable","message":"The API is starting or the geocoder is temporarily unavailable."},"schema":{"$ref":"#/components/schemas/Error"}}},"description":"The API is starting or the geocoder is temporarily unavailable."}},"summary":"Suggest places as someone types","tags":["Geocoding"],"x-credit-cost":0,"x-docs-order":1,"x-docs-slug":"autocomplete","x-docs-title":"Autocomplete"}},"/v1/regions":{"post":{"description":"Return every country and ISO 3166-2 administrative region known to the index. Free of credit charges, authenticated and rate-limited, including with zero credits. Send an empty JSON object as the request body.","operationId":"Regions","parameters":[{"description":"Optional. Must be 1 when supplied.","in":"header","name":"Connect-Protocol-Version","required":false,"schema":{"enum":["1"],"type":"string"}}],"requestBody":{"content":{"application/json":{"example":{},"schema":{"$ref":"#/components/schemas/RegionsRequest"}}},"required":true},"responses":{"200":{"content":{"application/json":{"example":{"regions":[{"adminCode":"DK-84","adminLevel":4,"countryCode":"dk","countryName":"Denmark","enName":"Capital Region","localName":"Region Hovedstaden"}]},"schema":{"$ref":"#/components/schemas/RegionsResponse"}}},"description":"Successful response. No credits consumed."},"400":{"content":{"application/json":{"example":{"code":"invalid_argument","message":"Invalid JSON, unknown fields, unsupported Connect protocol version, oversized body, invalid query or unverifiable client address."},"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Invalid JSON, unknown fields, unsupported Connect protocol version, oversized body, invalid query or unverifiable client address."},"401":{"content":{"application/json":{"example":{"code":"unauthenticated","message":"The API key is missing, invalid or revoked."},"schema":{"$ref":"#/components/schemas/Error"}}},"description":"The API key is missing, invalid or revoked."},"404":{"content":{"application/json":{"example":{"code":"not_found","message":"The suggestion ID is unknown or belongs to an older index. Request autocomplete suggestions again."},"schema":{"$ref":"#/components/schemas/Error"}}},"description":"The suggestion ID is unknown or belongs to an older index. Request autocomplete suggestions again."},"429":{"content":{"application/json":{"example":{"code":"resource_exhausted","message":"The per-second limit was reached, a billable operation has no remaining credits, or the client IP is temporarily locked after failed API authentication. Autocomplete and regions remain available with zero credits. IP lockouts include Retry-After and also block valid keys from that IP until expiry."},"schema":{"$ref":"#/components/schemas/Error"}}},"description":"The per-second limit was reached, a billable operation has no remaining credits, or the client IP is temporarily locked after failed API authentication. Autocomplete and regions remain available with zero credits. IP lockouts include Retry-After and also block valid keys from that IP until expiry.","headers":{"Retry-After":{"description":"Seconds to wait for a per-second rate limit or temporary IP authentication lockout. Not returned for exhausted credits.","schema":{"type":"integer"}}}},"503":{"content":{"application/json":{"example":{"code":"unavailable","message":"The API is starting or the geocoder is temporarily unavailable."},"schema":{"$ref":"#/components/schemas/Error"}}},"description":"The API is starting or the geocoder is temporarily unavailable."}},"summary":"List indexed countries and regions","tags":["Regions"],"x-credit-cost":0,"x-docs-order":4,"x-docs-slug":"regions","x-docs-title":"List regions"}},"/v1/resolve-region":{"post":{"description":"Resolve ISO 3166-2 administrative regions for coordinates. The response uses the same region entries as List regions.","operationId":"ResolveRegion","parameters":[{"description":"Optional. Must be 1 when supplied.","in":"header","name":"Connect-Protocol-Version","required":false,"schema":{"enum":["1"],"type":"string"}}],"requestBody":{"content":{"application/json":{"example":{"lat":55.6761,"lon":12.5683},"schema":{"$ref":"#/components/schemas/GeoCoordinates"}}},"required":true},"responses":{"200":{"content":{"application/json":{"example":{"regions":[{"adminCode":"DK-84","adminLevel":4,"countryCode":"dk","countryName":"Denmark","enName":"Capital Region","localName":"Region Hovedstaden"}]},"schema":{"$ref":"#/components/schemas/RegionsResponse"}}},"description":"Successful lookup. Consumes one credit."},"400":{"content":{"application/json":{"example":{"code":"invalid_argument","message":"Invalid JSON, unknown fields, unsupported Connect protocol version, oversized body, invalid query or unverifiable client address."},"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Invalid JSON, unknown fields, unsupported Connect protocol version, oversized body, invalid query or unverifiable client address."},"401":{"content":{"application/json":{"example":{"code":"unauthenticated","message":"The API key is missing, invalid or revoked."},"schema":{"$ref":"#/components/schemas/Error"}}},"description":"The API key is missing, invalid or revoked."},"404":{"content":{"application/json":{"example":{"code":"not_found","message":"The suggestion ID is unknown or belongs to an older index. Request autocomplete suggestions again."},"schema":{"$ref":"#/components/schemas/Error"}}},"description":"The suggestion ID is unknown or belongs to an older index. Request autocomplete suggestions again."},"429":{"content":{"application/json":{"example":{"code":"resource_exhausted","message":"The per-second limit was reached, a billable operation has no remaining credits, or the client IP is temporarily locked after failed API authentication. Autocomplete and regions remain available with zero credits. IP lockouts include Retry-After and also block valid keys from that IP until expiry."},"schema":{"$ref":"#/components/schemas/Error"}}},"description":"The per-second limit was reached, a billable operation has no remaining credits, or the client IP is temporarily locked after failed API authentication. Autocomplete and regions remain available with zero credits. IP lockouts include Retry-After and also block valid keys from that IP until expiry.","headers":{"Retry-After":{"description":"Seconds to wait for a per-second rate limit or temporary IP authentication lockout. Not returned for exhausted credits.","schema":{"type":"integer"}}}},"503":{"content":{"application/json":{"example":{"code":"unavailable","message":"The API is starting or the geocoder is temporarily unavailable."},"schema":{"$ref":"#/components/schemas/Error"}}},"description":"The API is starting or the geocoder is temporarily unavailable."}},"summary":"Find the administrative regions at a point","tags":["Regions"],"x-credit-cost":1,"x-docs-order":5,"x-docs-slug":"resolve-region","x-docs-title":"Resolve regions"}},"/v1/retrieve":{"post":{"description":"Retrieve the exact suggestion selected from autocomplete. A successful response costs one credit. IDs are opaque and tied to an index snapshot; a stale or unknown ID returns 404. Request suggestions again after an index update. Unverified floor or unit suffixes are not part of the retrieved building.","operationId":"Retrieve","parameters":[{"description":"Optional. Must be 1 when supplied.","in":"header","name":"Connect-Protocol-Version","required":false,"schema":{"enum":["1"],"type":"string"}}],"requestBody":{"content":{"application/json":{"example":{"id":"example-place-id"},"schema":{"$ref":"#/components/schemas/RetrieveRequest"}}},"required":true},"responses":{"200":{"content":{"application/json":{"example":{"countryCode":"dk","displayName":"Copenhagen, Denmark","geoCoordinates":{"lat":55.676,"lon":12.568},"id":"example-place-id","type":"city"},"schema":{"$ref":"#/components/schemas/RetrievedSuggestion"}}},"description":"Successful lookup. Consumes one credit."},"400":{"content":{"application/json":{"example":{"code":"invalid_argument","message":"Invalid JSON, unknown fields, unsupported Connect protocol version, oversized body, invalid query or unverifiable client address."},"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Invalid JSON, unknown fields, unsupported Connect protocol version, oversized body, invalid query or unverifiable client address."},"401":{"content":{"application/json":{"example":{"code":"unauthenticated","message":"The API key is missing, invalid or revoked."},"schema":{"$ref":"#/components/schemas/Error"}}},"description":"The API key is missing, invalid or revoked."},"404":{"content":{"application/json":{"example":{"code":"not_found","message":"The suggestion ID is unknown or belongs to an older index. Request autocomplete suggestions again."},"schema":{"$ref":"#/components/schemas/Error"}}},"description":"The suggestion ID is unknown or belongs to an older index. Request autocomplete suggestions again."},"429":{"content":{"application/json":{"example":{"code":"resource_exhausted","message":"The per-second limit was reached, a billable operation has no remaining credits, or the client IP is temporarily locked after failed API authentication. Autocomplete and regions remain available with zero credits. IP lockouts include Retry-After and also block valid keys from that IP until expiry."},"schema":{"$ref":"#/components/schemas/Error"}}},"description":"The per-second limit was reached, a billable operation has no remaining credits, or the client IP is temporarily locked after failed API authentication. Autocomplete and regions remain available with zero credits. IP lockouts include Retry-After and also block valid keys from that IP until expiry.","headers":{"Retry-After":{"description":"Seconds to wait for a per-second rate limit or temporary IP authentication lockout. Not returned for exhausted credits.","schema":{"type":"integer"}}}},"503":{"content":{"application/json":{"example":{"code":"unavailable","message":"The API is starting or the geocoder is temporarily unavailable."},"schema":{"$ref":"#/components/schemas/Error"}}},"description":"The API is starting or the geocoder is temporarily unavailable."}},"summary":"Get coordinates for a selected suggestion","tags":["Geocoding"],"x-credit-cost":1,"x-docs-order":2,"x-docs-slug":"retrieve","x-docs-title":"Retrieve suggestion"}},"/v1/reverse":{"post":{"description":"Look up the nearest addresses from coordinates. If no house is in range, results may fall back to a street, then a nearby locality. Results are ordered nearest first.","operationId":"Reverse","parameters":[{"description":"Optional. Must be 1 when supplied.","in":"header","name":"Connect-Protocol-Version","required":false,"schema":{"enum":["1"],"type":"string"}}],"requestBody":{"content":{"application/json":{"example":{"lat":55.676,"lon":12.568,"radiusM":500,"size":1},"schema":{"$ref":"#/components/schemas/ReverseRequest"}}},"required":true},"responses":{"200":{"content":{"application/json":{"example":{"results":[{"address":{"displayName":"Example nearby address","geoCoordinates":{"lat":55.6761,"lon":12.5683}},"distanceM":22,"layer":"address"}]},"schema":{"$ref":"#/components/schemas/ReverseResponse"}}},"description":"Successful lookup. Consumes one credit."},"400":{"content":{"application/json":{"example":{"code":"invalid_argument","message":"Invalid JSON, unknown fields, unsupported Connect protocol version, oversized body, invalid query or unverifiable client address."},"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Invalid JSON, unknown fields, unsupported Connect protocol version, oversized body, invalid query or unverifiable client address."},"401":{"content":{"application/json":{"example":{"code":"unauthenticated","message":"The API key is missing, invalid or revoked."},"schema":{"$ref":"#/components/schemas/Error"}}},"description":"The API key is missing, invalid or revoked."},"404":{"content":{"application/json":{"example":{"code":"not_found","message":"The suggestion ID is unknown or belongs to an older index. Request autocomplete suggestions again."},"schema":{"$ref":"#/components/schemas/Error"}}},"description":"The suggestion ID is unknown or belongs to an older index. Request autocomplete suggestions again."},"429":{"content":{"application/json":{"example":{"code":"resource_exhausted","message":"The per-second limit was reached, a billable operation has no remaining credits, or the client IP is temporarily locked after failed API authentication. Autocomplete and regions remain available with zero credits. IP lockouts include Retry-After and also block valid keys from that IP until expiry."},"schema":{"$ref":"#/components/schemas/Error"}}},"description":"The per-second limit was reached, a billable operation has no remaining credits, or the client IP is temporarily locked after failed API authentication. Autocomplete and regions remain available with zero credits. IP lockouts include Retry-After and also block valid keys from that IP until expiry.","headers":{"Retry-After":{"description":"Seconds to wait for a per-second rate limit or temporary IP authentication lockout. Not returned for exhausted credits.","schema":{"type":"integer"}}}},"503":{"content":{"application/json":{"example":{"code":"unavailable","message":"The API is starting or the geocoder is temporarily unavailable."},"schema":{"$ref":"#/components/schemas/Error"}}},"description":"The API is starting or the geocoder is temporarily unavailable."}},"summary":"Find the addresses nearest a point","tags":["Geocoding"],"x-credit-cost":1,"x-docs-order":3,"x-docs-slug":"reverse","x-docs-title":"Reverse geocoding"}},"/v1/search":{"post":{"description":"Find coordinates and structured address components from a free-text address or place. A partial match may return goodMatch: false (or omit it). An empty object means nothing was found.","operationId":"Search","parameters":[{"description":"Optional. Must be 1 when supplied.","in":"header","name":"Connect-Protocol-Version","required":false,"schema":{"enum":["1"],"type":"string"}}],"requestBody":{"content":{"application/json":{"example":{"addressString":"10 Rue de Rivoli, 75004 Paris"},"schema":{"$ref":"#/components/schemas/SearchRequest"}}},"required":true},"responses":{"200":{"content":{"application/json":{"example":{"addressDetails":{"city":"Paris","country":"France","countryCode":"fr","houseNumber":"10","postcode":"75004","road":"Rue de Rivoli"},"displayName":"Example address","geoCoordinates":{"lat":48.855,"lon":2.36},"goodMatch":true},"schema":{"$ref":"#/components/schemas/FullAddress"}}},"description":"Successful lookup. Consumes one credit."},"400":{"content":{"application/json":{"example":{"code":"invalid_argument","message":"Invalid JSON, unknown fields, unsupported Connect protocol version, oversized body, invalid query or unverifiable client address."},"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Invalid JSON, unknown fields, unsupported Connect protocol version, oversized body, invalid query or unverifiable client address."},"401":{"content":{"application/json":{"example":{"code":"unauthenticated","message":"The API key is missing, invalid or revoked."},"schema":{"$ref":"#/components/schemas/Error"}}},"description":"The API key is missing, invalid or revoked."},"404":{"content":{"application/json":{"example":{"code":"not_found","message":"The suggestion ID is unknown or belongs to an older index. Request autocomplete suggestions again."},"schema":{"$ref":"#/components/schemas/Error"}}},"description":"The suggestion ID is unknown or belongs to an older index. Request autocomplete suggestions again."},"429":{"content":{"application/json":{"example":{"code":"resource_exhausted","message":"The per-second limit was reached, a billable operation has no remaining credits, or the client IP is temporarily locked after failed API authentication. Autocomplete and regions remain available with zero credits. IP lockouts include Retry-After and also block valid keys from that IP until expiry."},"schema":{"$ref":"#/components/schemas/Error"}}},"description":"The per-second limit was reached, a billable operation has no remaining credits, or the client IP is temporarily locked after failed API authentication. Autocomplete and regions remain available with zero credits. IP lockouts include Retry-After and also block valid keys from that IP until expiry.","headers":{"Retry-After":{"description":"Seconds to wait for a per-second rate limit or temporary IP authentication lockout. Not returned for exhausted credits.","schema":{"type":"integer"}}}},"503":{"content":{"application/json":{"example":{"code":"unavailable","message":"The API is starting or the geocoder is temporarily unavailable."},"schema":{"$ref":"#/components/schemas/Error"}}},"description":"The API is starting or the geocoder is temporarily unavailable."}},"summary":"Turn an address into coordinates","tags":["Geocoding"],"x-credit-cost":1,"x-docs-order":0,"x-docs-slug":"search","x-docs-title":"Search"}}},"security":[{"ApiKey":[]},{"BearerAuth":[]}],"servers":[{"url":"https://api.opengeocoding.com","description":"Placeholder API URL — replace with your deployed edge URL."}],"tags":[{"name":"Geocoding"},{"name":"Regions"}]}