API reference

Search

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.

Runnable examples: Node.js geocoding guide → Python guide →

1 credit per successful call · Authentication and account rate limit apply.

POST GET /v1/search

Request body

application/json · Up to 64 KiB. Unknown fields are rejected. Send your key in x-api-key. With GET, send the same fields as URL query parameters instead; nested fields use dots, such as focus.lat. Unknown or repeated parameters return 400. The key still goes in a header.

addressString string required

Free-text address or place. Trimmed before searching; cannot be blank.

Up to 500 characters.

Response 200

Default scalar values and empty lists may be omitted. Treat absent lists as empty and absent scalars as their protobuf defaults.

addressDetails AddressDetails
Nested fields
- aerialway string
- aeroway string
- allotments string
- amenity string
- borough string
- boundary string
- bridge string
- city string
- cityBlock string
- cityDistrict string
- club string
- commercial string
- continent string
- country string
- countryCode string
- county string
- craft string
- croft string
- district string
- emergency string
- farm string
- farmyard string
- hamlet string
- highway string
- historic string
- houseName string
- houseNumber string
- industrial string
- isolatedDwelling string
- landuse string
- leisure string
- manMade string
- military string
- mountainPass string
- municipality string
- natural string
- neighbourhood string
- office string
- place string
- postcode string
- province string
- quarter string
- railway string
- region string
- regionCodes ISO3166_2[]
  
  ISO 3166-2 codes for the address.
  Nested fields
  
  adminLevel integer
  
  Administrative level.
  
  Range: 0–4294967295.
  
  code string
  
  ISO 3166-2 region code.
- regions Region[]
  
  Administrative regions for the address.
  Nested fields
  
  adminCode string
  
  ISO 3166-2 administrative region code.
  
  adminLevel integer
  
  Administrative level.
  
  Range: 0–4294967295.
  
  countryCode string
  
  ISO 3166-1 alpha-2 country code.
  
  countryName string
  
  Country name.
  
  enName string
  
  English region name.
  
  localName string
  
  Local region name.
  
  parentAdminCode string
  
  Parent administrative region code, when available.
- residential string
- retail string
- road string
- shop string
- state string
- stateDistrict string
- subdivision string
- suburb string
- tourism string
- town string
- tunnel string
- village string
- waterway string
displayName string

Human-readable address or place name.
geoCoordinates GeoCoordinates
Nested fields
- boundingBox BoundingBox
  Nested fields
  
  maxLat number
  
  Northern latitude in degrees.
  
  maxLon number
  
  Eastern longitude in degrees.
  
  minLat number
  
  Southern latitude in degrees.
  
  minLon number
  
  Western longitude in degrees.
- lat number
  
  Latitude in degrees, from -90 to 90. Omission uses the protobuf default of 0.
- lon number
  
  Longitude in degrees, from -180 to 180. Omission uses the protobuf default of 0.
goodMatch boolean

True for a good match. False or omitted for a partial match, such as a street without the requested house number.

Errors

HTTP	Code	Meaning
400	invalid_argument	Invalid JSON, unknown fields, unknown or repeated query parameters, unsupported Connect protocol version, oversized body, invalid query or unverifiable client address.
401	unauthenticated	The API key is missing, invalid, expired or revoked.
403	permission_denied	A browser key was used without an Origin header, from an origin not in its allowed list, or over gRPC.
404	not_found	The suggestion ID is unknown or belongs to an older index. Request autocomplete suggestions again.
429	resource_exhausted	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.
503	unavailable	The API is starting or the geocoder is temporarily unavailable.

Error handling and retries →