Request Parameters

The POST request comprises the following input parameters:
  • points — The input coordinates or multiple input coordinates to be reverse geocoded. Required.
  • preferences — The matching options. Optional.
These objects and their elements are defined in the following table.
Parameter Name Description Usage
points an array object containing both a geometry object and a country code string:
country (String) Indicates the country to search for the reverse geocode result, specified using an ISO country code or country name. For country codes, see Geocode Premium: Country Reference Listing and ISO 3166-1 Country Codes. Optional
geometry object, consisting of the following elements:
coordinates (Double) Specifies the x, y input coordinates, where x=longitude and y=latitude. For example: [ -105.25175, 40.024494 ] Required
type (String) Indicates the type of geographic entity the input coordinates represent.
point
The input coordinates represent a point location.
 Optional
crs (String) Indicates the coordinate reference system used for the input coordinates. The format must be the European Petroleum Survey Group (EPSG) code or the SRID code. Default = EPSG:4326. Specify the coordinate reference system in the format codespace:code. Optional
preferences object, consisting of the following elements.
Note: Only the following elements in the preferences object are applicable to the Reverse Geocode service.
Note: To override the default value of a preferences element for a specific country, specify the key/value pair in the customPreferences object, with the key constant preceded by the ISO-3166 3-character country code plus period. For example: DEU.streetOffset.
fallbackToGeographic Specifies whether to attempt to determine a geographic region centroid when an address-level reverse geocode cannot be determined.
True
Return a geographic centroid when an address-level centroid cannot be determined. Default.
False
Do not return a geographic centroid when an address-level centroid cannot be determined.
 Optional
fallbackToPostal Specifies whether to attempt to determine a post code centroid when an address-level reverse geocode cannot be determined.
True
Return a post code centroid when an address-level centroid cannot be determined. Default.
False
Do not return a post code centroid when an address-level centroid cannot be determined.
Optional
FALLBACK_TO_WORLD StringSpecifies whether to use the World Geocoder (XWG) to determine a reverse geocode when either a country geocoder is not installed or a country geocoder is installed without a Geocode dataset. The World Geocoder (XWG) may return either a postal or geographic reverse geocode depending on the level of support in the XWG Geocode dataset.
True
Use the World Geocoder (XWG) for matching when either a country geocoder is not installed or a country geocoder is installed without a Geocode dataset. Default.
False
Do not use the World Geocoder (XWG) for matching when either a country geocoder is not installed or a country geocoder is installed without a Geocode dataset.
Optional
clientLocale (String) This field is used for a country that has multiple languages to determine the preferred order of language candidates. The locale must be specified in the format "cc_CC", where "cc" is the language and "CC" is the ISO 3166-1 Alpha-2 code, such as: en_US, fr_CA or fr_FR.

For example, Egypt supports both english and arabic. The clientLocale field could be set to either english-first (en-EG) or arabic-first (ar-EG).

Note: For a listing of ISO Alpha-2 country codes, see Geocode Premium: Country Reference Listing and ISO 3166-1 Country Codes.
 Optional
clientCoordSysName (String) Specifies the coordinate system that you want to convert the geometry to. The format must be the European Petroleum Survey Group (EPSG) code or the SRID code. Default = EPSG:4326.

Specify the coordinate reference system in the format codespace:code.

 Optional
streetOffset (Double) Indicates the offset distance from the street segments to use in street-level geocoding. The distance is specified in the units you specify in the streetOffsetUnits option. Default value = 7 meters.

The offset distance is used in street-level geocoding to prevent the geocode from being in the middle of a street. It compensates for the fact that street-level geocoding returns a latitude and longitude point in the center of the street where the address is located. Since the building represented by an address is not on the street itself, you do not want the geocode for an address to be a point on the street. Instead, you want the geocode to represent the location of the building which sits next to the street. For example, an offset of 50 feet means that the geocode will represent a point 50 feet back from the center of the street. The distance is calculated perpendicular to the portion of the street segment for the address. Offset is also used to prevent addresses across the street from each other from being given the same point. The following diagram shows an offset point in relation to the original point.

 Optional
customPreferences (Map<String key, String value>) Specifies the country-specific input preferences. This object can be used to specify:
  • A country override to a default value of one or more elements in the preferences or returnFieldsDescriptor objects.
  • A custom country input option.

To override the default value for a specific country, precede the key constant with the ISO-3 country code plus period, and then specify the value.

Custom country input options are available for the following countries: 		Optional
returnFieldsDescriptor object of type ReturnsFieldsDescriptor. Controls the return of additional data on a candidate. By default, the extended candidate information is not returned, but in the cases where more is available, it can be controlled in the following ways:
Note: To override the default value of a returnFieldsDescriptor element for a specific country, specify the key/value pair in the customPreferences object, with the key constant preceded by the ISO-3166 3-character country code plus a period. For example: "AUS.returnAllCustomFields".
returnAllCustomFields (Boolean)
True
Return all of the custom fields for the candidate.
False
Return only the standard set of fields for the candidate. Default.
 Optional
returnedCustomFieldKeys (List<String>) Specifies a list of keys that represent the custom fields to be returned in the candidate's customFields output. For example: “CTYST_KEY” or “DATATYPE”. Default: empty.
Note: To specify multiple key/value pairs for a country, use spaces to separate the names of the custom fields to be returned. For example: "USA.returnedCustomFieldKeys" : "LAT LON SHORT_CITY". Candidates which have this information available will include the three custom fields with these keys in the candidate's customFields output.
Note: Custom fields vary by country. To locate your country's information, refer to Country-Specific Information to find the corresponding section in the appendix that provides more details.
 Optional
returnMatchDescriptor (Boolean)
True
Return the match descriptor object, which indicates the parts of the candidate that matched the input address.
False
Do not return the match descriptor object. Default.
Optional
returnStreetAddressFields (Boolean)
True
Return all of the individual street fields that make up the formattedStreetAddress field separately, as follows:
  • MAIN_ADDRESS — the base part of the street name. For example: “River” in “13 River Ave”
  • THOROUGHFARE_TYPE — the thouroughfare type, which may appear before or after the street name, such as Ave, Via, St, Rd, etc.
  • ADDRESS_ID — the unique identifier for the address in the source data
  • PRE_ADDRESS — value may contain articles, etc. that appear before the main street name. For example: “de la” from “Calle de la mesa”
  • POST_ADDRESS — value may contain phrases that appear after the main street name. For example: “de la tiedra” from “Calle Ramon Perez de la tiedra”
  • PRE_DIRECTIONAL — value contains a directional that appears before the main street name. For example: “South” in “123 South Main St”
  • POST_DIRECTIONAL — value contains a directional that appears after the main street name. For example: “SW” in “123 River St SW”
False
Do not return the individual street fields separately; return these values in the formattedStreetAddress field. Default.
 Optional
returnUnitInformation (Boolean)
True
Where available, return unit type and unit value information separately in the unitType and unitValue fields, as well as in the formattedStreetAddress field.
False
Where available, return unit type and unit value information only in the formattedStreetAddress field. Default.
 Optional