reverseGeocode

The reverseGeocode operation determines the address at a particular x/y location. You pass the coordinates of a point location to the geocoding service, and the service returns the address that is closest to the location.

reverseGeocode

Request URL

http://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer/reverseGeocode?<PARAMETERS>

Request parameters

The parameters for reverseGeocode are listed in the subsections that follow, categorized by required and optional parameters.

Required parameters

location

The point from which to search for the closest address. The point can be represented as a simple, comma-separated syntax or as a JSON point object.

The spatial reference of the comma-separated syntax is always WGS84 (in decimal degrees), the same coordinate system as the World Geocoding Service.

Use JSON formatting to specify any other coordinate system for the input location. Specifically, set the spatial reference using its well-known ID (WKID) value. For a list of valid WKID values, see Projected Coordinate Systems and Geographic Coordinate Systems.

Example using simple syntax and the default WGS84 spatial reference:
location=103.8767227,1.3330736
Example using JSON and the default WGS84 spatial reference:
location={x: 103.876722, y: 1.3330736}
Example using JSON and specifying a spatial reference (WGS84 Web Mercator Auxiliary Sphere):
location=
{
    "x": 11563503,
    "y": 148410,
    "spatialReference": {
        "wkid": 3857
    }
}

f

The service supports responses in JSON or PJSON format. You can specify the response format using the f parameter. This is a required parameter.

Example:
f=json

token

The token parameter may or may not be required; read about free vs. paid operations to learn when it is required.

Use this parameter to specify a token that provides the identity of a user who has the needed permissions to access the service.

The authentication topic provides more information on how to generate an access token.

Example (replace <YOUR TOKEN> with a valid token):
token=<YOUR TOKEN>

Optional parameters

distance

The optional distance parameter allows you to specify a radial distance in meters to search for an address from the specified location. If no distance value is specified, the value is assumed to be 100 meters.

Example:
distance=50

outSR

The spatial reference of the x/y coordinates returned by a geocode request. This is useful for applications using a map with a spatial reference different than that of the geocode service.

The spatial reference can be specified as either a well-known ID (WKID) or as a JSON spatial reference object. If outSR is not specified, the spatial reference of the output locations is the same as that of the service. The World Geocoding Service spatial reference is WGS84 (WKID = 4326).

For a list of valid WKID values, see Projected Coordinate Systems and Geographic Coordinate Systems.

Example (102100 is the WKID for the Web Mercator projection):
outSR=102100

langCode

Sets the language in which reverse-geocoded addresses are returned. Addresses in many countries are available in more than one language; in these cases the langCode parameter can be used to specify which language should be used for addresses returned by the reverseGeocode operation. This is useful for ensuring that addresses are returned in the expected language by reverse geocoding functionality in an application. For example, a web application could be designed to get the browser language and pass it as the langCode parameter value in a reverseGeocode request.

See the table of supported countries for valid language code values in each country. The Two-Digit Language Codes column provides the valid input values for the langCode parameter. Only the two-digit language codes in this column are accepted as valid input; neither three-digit language codes nor full language names can be used with the langCode parameter.

NoteNote:

The language code "XX" is a convention used to represent transliterated or transcribed versions of a language.

In addition to the supported language codes, the table also includes the Default Language Code column, which lists the default language of addresses returned by the reverseGeocode operation for each country. For countries with multiple supported languages, the default language is the one spoken by the highest percentage of the country's population. Addresses are not always available in the default language for the entirety of a particular country.

NoteNote:

The langCode parameter is not supported for Japan and Hong Kong locations.

Similarly, when there are multiple supported languages for addresses in a country, it doesn't mean that every address in the country is available in each of the languages. It may be the case that addresses are available in multiple languages for only one region of the country, or that each language is exclusive to different regions and there is no overlap at all.

  • Both English and French are listed as supported languages for Canada. However, there is no overlap between the languages for any addresses—in the province of Quebec, only French addresses are available, while English is the only language used for the rest of the country.
  • In Belgium, where three languages are supported (Dutch, French, and German), addresses are available in the City of Brussels in both Dutch and French; however, in the rest of the country, the addresses are only available in a single language.
  • In Greece there is complete address coverage in both Greek and transliterated Greek languages (Greek words translated with Latin characters).

