Features
Forward Geocoding
Forward geocoding is the process of converting a free-text address or place to location data. To make a forward geocoding request, use the API's forward endpoint and specify your query using the query parameter. Other optional parameters are available.
Example API Request:
Sign Up to Run API Request
HTTP GET Request Parameters:
| Object | Description |
|---|---|
access_key | [Required] Your API access key, which can be found in your acccount dashboard. |
query | [Required] Specify your query as a free-text address, place name or using any other common text-based location identifier (e.g. postal code, city name, region name). |
country | [Optional] Filter geocoding results by one or multiple comma-separated 2-letter (e.g. AU) or 3-letter country codes (e.g. AUS). Example: country=AU,CA to filter by Australia and Canada.Download: Supported Countries (CSV) |
region | [Optional] Filter geocoding results by specifying a region. This could be a neighbourhood, district, city, county, state or administrative area. Example: region=Berlin to filter by locations in Berlin. |
language | [Optional] Translate specific API response objects by specifying the 2-letter (e.g. en) or the 3-letter code (e.g. eng) of your preferred language. (Default: English) |
country_module | [Optional] Set to 1 in order to enable the Country Module to include more extensive country data in your API response. Read more about this in the Country Module section. |
sun_module | [Optional] Set to 1 in order to enable the Sun Module to include astrology data in your API response. Read more about this in the Sun Module section. |
timezone_module | [Optional] Set to 1 in order to enable the Timezone Module to include timezone data in your API response. Read more about this in the Timezone Module section. |
bbox_module | [Optional] Set to 1 in order to enable the Bounding Box Module to include boundary coordinates in your API response. Read more about this in the Bounding Box Module section. |
limit | [Optional] Specify a limit between 1 and 80 to limit the number of results returned per geocoding query. Batch requests can contain multiple geocoding queries. (Default: 10 results) |
fields | [Optional] Specify one or multiple response field(s) to decrease API response size. Learn how to use this option in the Specify Response Fields section. |
output | [Optional] Specify your preferred API output format. Available values: json (default), xml and geojson. |
callback | [Optional] Use this parameter to specify a JSONP callback function name to wrap your API response in. Learn more about JSONP Callbacks. |
Example API Response:
Please note: For readability purposes we have reduced the above example API response to show only one geocoding result. To achieve the same result size, you can set the
limitparameter to1.
API Response Objects:
| Response Object | Description |
|---|---|
data | Returns two large arrays of data: request and results, explained in more detail below. |
results | Returns an array of location results for this API request. The number of sub-arrays directly depends on the value specified limit value. All sub-arrays and sub-objects are listed below. |
results > latitude | Returns the latitude coordinate associated with the location result. |
results > longitude | Returns the longitude coordinate associated with the location result. |
results > label | Returns the formatted place name or address. |
results > name | Returns the name of the location result. This could be a place name, address, postal code, and more. |
results > type | Returns the type of location result. View all location types |
results > number | Returns the street or house number associated with the location result. |
results > street | Returns the street name associated with the location result. |
results > postal_code | Returns the postal or ZIP code associated with the location result. |
results > confidence | Returns a confidence score between 0 (0% confidence) and 1 (100% confidence) associated with the location result. |
results > region | Returns the name of the region associated with the location result. |
results > region_code | Returns the region code associated with the location result. |
results > administrative_area | Returns the name of the administrative area associated with the location result. |
results > neighbourhood | Returns the name of the neighbourhood associated with the location result. |
results > country | Returns the common name of the country associated with the location result. |
results > country_code | Returns the ISO 3166 Alpha 2 (two letters) code of the country associated with the location result. |
results > map_url | Returns an embeddable map associated with the location result. |
Reverse Geocoding
Reverse geocoding is the process of converting coordinates (latitude & longitude) or an IP address to location data. To make a reverse geocoding request, use the API's reverse endpoint and specify your query using the query parameter. Other optional parameters are available.
Example API Request:
Sign Up to Run API Request
HTTP GET Request Parameters:
| Object | Description |
|---|---|
access_key | [Required] Your API access key, which can be found in your acccount dashboard. |
query | [Required] Specify your query as coordinates in the format latitude,longitude (e.g. query=40.7638435,-73.9729691) or use an IP address for automated coordinate-detection (e.g. query=72.229.28.185). |
country | [Optional] Filter geocoding results by one or multiple comma-separated 2-letter (e.g. AU) or 3-letter country codes (e.g. AUS). Example: country=AU,CA to filter by Australia and Canada.Download: Supported Countries (CSV) |
region | [Optional] Filter geocoding results by specifying a region. This could be a neighbourhood, district, city, county, state or administrative area. Example: region=Berlin to filter by locations in Berlin. |
language | [Optional] Translate specific API response objects by specifying the 2-letter (e.g. en) or the 3-letter code (e.g. eng) of your preferred language. (Default: English) |
country_module | [Optional] Set to 1 in order to enable the Country Module to include more extensive country data in your API response. Read more about this in the Country Module section. |
sun_module | [Optional] Set to 1 in order to enable the Sun Module to include astrology data in your API response. Read more about this in the Sun Module section. |
timezone_module | [Optional] Set to 1 in order to enable the Timezone Module to include timezone data in your API response. Read more about this in the Timezone Module section. |
bbox_module | [Optional] Set to 1 in order to enable the Bounding Box Module to include boundary coordinates in your API response. Read more about this in the Bounding Box Module section. |
limit | [Optional] Specify a limit between 1 and 80 to limit the number of results returned per geocoding query. Batch requests can contain multiple geocoding queries. (Default: 10 results) |
fields | [Optional] Specify one or multiple response field(s) to decrease API response size. Learn how to use this option in the Specify Response Fields section. |
output | [Optional] Specify your preferred API output format. Available values: json (default), xml and geojson. |
callback | [Optional] Use this parameter to specify a JSONP callback function name to wrap your API response in. Learn more about JSONP Callbacks. |
Example API Response:
Please note: For readability purposes, we have reduced the above example API response to show only one geocoding result. To achieve the same result size, you can set the
limitparameter to1.
API Response Objects:
| Response Object | Description |
|---|---|
data | Returns two large arrays of data: request and results, explained in more detail below. |
results | Returns an array of location results for this API request. The number of sub-arrays directly depends on the value specified limit value. All sub-arrays and sub-objects are listed below. |
results > latitude | Returns the latitude coordinate associated with the location result. |
results > longitude | Returns the longitude coordinate associated with the location result. |
results > label | Returns the formatted place name or address. |
results > name | Returns the name of the location result. This could be a place name, address, postal code, and more. |
results > type | Returns the type of location result. View all location types |
results > distance | Returns the distance (in meters) between the location result and the coordinates specified in the query parameter. Only applicable for reverse geocoding. |
results > number | Returns the street or house number associated with the location result. |
results > street | Returns the street name associated with the location result. |
results > postal_code | Returns the postal or ZIP code associated with the location result. |
results > confidence | Returns a confidence score between 0 (0% confidence) and 1 (100% confidence) associated with the location result. |
results > region | Returns the name of the region associated with the location result. |
results > region_code | Returns the region code associated with the location result. |
results > administrative_area | Returns the name of the administrative area associated with the location result. |
results > neighbourhood | Returns the name of the neighbourhood associated with the location result. |
results > country | Returns the common name of the country associated with the location result. |
results > country_code | Returns the ISO 3166 Alpha 2 (two letters) code of the country associated with the location result. |
results > map_url | Returns an embeddable map associated with the location result. |
Batch Requests
Batch requests are a way of sending multiple forward or reverse geocoding queries to the API at once. While batch requests look very similar to regular geocoding requests, they come with the requirement of an additional HTTP POST request body.
To make a batch request, simply specify your API request URL along with an additional batch request parameter sent as an HTTP POST JSON body carrying multiple queries. You can find an example request containing 3 queries below.
Example Request URL:
Sign Up to Run API Request
Example Request POST Body:
The request body below sends 3 forward geocoding queries to the API at once, looking for a street named "Main Street" across the US regions Minnesota, Illinois, and Missouri. While the query parameter is required, the other two are optional, and override potential HTTP GET counterparts specified in your API request URL.
HTTP GET Request Parameters:
To see all supported HTTP GET request parameters, please refer to the Forward Geocoding or Reverse Geocoding sections.
HTTP POST Request Parameters:
| Object | Description |
|---|---|
query | [Required] Specify an address or place name for forward geocoding, or coordinates (e.g. query=40.7638435,-73.9729691) or an IP address for reverse geocoding. |
country | [Optional] Filter geocoding results by one or multiple comma-separated 2-letter (e.g. AU) or 3-letter country codes (e.g. AUS). Example: country=AU,CA to filter by Australia and Canada. |
region | [Optional] Filter geocoding results by specifying a region. This could be a neighbourhood, district, city, county, state or administrative area. Example: region=Berlin to filter by locations in Berlin. |
Example API Response:
As you can see in the example API response below, batch requests will return one instance of the API's data array for each geocoding query sent in your POST request body. In our example, the API response has 3 instances.
Please note: For readability purposes we have reduced the above example API response to show only one geocoding result. To achieve the same result size, you can set the limit parameter to 1.
API Response Objects:
For details about API response objects, please refer to the Forward Geocoding or Reverse Geocoding sections.