Understanding geocoders¶
Geocoders are tools that can find spatial coordinates of addresses, business names, places of interest and so on. The output points can be visualized on a map, inserted as stops for a route, or loaded as input for spatial analysis. They also used to generate batch results for a set of addresses, as well as for reverse geocoding, i.e. determining the address at a particular x/y location.
The arcgis.geocoding module provides types and functions for geocoding, batch geocoding and reverse geocoding.
In this guide, we will observe
The GIS's geocoders¶
A GIS includes one or more geocoders. The list of geocoders registered with the GIS can be queried using get_geocoders(). This method returns a list of Geocoder instances.
In the example below, there is one registered Geocoder with the GIS, that uses the Esri World Geocoding Service for geocoding:
from arcgis.gis import GIS
from arcgis.geocoding import Geocoder, get_geocoders
gis = GIS("portal url", "username", "password")
get_geocoders(gis)
The default geocoder¶
The arcgis.geocoding modules provides functions for geocoding, reverse geocoding and batch geocoding. These functions use a Geocoder for their operation. All geocoding functions have an optional parameter for specifying the geocoder to be used.
The first available geocoder in the active GIS is used by default, unless specified. Creating a new GIS object makes it’s first available geocoder as the default geocoder unless set_active=False is passed in the GIS constructor.
However, it is possible to use a different Geocoder by specifying it explicitly as a method parameter.
Creating a geocoder using a geocoding service item¶
Geocoding services can be published as items in the GIS. An instance of the geocoder can also be constructed by passing in a reference to these items from the GIS to the Geocoder's constructor:
from IPython.display import display
arcgis_online = GIS()
items = arcgis_online.content.search('Geocoder', 'geocoding service', max_items=3)
for item in items:
display(item)
# construct a geocoder using the first geocoding service item
worldgeocoder = Geocoder.fromitem(items[0])
worldgeocoder
Geocoding Service by esri
Creating a geocoder from a geocoding service¶
Geocoders may also be created using the constructor by passing in their location, such as a url to a Geocoding Service. If the geocoding service is a secure service, pass in the GIS to which it is federated with as the gis parameter:
geocoder_url = 'https://services.arcgisonline.nl/arcgis/rest/services/Geocoder_BAG_RD/GeocodeServer'
esrinl_geocoder = Geocoder(geocoder_url, gis)
esrinl_geocoder
Using default geocoder¶
The example below shows calling the geocode() function to geocode an address. It does not pass in the geocoder to be used for geocoding, which makes the active GIS's first geocoder to be used by default.
from arcgis.geocoding import geocode
results = geocode('New York St, Redlands, CA')
# query the first matched result
results[0]['location']
Specifying the geocoder to be used¶
The example below shows calling the geocode() function to geocode an address. It specifies that the esrinl_geocoder created above should be used for geocoding by passing it in explicitly.
results = geocode('Raadhuisstraat 52, 1016 Amsterdam', geocoder=esrinl_geocoder)
# query the first matched result
results[0]['location']
Geocoders have several properties and they can be accessed on geocoder.properties as shown in the intellisence below
The code snippet below lists the properties of the default geocoder:
geocoder = get_geocoders(gis)[0]
[prop_name for prop_name in geocoder.properties.keys()]
Some of the important properties are described in detail below:
addressFields property¶
The Geocoder's 'addressFields' property specifies the various address fields accepted by it when geocoding addresses.
For instance, the address fields accepted by this geocoder, and their length, are the following:
for addrfld in geocoder.properties.addressFields:
print(addrfld['name'] + " (" + str(addrfld['length']) +" chars)")
Single Line Address Field¶
The geocoder may also support a single line address field. Single field input is easier because the address parsing is done for you; however, multifield input may provide faster responses and more precise results. The field name can be found using the code below:
geocoder.properties.singleLineAddressField['name']
When using single line input for the address, it is unnecessary (though supported) to create a dict with this key and the single line address as it's value. The address can be passed in directly as a text string.
One instance of when you might use a dict to include the SingleLine parameter is when it is combined with the countryCode parameter. The SingleLine parameter cannot be used with any of the other multifield parameters.
Localized input field names¶
Developers integrating the geocoder into their application may need to know the appropriate input field names to use for the language and country of their users. This information can be obtained using the 'localizedNames' parameter of the address field. More information on this as well as the 'recognizedNames' parameter is avilable in the Foreign language field names (World Geocoding Service) documentation
For example, the code below lists the supported address fields and the corresponding input field names in Hindi:
for addrfld in geocoder.properties.addressFields:
print(addrfld['name'], end='')
print(": " + str(addrfld['localizedNames']['hi'] if 'hi' in addrfld['localizedNames'] else '-'))
Categories property¶
The 'categories' property can be used to limit result to one or more categories. For example, "Populated Place" or "Scandinavian Food". Only applies to the World Geocode Service. See Category filtering (World Geocoding Service) for more information.
The following code lists the entire hierarchy of supported category values.
def list_categories(obj, depth = 0):
for category in obj['categories']:
print('\t'*depth + category['name'])
if 'categories' in category:
list_categories(category, depth + 1)
list_categories(geocoder.properties)
candidateFields property¶
The CandidateFields property of the geocoder contains the fields that are returned for each candidate.
for addrfld in geocoder.properties.candidateFields:
print(addrfld['name'])
spatialReference property¶
The default spatial reference returned by the geocoder. The code below is querying the well known id of the default spatial reference of the geocoder.
geocoder.properties.spatialReference['wkid']
Locator properties¶
The geocoder has several important properties that are specified in the locatorProperties.
These include the maximum number of addresses that can be geocoded in a single batch geocoding method call. The MaxBatchSize property defines this limit. For instance, if MaxBatchSize=2000, and 3000 addresses are passed in as input to the batch_geocode() method, only the first 2000 will be geocoded.
The SuggestedBatchSize property is also useful as it specifies the optimal number of addresses to include in a single batch request.
The code below lists these useful locator properties.
for key, value in geocoder.properties.locatorProperties.items():
print(key + " : "+ str(value))
Feedback on this topic?