Due to variability of language coverage, the following logic is used to handle the different scenarios that may be encountered.

Scenario

Result

Example

No langCode value is specified and only one language is supported at the input location.

Address is returned in the supported language

Location in Geneva, Switzerland (only French addresses are supported)

French address returned

No langCode value is specified and multiple languages are supported at the input location.

Address is returned in the country's default language

Location in Brussels, Belgium (Dutch and French addresses are supported; Dutch is the default language)

Dutch address returned

An invalid langCode value is specified and only one language is supported at the input location.

Address is returned in the supported language

Location in Geneva, Switzerland (only French addresses are supported), and langCode=zh

French address returned

An invalid langCode is specified and multiple languages are supported at the input location; the input langCode is a Latin-based script and a transliterated address exists at the location.

Address is returned in transliterated format

Location in Athens, Greece (Greek and transliterated Greek are supported), and langCode=fr

Transliterated Greek address returned

An invalid langCode is specified and multiple languages are supported at the input location; the input langCode is not a Latin-based script.

Address is returned in the country's default language

Location in Athens, Greece (Greek and transliterated Greek are supported; Greek is the default language), and langCode=ru

Greek address returned

Example:
langCode=fr

forStorage

Specifies whether the results of the operation will be persisted. The default value is false, which indicates the results of the operation can't be stored, but they can be temporarily displayed on a map, for instance. If you store the results, in a database, for example, you need to set this parameter to true.

Applications are contractually prohibited from storing the results of reverse-geocoding transactions unless they make the request by passing the forStorage parameter with a value of true and the token parameter with a valid ArcGIS Online token. Instructions for composing a request with a valid token are provided in Authentication.

ArcGIS Online service credits are deducted from the organization account for each geocode transaction that includes the forStorage parameter with a value of true and a valid token. Refer to the ArcGIS Online service credits overview page for more information on how credits are charged.

To learn more about free and paid geocoding operations, see Free vs. paid operations.

Example:
forStorage=true

returnIntersection

A Boolean that specifies whether the service should return the nearest street intersection or the nearest address to the input location. If true, then the closest intersection to the input location is returned; if false, then the closest address to the input location is returned. The default value is false.

Example:
returnIntersection=true

Reverse geocode examples

Example: Reverse geocode the location x = 2.2945, y = 48.8583

Request URL

JSON response

{
 "address": {
  "Address": "4 Avenue Gustave Eiffel",
  "Neighborhood": "7e Arrondissement",
  "City": "Paris",
  "Subregion": "Paris",
  "Region": "Île-de-France",
  "Postal": "75007",
  "PostalExt": null,
  "CountryCode": "FRA",
  "Match_addr": "4 Avenue Gustave Eiffel, 75007, 7e Arrondissement, Paris, Île-de-France",
  "Loc_name": "FRA.PointAddress"
 },
 "location": {
  "x": 2.2956042268863568,
  "y": 48.858155299571777,
  "spatialReference": {
   "wkid": 4326,
   "latestWkid": 4326
  }
 }
}

Example: Reverse geocode a location in Brussels with langCode=fr (location = 4.366281,50.851994)

Request URL

JSON response

{
 "address": {
  "Address": "Rue de la Sablonnière 15",
  "Neighborhood": "Bruxelles",
  "City": "Bruxelles",
  "Subregion": "Bruxelles",
  "Region": "Bruxelles",
  "Postal": "1000",
  "PostalExt": null,
  "CountryCode": "BEL",
  "Match_addr": "Rue de la Sablonnière 15, 1000, Bruxelles",
  "Loc_name": "BEL.PointAddress"
 },
 "location": {
  "x": 4.3662658131546248,
  "y": 50.851964049883307,
  "spatialReference": {
   "wkid": 4326,
   "latestWkid": 4326
  }
 }
}

3/3/2017