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:
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.
If the 'address' field is set it always takes precedence.
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
street
no
string
The street/road name to locate
city
no
string
The city/town name to locate
county
no
string
The county/region name to locate
state
no
string
The state name to locate
postal-code
no
string
The postal code to locate
country-code
no
string
Limit result to this country (the default is no country bias)
language-code
no
string
en
The language to display results in, available languages are:
de, en, es, fr, it, pt, ru, zh
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 recommended for processing user input or implementing auto-complete. We use a combination of approximate string matching and data cleansing to find possible location matches
API Response
Parameter
Type
Description
found
integer
The number of possible matching locations found
locations
array
Array of matching location objects:
Parameter
Type
Description
latitude
float
The location latitude
longitude
float
The location longitude
address
string
The complete address using comma-separated values
address-components
map
The components which make up the address such as road, city, state, etc
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
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
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
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)
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]