Global Geocoding
The Global Geocoding API takes an input of one or more address strings and returns latitude and longitudes for the given locations. It can also be used for reverse geocoding, returning addresses that are close to a given set of latitude and longitude co-ordinates.
When reverse geocoding, multiple addresses will be returned if possible (with a maximum of 5). This is because, particularly in urban areas, it can be difficult to identify the specific property associated with a set of co-ordinates.
Please note that whilst the API can accept an input of multiple addresses/co-ordinates, response times will be quicker if only one is sent at a time.
For the UK, only the first address/co-ordinate in the string will be parsed (i.e. only one geocoding/reverse geocoding result will be provided).
If sending multiple addresses/co-ordinates, limiting these to one country will also improve performance.
The Global Geocoding API supports most international locations. For a full list of coverage please see https://support.loqate.com/coverage-full/.
This method will consume credit. You will be charged per address geocoded.
Base URL
https:// api.addressy.com/LocationServices/Geocoding/Global/v1.00/
Note: we don't support API connections using HTTP - all calls should use HTTPS.
JSON
https://api.addressy.com/LocationServices/Geocoding/Global/v1.00/json4.ws
Note: A REST endpoint with a JSON payload is the only call style supported.
Request parameters
Each request to the web service requires a number of parameters, all of which are listed below. All requests require a key which can be generated in your account.
Note: where potentially sensitive data is used in these parameters, remember to make the request as secure as possible (see the API Security page for more information).
* = required field
| Name | Type | Example values | Description |
|---|---|---|---|
| Key* | String | AA11-AA11-AA11-AA11 | The Loqate key used to authenticate with the service. |
| Input* | Array of Strings | ["52.369180,-2.24545", "3 Harlech Way Kidderminster"] | An array of strings containing either location co-ordinates and/or unstructured addresses. This array can contain up to 10 items. |
| Country | String | GBR | ISO2 or ISO3 country code (e.g. GB or GBR). This will limit the geocoding lookup to the specified country, but will improve performance. This parameter is not required for reverse geocoding requests. |
Response Fields
The response from the web service is a table with the specification below. Where no items are found, the response will be empty (although all endpoints specify the columns). If an error occurs, the response will not follow this format. Instead the response will be an error table.
| Name | Type | Example values | Description |
|---|---|---|---|
| Input | Array of Strings | ["52.369180,-2.24545", "3 Harlech Way Kidderminster GB"] | An array of strings containing the input from the original request. |
| Results | Array of Strings |
{ |
An array of strings containing the results of your geocoding request. |
Results Fields
Further information on the fields contained within the results array.
| Name | Type | Example values | Description |
|---|---|---|---|
| Premise | String | 3 | This field contains the alphanumeric code identifying an individual location, should one exist. |
| Thoroughfare | String |
Kenilworth Drive
|
This field holds the most common street or block data element within a country. |
| Locality | String | Kidderminster | This field holds the most common population center data element within a country. |
| AdministrativeArea | String | Worcestershire | This field holds the most common geographic data element within a country. |
| PostCode | String | B71 3JA | This field contains the complete postal code, should such information be able to be determined. |
| Country | String | GB | This field holds the ISO2 country code. |
| Latitude | String | 52.369171 | This field holds the WGS 84 latitude in decimal degrees format. |
| Longitude | String | -2.245479 | This field holds the WGS 84 longitude in decimal degrees format. |
| GeoDistance | String | 2.267699 | This field holds the radius of accuracy in meters, giving an indication of the likely maximum distance between the geocode and the physical location. Please note that this field is derived from and therefore dependent on the accuracy and coverage of the underlying reference data. |
| GeoAccuracy | String | P4 | This field is made up of the geocoding status and geocoding level. For more information on this please see the section below. When looking for a geocoding result it's important to look for this field, as if we return U0 it means we have been unable to geocode that input. |
| LocationType | String | DeliveryPoint, Premise, Thoroughfare, Locality, PostalCode, AdministrativeArea, None |
This field identifies the level we have validated a given address or co-ordinates to. E.g. if we cannot identify a premise number we may only validate to Thoroughfare level. |
GeoAccuracy Description
The GeoAccuracy code is made up of the following values:
- The geocoding Status
- The geocoding Level
e.g. I4, A2, P4
Geocoding Status
- P: Point - a single geocode was found matching the input address
- I: Interpolated - a geocode was able to be interpolated from the input addresses location in a range
- A: Average - multiple candidate geocodes were found to match the input address, and an average of these was returned
- U: Unable to geocode - a geocode was not able to be generated for the input address
Geocoding Level
- 4: Premise (Premise or Building)
- 3: Thoroughfare
- 2: Locality
- 1: AdministrativeArea
- 0: None
Errors
Below are the errors which are specific to this web service. If an error occurs, an error table like the one below will be returned. To check for an error response, test for a 4-column table with columns "Error", "Description", "Cause" and "Resolution" containing a single row.
For a list of errors applicable to all APIs, have a look at the list of common errors.
| Number | Description | Cause | Resolution |
|---|---|---|---|
| 1001 | InputRequired | Input value not provided. | Check that you have provided a valid input(s) and try again. |
| 1002 | ProviderFailure | Internal Server Error. | Internal Server Error. Please try again later. |
Examples
The examples below show requests to the API and the corresponding responses.
Example Geocoding Request
POST https:// api.addressy.com/LocationServices/Geocoding/Global/v1.00/json4.ws
Content-Type: application/json
{
"key" : "AA11-AA11-AA11-AA11",
"input" : ["Waterside, Basin Rd, Worcester, WR5 3DA", "The Foundation, Herons Way, Chester Business Park, Chester, CH4 9GB", "128 Queen Victoria Street, London, EC4V 4BJ" ]
"country" : "GBR"
}
Example Response
{
"Items": [
{
"Input": "Waterside, Basin Rd, Worcester, WR5 3DA, GB",
"Results": [
{
"Thoroughfare": "Basin Road",
"Locality": "Worcester",
"AdministrativeArea": "Worcestershire",
"Country": "GB",
"Latitude": "52.182747",
"Longitude": "-2.222145",
"GeoDistance": "0.0",
"LocationType": "Premise"
}
]
},
{
"Input": "The Foundation, Herons Way, Chester Business Park, Chester, CH4 9GB, GB",
"Results": [
{
"Thoroughfare": "Herons Way",
"Locality": "Chester",
"AdministrativeArea": "Cheshire",
"Country": "GB",
"Latitude": "53.161261",
"Longitude": "-2.906420",
"GeoDistance": "0.0",
"LocationType": "Premise"
}
]
},
{
"Input": "128 Queen Victoria Street, London, EC4V 4BJ, GB",
"Results": [
{
"Premise": "128",
"Thoroughfare": "Queen Victoria Street",
"Locality": "London",
"AdministrativeArea": "London",
"Country": "GB",
"Latitude": "51.512050",
"Longitude": "-0.097604",
"GeoDistance": "26.9",
"LocationType": "Premise"
}
]
}
]
}
Example Reverse Geocoding Request
POST https:// api.addressy.com/LocationServices/Geocoding/Global/v1.00/json4.ws
Content-Type: application/json
{
"key" : "AA11-AA11-AA11-AA11",
"input" : ["52.182747,-2.222145", "53.161261, -2.906420", "51.512050, -0.097604"]
}
Example Response
{
"Items": [
{
"Input": "52.182747,-2.222145",
"Results": [
{
"Thoroughfare": "Basin Road",
"Locality": "Worcester",
"AdministrativeArea": "Worcestershire",
"Country": "GB",
"Latitude": "52.182747",
"Longitude": "-2.222145",
"GeoDistance": "0.013651",
"LocationType": "None"
},
{
"Premise": "22",
"Thoroughfare": "Basin Road",
"Locality": "Worcester",
"AdministrativeArea": "Worcestershire",
"Country": "GB",
"Latitude": "52.182562",
"Longitude": "-2.221917",
"GeoDistance": "25.462199",
"LocationType": "None"
},
{
"Premise": "24",
"Thoroughfare": "Basin Road",
"Locality": "Worcester",
"AdministrativeArea": "Worcestershire",
"Country": "GB",
"Latitude": "52.182536",
"Longitude": "-2.221981",
"GeoDistance": "25.716314",
"LocationType": "None"
},
{
"Premise": "20",
"Thoroughfare": "Basin Road",
"Locality": "Worcester",
"AdministrativeArea": "Worcestershire",
"Country": "GB",
"Latitude": "52.182585",
"Longitude": "-2.221854",
"GeoDistance": "26.413655",
"LocationType": "None"
},
{
"Premise": "26",
"Thoroughfare": "Basin Road",
"Locality": "Worcester",
"AdministrativeArea": "Worcestershire",
"Country": "GB",
"Latitude": "52.182511",
"Longitude": "-2.222045",
"GeoDistance": "26.920126",
"LocationType": "None"
}
]
},
{
"Input": "53.161261, -2.906420",
"Results": [
{
"Thoroughfare": "Herons Way",
"Locality": "Chester",
"AdministrativeArea": "Cheshire",
"Country": "GB",
"Latitude": "53.161261",
"Longitude": "-2.906420",
"GeoDistance": "0.000000",
"LocationType": "None"
},
{
"Thoroughfare": "Herons Way",
"Locality": "Chester",
"AdministrativeArea": "Cheshire",
"Country": "GB",
"Latitude": "53.161261",
"Longitude": "-2.906420",
"GeoDistance": "0.012753",
"LocationType": "None"
},
{
"Thoroughfare": "Lakewood",
"Locality": "Chester",
"AdministrativeArea": "Cheshire",
"Country": "GB",
"Latitude": "53.159502",
"Longitude": "-2.906114",
"GeoDistance": "196.264215",
"LocationType": "None"
},
{
"Thoroughfare": "Wrexham Road",
"Locality": "Chester",
"AdministrativeArea": "Cheshire",
"Country": "GB",
"Latitude": "53.162955",
"Longitude": "-2.908206",
"GeoDistance": "219.094583",
"LocationType": "None"
},
{
"Thoroughfare": "Wrexham Road",
"Locality": "Chester",
"AdministrativeArea": "Cheshire",
"Country": "GB",
"Latitude": "53.162955",
"Longitude": "-2.908206",
"GeoDistance": "219.094583",
"LocationType": "None"
}
]
},
{
"Input": "51.512050, -0.097604",
"Results": [
{
"Premise": "155",
"Thoroughfare": "Queen Victoria Street",
"Locality": "London",
"AdministrativeArea": "London",
"Country": "GB",
"Latitude": "51.512056",
"Longitude": "-0.097605",
"GeoDistance": "0.653191",
"LocationType": "None"
},
{
"Premise": "128",
"Thoroughfare": "Queen Victoria Street",
"Locality": "London",
"AdministrativeArea": "London",
"Country": "GB",
"Latitude": "51.512033",
"Longitude": "-0.097648",
"GeoDistance": "3.578615",
"LocationType": "None"
},
{
"Premise": "128",
"Thoroughfare": "Queen Victoria Street",
"Locality": "London",
"AdministrativeArea": "London",
"Country": "GB",
"Latitude": "51.512097",
"Longitude": "-0.097703",
"GeoDistance": "8.566401",
"LocationType": "None"
},
{
"Premise": "128",
"Thoroughfare": "Queen Victoria Street",
"Locality": "London",
"AdministrativeArea": "London",
"Country": "GB",
"Latitude": "51.512038",
"Longitude": "-0.097431",
"GeoDistance": "12.048529",
"LocationType": "None"
},
{
"Premise": "126",
"Thoroughfare": "Queen Victoria Street",
"Locality": "London",
"AdministrativeArea": "London",
"Country": "GB",
"Latitude": "51.512038",
"Longitude": "-0.097431",
"GeoDistance": "12.057832",
"LocationType": "None"
}
]
}
]
}
Use of geocodes/addresses
Use of the output of the Global Geocoding API is temporary, and only for use as part of a Store Finder. It is not permitted to index or store results for other purposes, such as use in a checkout process. For further information please see Loqate Terms and Conditions.