Reverse Geocode POST Request

The POST request enables you to submit a single input coordinate or a list of coordinates for batch processing. A country code, coordinate reference system and matching preferences can optionally be specified. A response containing a list of candidates with associated address data and matching information is returned. The preference options for a POST request are the complete set of available options.

Base URI

http://<server>:<port>/<contextpath>/rest/GeocodeService/reverseGeocode
[.content type]
http://<server>:<port>/rest/GlobalGeocode/reverseGeocode[.content type]

where:

[.content type] indicates that the specified content type will be used by default. Optional.
json
Default content type is JSON, unless superseded by HTTP content negotiation
xml
Default content type is XML, unless superseded by HTTP content negotiation

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.
Name Type Description
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 a 3-letter ISO country code. Optional. For country codes, see ISO 3166-1 Country Codes.
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 ]
type String Indicates the type of geographic entity the input coordinates represent.
point
The input coordinates represent a point location.
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.
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.
distance Double Sets the radius in which the Reverse Geocode service searches for a match to the input coordinates. The unit of measurement is specified using distanceUnits. Default = 150 meters. Maximum value = 5280 feet (1 mile ) or 1609 meters.
distanceUnits String Specifies the unit of measurement for the search distance. One of the following:
  • Feet
  • Meters - Default
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-EN) or arabic-first (ar-EG).

Note: For a listing of ISO Alpha-2 country codes, see ISO 3166-1 Country Codes.

POST: 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.
streetOffset Double The offset distance from the street segments. The distance is in the units you specify in the streetOffsetUnits preference. 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.

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.
streetOffsetUnits String Unit of measurement for the street offset. One of the following: Feet, Meters (default).
cornerOffset Double Distance to offset the street end points in street-level matching. The distance is in the units you specify in the cornerOffsetUnits preference. This value is used to prevent addresses at street corners from being given the same geocode as the intersection. Defines the offset position of the geocoded point with respect to the corner. Default value = 7 meters.

The following diagram compares the end points of a street to offset end points.
cornerOffsetUnits String Unit of measurement for the street offset. One of the following: Feet, Meters (default).
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. For example, in an XML request, an entry for a country override would look as follows: 
<customPreferences>
   <entry>
      <key>CAN.distance</key>
      <value>300</value>
   </entry>
</customPreferences>
Custom country input options are available for the following countries: In addition, for countries that support both custom user dictionaries and standard geocoding datasets, you can set a custom preference with the key KEY_CUSTOM_DICTIONARY_USAGE that will define the searching and matching preferences when both custom and standard dictionaries are available in the geocoding engine. This option is only available with forward geocoding. For more information, see Setting Searching and Matching Preferences When Using Standard and Custom Dictionaries. To locate information on whether your country supports custom user dictionaries, refer to the "Supported Geocoding Datasets" section in the country's write-up.