Understanding How to Use DOTS Address Geocode International – Reverse Search

The DOTS Address Geocode International (AGI) service is a geocoding service that can be used to reverse geocode coordinate points from around the world. The AGI service makes use of various levels of location-based data, such as Geographic Information System (GIS) data.

Having various data sets at various levels means that a user has the flexibility to choose what type of match they want returned and not be limited to just one type of location data set. However, as powerful as the AGI service is, it is not a magic wand, and it is not without its limitations. As always, not all countries and areas offer the same level of data, and therefore precision resolution will vary. As to be expected, metropolitan and urban areas are more likely to have higher levels of data available when compared to rural and underdeveloped areas.

If you are unfamiliar with the term “reverse geocode,” or would like to learn more about reverse geocoding in general, then please read my previous article Understanding Reverse Geocoding. This article is considered supplemental material to the Reverse Search operation documentation included in the DOTS Address Geocode International developer guide, and therefore assumes that you have already reviewed it.

Reverse geocoding with the DOTS Address Geocode International Reverse Search operation

Simply put, the Reverse Search operation accepts a latitudinal and longitudinal coordinate, and will attempt to return location information representing the given point. The type of location data returned is primarily dependent on the Search Type given. For example, a Search Type of ‘Address’ will attempt to return location details down to the address/premise number if they are available and a match can be found. For non-address places such as streets, cities and postal codes, the service will return what data is available at that location’s resolution level. For more information about resolution levels and precision in geocoding in general, please read Understanding geocoding and resolution levels.

Calling the service

The Reverse Search operation can be called using HTTP GET and POST to return either an XML or JSON response output.

HTTP GET Request Help Page

JSON
https://trial.serviceobjects.com/AGI/api.svc/json/help/operations/ReverseSearch
XML
https://trial.serviceobjects.com/AGI/api.svc/xml/help/operations/ReverseSearch

HTTP POST Request Help Page

JSON
https://trial.serviceobjects.com/AGI/api.svc/json/help/operations/ReverseSearch_POST
XML
https://trial.serviceobjects.com/AGI/api.svc/xml/help/operations/ReverseSearch_POST

Required Inputs

• Latitude – The latitudinal portion of the coordinate, represented as a Decimal Degree (DD). The service accepts a decimal number up to 10 digits in length with a maximum precision of 7 places after the decimal point. Degrees-Minutes-Seconds (DMS) coordinates are not accepted.
  Example: 34.418721
• Longitude – The longitudinal portion of the coordinate, represented as a Decimal Degree (DD). The service accepts a decimal number up to 10 digits in length with a maximum precision of 7 places after the decimal point. Degrees-Minutes-Seconds (DMS) coordinates are not accepted.
  Example: -119.696215
• SearchType – The name of the type of search to perform on the given coordinates. This is primarily used to specify what location type to match against. For example, a search type value of Locality will limit the search to locality level data sets, such as cities, towns, districts, and sub-districts.
• LicenseKey – The license key assigned to you to use the service.

Please note that even though the service accepts up to 7 places after the decimal point, doing so is hardly necessary, as the level of coordinate precision past the 5^th decimal point is in most cases beyond necessary. This is because the degree of precision for most consumer level GPS devices only goes up to the 5th decimal place, which equates to “roughly” one meter of precision.

SearchTypes

The Reverse Search operation currently supports seven SearchTypes. These search types will instruct the service on how to behave.

The full list of available SearchTypes is in the developer guide. Please refer to this list occasionally as new Search Types may be added in the future.

If you are unfamiliar with the terms “thoroughfare,” “locality” and “administrative-area” then please consult the article Five commonly used terms and definitions in international address validation systems for more information.

Outputs of Importance

The full list of service outputs is available in the developer guide.

SearchInfo

For every successful HTTP 200 response you can expect to receive a SearchInfo object which 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 reverse geocoding the coordinates, or if a match was not found.
  • Status = OK – Often indicates that a single location was returned.
  • Status = MULTIPLE – Indicates that more than one location was found. Results are listed in order of distance from the given coordinate point, from closest to furthest.
  • Status = NOTFOUND – Indicates that a match was not found and no LocationInfo object was returned. If no match was found you could try again using a search type of lower precision to see if a match can be found.
  • Status = 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.

• 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/place. Please refer to the developer guide documentation on Errors.
• NumberOfLocations – It is important to be aware that the Reverse Search operation is capable of returning multiple location matches for a single coordinate query. For example, the Address and Thoroughfare SearchTypes will often return multiple matches in order of distance from the given coordinate point.

Locations

The Locations array will contain LocationInfo objects, which contain the following important information:

• Type – Also referred to as the Location Type. This is 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 property. It also means that the rest of the LocationInfo data is at the address level, so additional information such as the premise number and thoroughfare may be available. In general, the higher the precision level of the location type, the more location information that will be available.
• PrecisionLevel – Represented as a whole number ranging from 1 to 16 to indicate how accurate the coordinates are for the location. The higher the number, the higher the level of precision. Depending on the precision level, the data and coordinates may relate to a building, a segment in a street or a point that is a centroid for a larger area.
• 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 – This 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 names and premise numbers. 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.

AddressComponents

Values returned in the AddressComponents provide information about the location that matched the query. The data of importance will generally relate to the search type used in your query. For example, if you used Address as your search type then address information such as the premise number and thoroughfare name will likely be of importance to you, but if you used Locality as your search type then perhaps just the name and the administrative area are what you are looking for. In general, the following components are useful regardless of type.

• Name – The name of the location. For example, if the location type is Locality, then this would be the place’s name, such as the name of a city, town, or neighborhood. If the location type is Thoroughfare, then the name will represent the name of the street, road, highway, or other type of thoroughfare.
• FullName – The full name of the location. This value can sometimes be used as a description for the place, as it will contain key location information in a single string. For example, if the location type is Address then the full name will often appear as a single-line formatted address. If the location type is Locality, then it will return the names of the locality, any related parent localities, and admin-areas.
• DistanceKilometers – The distance of the location from the given coordinates in kilometers. When multiple matches are found the locations are ordered with the locations of closest distance listed first.
• URLs – BingMapsURL, GoogleMapsURL, MapQuestURL are components that return URLs of the location in Bing Maps, Google Maps and MapQuest. These URLs can be useful if you don’t have your own mapping system to plot the coordinates of the location and would instead like to use one of the popular online mapping systems.

For a complete list of LocationInfo components and their descriptions please refer to the LocationInfo table in the developer guide.

Address component availability is dependent on data availability; however, if there is a relevant data point of interest that we do not offer on any of the data levels, please feel free to let us know and we can look into adding it into the service.