Reverse Geocoding

The reverse_geocode() function in the arcgis.geocoding module determines the address at a particular x/y location. You pass the coordinates of a point location to the geocoder, and it returns the address that is closest to the location.

In this guide we will learn about:

reverse_geocode() function signature and parameters

The code snippet below imports the reverse_geocode() function and displays its signature and parameters along with a brief description:

In [1]:
from arcgis.geocoding import reverse_geocode

help(reverse_geocode)
Help on function reverse_geocode in module arcgis.geocoding._functions:

reverse_geocode(location, distance=None, out_sr=None, lang_code=None, return_intersection=False, for_storage=False, geocoder=None)
    The reverse_geocode 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.
    Input:
    
       location - a list defined as [X,Y] or a Point Geometry object
    
       distance - allows you to specify a radial distance in meters to search for an address from the specified location.
                  If no distance value is specified then the value is assumed to be 100 meters.
    
       out_sr - spatial reference of the x/y coordinates returned.
    
       lang_code - sets the language in which reverse-geocoded addresses are returned.
    
       return_intersection - Boolean which specifies whether the service should return the nearest street intersection
                             or the nearest address to the input location
    
       for_storage - specifies whether the results of the operation will be persisted
    
       geocoder - Optional, the geocoder to be used. If not specified, the active GIS's first geocoder is used.

location parameter

The point from which to search for the closest address. The point can be represented as a simple list of coordinates ([x, y] or [longitude, latitude]) or as a JSON point object.

The spatial reference of the list of coordinates is always WGS84 (in decimal degress), 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 } }

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

In [2]:
from arcgis.gis import GIS
from arcgis.geocoding import reverse_geocode

gis = GIS("portal url", "username", "password")
In [3]:
results = reverse_geocode([2.2945, 48.8583])
In [4]:
results
Out[4]:
{'address': {'Address': '6 Avenue Gustave Eiffel',
  'City': 'Paris',
  'CountryCode': 'FRA',
  'Loc_name': 'FRA.PointAddress',
  'Match_addr': '6 Avenue Gustave Eiffel, 75007, 7e Arrondissement, Paris, Île-de-France',
  'Neighborhood': '7e Arrondissement',
  'Postal': '75007',
  'PostalExt': None,
  'Region': 'Île-de-France',
  'Subregion': 'Paris'},
 'location': {'spatialReference': {'latestWkid': 4326, 'wkid': 4326},
  'x': 2.29465293958984,
  'y': 48.85748501186063}}

Example: Reverse geocode location specified as a Point geometry

In [5]:
from arcgis.geometry import Geometry
In [6]:
pt = Geometry({
    "x": 11563503,
    "y": 148410,
    "spatialReference": {
        "wkid": 3857
    }
})
In [7]:
results = reverse_geocode(pt)
In [8]:
results
Out[8]:
{'address': {'Address': '40 Lichi Avenue',
  'City': None,
  'CountryCode': 'SGP',
  'Loc_name': 'SGP.PointAddress',
  'Match_addr': '40 Lichi Avenue, 348814, Singapore',
  'Neighborhood': None,
  'Postal': '348814',
  'PostalExt': None,
  'Region': None,
  'Subregion': None},
 'location': {'spatialReference': {'latestWkid': 4326, 'wkid': 4326},
  'x': 103.87671886128821,
  'y': 1.3330587058289018}}

distance parameter

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 then the value is assumed to be 100 meters.

Example:

distance=50

out_sr parameter

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 out_sr 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):

out_sr=102100

lang_code parameter

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 reverse_geocode() method. 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 then 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.

Note: 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.

Note: 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. Examples:

  • 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 which may be encountered.

ScenarioResultExample

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:

lang_code="fr"

return_intersection parameter

A Boolean which 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:

return_intersection=True

for_storage parameter

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

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

In [9]:
result = reverse_geocode([4.366281,50.851994], lang_code="fr")
In [10]:
result
Out[10]:
{'address': {'Address': 'Rue de la Sablonnière 15',
  'City': 'Bruxelles',
  'CountryCode': 'BEL',
  'Loc_name': 'BEL.PointAddress',
  'Match_addr': 'Rue de la Sablonnière 15, 1000, Bruxelles',
  'Neighborhood': 'Bruxelles',
  'Postal': '1000',
  'PostalExt': None,
  'Region': 'Bruxelles',
  'Subregion': 'Bruxelles'},
 'location': {'spatialReference': {'latestWkid': 4326, 'wkid': 4326},
  'x': 4.366265813154625,
  'y': 50.85196404988331}}

Example: Reverse geocode a clicked location on the map

In [2]:
from arcgis.gis import GIS
from arcgis.geocoding import reverse_geocode
gis = GIS("portal url", "username", "password")
In [3]:
m = gis.map('Redlands, CA', 14)
m
370 N New York St, Redlands, California, 92373
380 New York St, Redlands, California, 92373
In [4]:
def find_addr(m, g):
    try:
        geocoded = reverse_geocode(g)
        print(geocoded['address']['Match_addr'])
    except:
        print("Couldn't match address. Try another place...")

m.on_click(find_addr)

Feedback on this topic?