The new DOTS Address Geocode – International service is a geocoding service that can be used to geocode addresses and places from around the world. The international geocoding service makes use of various levels of address data and Geographic Information System (GIS) data. Using various types of data allows the service to cast a wide net when searching for a place or address match.
Not all countries and areas offer the same level of data, so precise resolution will vary. Service behavior and results will also depend on the type of data being entered, so it is important to be aware of the quality of data being submitted to the geocoding service. For example, you should not expect to get an address level coordinate if you are only submitting a city name.
Before we begin, this guide is a supplement to the documentation already available in the developer guide. We highly recommend reviewing the developer guide, and reading our blog, Introduction to Address Geocode – International, before continuing.
Troubling address formats
The Address Geocode – International service was designed to handle various use cases. We understand that international addresses can come in a variety of formats:
- standardized and unstandardized
- parsed and unparsed
- single-line and multi-line
- deliverable and undeliverable
- Latin texts and special character texts, such as Chinese, Arabic or Cyrillic
Sometimes global data is collected and/or stored incorrectly, and a user is not always able to go back and fix it. It is also not uncommon for the user to not always know the quality of their data or the correct address format(s) of the countries that they have data for. This is why the inputs of the service were designed to be flexible and comprehensive but remain simple enough to easily use. Some users may find that they can perform a simple one-to-one mapping between their data and the service’s address inputs.
Calling the service
Since the Address Geocode – International service makes use of various data sources for over 250 countries, some service requests may take some time to complete. In general, most queries will take less than a second to process, and depending on your network connection, some will return as quickly as 200 milliseconds. With that said, depending on the quality of the address entered and the amount of data available for the country, a small number of queries may take one or two seconds to process.
The service has a long yet simple list of inputs. Below is a partial summary:
Required Inputs
- LicenseKey – This is the only required field. If a key is not entered then the service will return a User Input Error. If the key is invalid, then it will return an Authorization Error.
- Country – This input field is not required; however, a country value is required. This means that a country value can be passed in this field, or it can be included in the single-line address, or in one of the Address1 to Address5 fields. Do not include more than one entry for the country and do not enter the country in the Locality, AdministrativeArea or PostalCode input fields.
Submitting an address
Parsed Address (recommended) – If the address or place that you wish to geocode is already parsed then it is recommended that you map the parsed address values to their appropriate input fields. Parsed addresses are preferred as they usually indicate that the address that you wish to geocode has already been processed by validation service and that the address elements are already known. This means that there is less guesswork for the service since the Locality, Administrative Area and/or Postal Code have already been provided. This helps cut down on ambiguity and allows the service to make a more decisive match when geocoding.
- Parsed Address Example
Address1: 628 State St
Locality: Santa Barbara
AdministrativeArea: CA
PostalCode: 93101-3302
Country: USA
Multi-Line Address – If the address or place that you wish to geocode is not parsed and is broken into multiple address lines, then simply map the lines to the input fields Address1, Address2, Address3, Address4 and Address5 as needed. If you find that you have more than five address lines to input, then you likely have non-address data included, such as recipient information. Do not include non-address data, because this superfluous information will get in the way of properly geocoding the address and may yield inaccurate results. Multi-line addresses are usually addresses that have not been parsed and are in a format intended for mail delivery.
- Multi-Line Example
Address1: 628 State St
Address2: Santa Barbara, CA 93101
Address3: USA
Single-Line Address – Use the SingleLine input field and only this field if you have the complete address or place that you wish to geocode in a single line string. Do not use any other address fields, such as Address1, Address2 … Address5, Locality, AdministrativeArea and/or PostalCode when using the SingleLine field. Doing so will result in a User Input Error. The only exception is the Country field. If the SingleLIne field value does not contain a country then one can be entered in the Country field.
- Single-Line Example
SingleLine: 628 State St, Santa Barbara, CA 93101, USA
Submitting an already parsed address is recommended; however, if you are unsure which parsed value is your Locality and which is the Administrative Area or Postal Code then you may let the service try and figure it out by submitting the address in the SingleLine field, with each address element value separated by a comma.
- Unknown Parsed Address Elements Example
SingleLine: 628,State St,Santa Barbara,CA,93101,USA
Overall, submitting a single-line or multi-line address is not recommended, as it leaves room for inaccuracies when trying to find a match, but we understand that not all international address values are easily identifiable. This is why the service provides a flexible list of inputs. While parsed address values are preferred, multi-line and single-line addresses are acceptable and the service will do its best to work with these types of addresses and find a match. Please keep in mind, however, that the results may differ.
The full list of inputs for the Address Geocode – International service, with descriptions, can be found in the developer guide.
Search types
Not only does the service accept multiple address formats, it also allows the user to instruct the service on how to perform a search that best fits their needs and the type of data they have to work with.
| SearchType | Description |
| All | Instructs the service to return all possible matches. |
| BestMatch | Instructs the service to try and find the best possible match for the given place or address, allowing the service to use cascading logic to search through various levels of data. This search type is useful if you are unsure of what you are submitting. Sometimes users are unsure if they have a full address, a partial address or simply the name of a place. Use this Search Type to let the service try and figure it out for you if you are unsure. This is the default if no SearchType is given. |
| Address | Instructs the service to try and find an address level match. |
| Thoroughfare | Instructs the service to try and find a thoroughfare level match. This search type can be used to search for roads by name or to search for addresses with missing address numbers. It is usually best to not provide additional address elements, such as the address number or postal code, as they may interfere with the query. |
| Locality | Instructs the service to try and find a locality level match. This search type can be used to search for neighborhoods, towns, cities and other various localities by name. It is usually best to not provide additional address elements, such as the address number or thoroughfare, as they may interfere with the query. |
| AdminArea | Instructs the service to try and find an administrative area level match. This search type can be used to search for districts, counties, states, provinces, and other various types administrative areas. It is usually best to just provide an administrative area and country for this search type. |
| PostalCode | Instructs the service to try and find a postal code level match. It is usually best to just provide the postal code and country for this search type. |
SearchType is not a required value, and the service will default to BestMatch if a value is not provided. The full list of Search Types is available in the developer guide. Please refer to this list occasionally as new Search Types may be added in the future.
Outputs of importance
The full list of service outputs is available in the developer guide.
For every successful HTTP 200 response, you can expect to receive a SearchInfo object that contains the Status output.
- Status – It is recommended to always check the status field value first. This value will indicate if the search was successful or if there was an error in geocoding the address, or if a match was not found, or if the results are ambiguous.
- Error – An Error object will be returned in the root of the response along with the SearchInfo object if a problem was encountered trying to geocode the address or place. Please refer to the developer guide documentation on Errors.
- NumberOfLocations – It is important to be aware that the service is capable of returning multiple location matches for a single address or place. The number of locations returned will often relate to the Status of the result:
- Status OK – Often indicates that a single location was returned.
- Status MULTIPLE – Indicates that more than one location was found, and it is usually associated with the SearchType ALL. The service will perform a simple attempt to list the locations in ranked order with what it thinks is the best match listed first; however, various steps in logic are skipped when the SearchType ALL is submitted. Therefore, the first location listed may not always be the best. Depending on the search, none of the results may be accurate for what the user intended, which is why that we recommend using ALL as an exploratory search type. It may prove useful in cases where the service failed to find any matches.
- Status AMBIGUOUS – Indicates that more than one location was found. Unlike MULTIPLE, the locations for this type of result are not ranked and listed in any order, as there is not enough information available to the service to deem one location better than the other.
- Status NOTFOUND or ERROR – Indicates that no locations were returned, so do not attempt to retrieve data from the list of LocationInfo objects as it will be null.
Locations
Locations are essentially the results that the user is interested in. The Locations array will contain LocationInfo objects, which contain the following important information:
- Latitude – The latitude of the location. A decimal number up to 10 digits with a maximum precision of up to 7 places after the decimal point.
- Longitude – The longitude of the location. A decimal number up to 10 digits with a maximum precision of up to 7 places after the decimal point.
- AddressComponents – Will contain additional data about the location that is available. Most commonly it will contain address elements such as Country ISO codes, Administrative Area Names and Abbreviations, Locality names, thoroughfare name and premise number. Not all address components will be available for all locations. Location data will vary from country to country, region to region and level to level. For example, some US addresses will have US Census data available while others will not.
- Type – Also referred to as the Location Type. Used to identify what type of place the location is. For example, if the Type is ‘Address’ then it means that the coordinates will likely point to a spot in the address property. It also means that the rest of the LocationInfo data is at the address level so additional information such as address elements or even US Census elements may be available. If the Type is ‘Locality’, then address level data will not be available and the coordinates will simply point to a spot within the locality boundaries.
- PrecisionLevel – Represented as a whole number ranging from 1 to 16 to indicate how accurate the coordinates are for the location. Depending on the precision level, the coordinates may point to a building, a segment in a street or a point that is a centroid for a larger area.
For more general information about geocoding resolution levels and what these levels mean, check out this blog.
Common use cases
The two most common use cases for the Address Geocode – International service are Address and Place geocoding. However, a third use case exists aside from geocoding: many users are also interested in obtaining general location data for an area.
Geocode an address
Users who have complete addresses will often look for a set of coordinates that will point to the property or building of the given address. These types of coordinates are often referred to as “rooftop” level coordinates, as they will sometimes point to the rooftop of a building associated with the address. The geocoding service cannot always return “rooftop” level coordinates and it will instead sometimes return a set of coordinates that point to a driveway, yard, parking lot or some other location in the property. Locations with these types of coordinates will return a Precision Level of 15 or higher. Coordinates for interpolated addresses will return a Precision Level of 14.
A properly formatted and valid address with no extraneous information such as address recipient information or non-address delivery instructions will have a better chance of returning a higher precision level set of coordinates. However, high precision level coordinates are not always available for all countries and regions. Some countries have better quality data available than others, and in general urban areas tend to have better data than suburban and rural areas.
Geocode a place
Complete address data for some countries is not always easy to come by or available, and sometimes all a person has to work with is a postal code or the name of a city and region. When you know that you do not have a full address you can instruct the service to perform a geocode search that better fits your data. Use the SearchType input field to instruct the service to perform a specific type of search, such as a Locality search, Admin Area Search or Postal Code search.
When performing a place search, it is best to exclude any non-essential data. For example, if you a performing a Postal Code search then simply provide the postal code and country. Do not submit any other address information as that may interfere with the geocoding process.
Location data
In addition to obtaining a set of coordinates for an address or place, many users are interested in getting general data about the location. Any additional information about the location will be returned in the AddressComponents section of the output. This section will contain address elements such as the administrative hierarchy as well as other available data.
Not all countries and regions have the same level of data available, so not all address component fields will always contain values. Some countries will contain country-specific data, such as the US. By entering ‘census’ in the Extras input field the service will attempt to return US Census elements such as US Census tracts and block codes.
If there is a specific set of data that you are interested in obtaining for an address that is location related, then please let us know and we may add it to the service.
