Geocode an address, partial address or just the name of a place.
Address geocoding is the process of taking a string and attempting to match this with possible real world locations.
This is the opposite process of reverse geocoding.
Once a location is found you can then retrieve the geographic coordinates as latitude and longitude.
If more than one location is found for a given string then results are ordered by most relevant to the original search address and with the highest geographic accuracy.
Use this API to:
Display geocoded locations on a map component
Validate postal addresses
Search for postal codes
Extract address components like city, state and country details
Implement auto-complete for address inputs
Fuzzy search for the nearest locations from partial or misspelled addresses
Note on address formatting:
This API accepts both structured and unstructured addresses.
To geocode a structured address set the fields: 'house-number', 'street', 'city', etc.
To geocode an unstructured address just set the 'address' field,
commas may be used to separate the various addresses components and can help improve geocoding accuracy.
If the 'address' field is set it always takes precedence over any structured address fields.
The full address, partial address or name of a place to try and locate. Comma separated address components are preferred.
house-number
no
string
The house/building number to locate (for structured address searches)
street
no
string
The street/road name to locate (for structured address searches)
city
no
string
The city/town name to locate (for structured address searches)
county
no
string
The county/region name to locate (for structured address searches)
state
no
string
The state name to locate (for structured address searches)
postal-code
no
string
The postal code to locate (for structured address searches)
country-code
no
string
Prefer results from this country code (the default is no country bias)
country-codes
no
string
Prefer results from this list of country codes (space or comma separated values). Preference is in the order supplied, you can use the 'country-code' parameter to also set a dynamic or user supplied country code which takes precedence
language-code
no
string
en
The language to display results in, available languages are:
ar, de, en, es, fr, it, ja, nl, pt, ru, zh
auto-complete
no
boolean
false
Enable auto-complete for search-as-you-type and search suggestions. This option can find addresses based on partial search terms, combine with 'country-code' for country specific searches. Auto-complete works best with 'fuzzy-search' disabled for the fastest response times but can be combined if required
fuzzy-search
no
boolean
false
If no matches are found for the given address, start performing a recursive fuzzy search until a geolocation is found. This option is useful for processing user supplied input that may be incomplete or have typos and where you do not mind some potential loss in precision
limit
no
integer
8
Limit search results to this many locations (between 1 and a maximum of 32)
The full address string using comma-separated values, use 'postal-address' for the address string formatted using country/region specific rules
address-structured
map
The structured address components:
Parameter
Type
Description
name
string
The name of the person or organization
number
string
The house or building number
street
string
The name of the street/road
area
string
The name of the local area. Also known as: suburb/neighborhood/locality/subdivision
city
string
The name of the city/town/village
county
string
The name of the county. Also known as: district/municipality/province
state
string
The name of the state/region
postal-code
string
The postal code
country
string
The name of the country
address-components
map
The components which make up the address such as road, city, state, etc. These are country/region specific values, use 'address-structured' for a strict address structure which is the same for all locations globally
city
string
The city of the location
state
string
The state of the location
region-code
string
The ISO 3166-2 region code for the location
language-code
string
The ISO 2-letter language code for the official language spoken in the country
country
string
The country of the location
country-code
string
The ISO 2-letter country code of the location
country-code3
string
The ISO 3-letter country code of the location
currency-code
string
ISO 4217 currency code associated with the country
postal-code
string
The postal code for the location
postal-address
string
The formatted address using local standards suitable for printing on an envelope
location-type
string
The detected location type ordered roughly from most to least precise, possible values are:
address - indicates a precise street address
street - accurate to the street level but may not point to the exact location of the house/building number
city - accurate to the city level, this includes villages, towns, suburbs, etc
postal-code - indicates a postal code area (no house or street information present)
railway - location is part of a rail network such as a station or railway track
natural - indicates a natural feature, for example a mountain peak or a waterway
island - location is an island or archipelago
administrative - indicates an administrative boundary such as a country, state or province
building-type
string
The detected building type for the address, possible values are:
none - no building type was detected for this location
house - a residential house/property
apartment - a residential apartment complex
office - a commercial/business office
accommodation - a hotel/motel or other type of accommodation
education - a school or university
food - a restaurant or place where food can be purchased
shop - a shop selling any type of goods
attraction - an attraction such as theme parks or tourist activities
medical - a hospital or other medical facility
transport - a transportation building such as a bus or train depot
commercial - a commercial/industrial building
government - a government or military facility
public - a public building such as a townhall or community centre
location-tags
array
Array of strings containing any location tags associated with the address. Tags are additional pieces of metadata about a specific location, there are thousands of different tags. Some examples of tags: shop, office, cafe, bank, pub
location-profile
map
Map containing any external metadata linked to the location. Currently supports the following values which are only set if known: website-url, phone-number, org-name, wikipedia-title, wikidata-entity
timezone
map
Map containing timezone details for the location:
Parameter
Type
Description
id
string
The time zone ID as per the IANA time zone database (tzdata). If empty then no valid timezone was detected
name
string
The full time zone name
abbr
string
The time zone abbreviation
date
string
The current date at the time zone (ISO 8601 format 'YYYY-MM-DD')
time
string
The current time at the time zone (ISO 8601 format 'hh:mm:ss.sss')
offset
string
The UTC offset for the time zone (ISO 8601 format '±hh:mm')
API Performance
Characteristic
Value
Description
Avg Latency
80ms
Average RTT for requests within the same data center/region
Max Rate
6/second
Maximum inbound request rate. Exceeding this will result in request throttling
Max Concurrency
30
Maximum concurrent/simultaneous requests. Exceeding this will result in error code 06 [TOO MANY CONNECTIONS]