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.

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

POST/v1/search

Request body

application/json · Up to 64 KiB. Unknown fields are rejected. Send your key in x-api-key.

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, unsupported Connect protocol version, oversized body, invalid query or unverifiable client address.
401	unauthenticated	The API key is missing, invalid or revoked.
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 →