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:

In [1]:
from arcgis.gis import GIS
from arcgis.geocoding import Geocoder, get_geocoders

gis = GIS("portal url", "username", "password")

get_geocoders(gis)
Out[1]:
[<Geocoder url:"https://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer">]

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:

In [2]:
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    
World Geocoding
The World Geocoding Service finds addresses and places in all supported countries around the world in a single geocoding service.Geocoding Service by esri
Last Modified: January 08, 2015
7 comments, 40,217 views
Esri Nederland BAG Geocoder
Met de Esri Nederland BAG Geocoder zoekt u naar adressen en plaatsenGeocoding Service by Esri_NL_Content
Last Modified: April 24, 2015
0 comments, 1,160 views
VGIN Composite Geocoder
Geocoding Service by VGIN
Last Modified: August 05, 2016
0 comments, 909 views
Out[2]:
<Geocoder url:"http://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer">

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:

In [3]:
geocoder_url = 'https://services.arcgisonline.nl/arcgis/rest/services/Geocoder_BAG_RD/GeocodeServer'
esrinl_geocoder = Geocoder(geocoder_url, gis)
esrinl_geocoder
Out[3]:
<Geocoder url:"https://services.arcgisonline.nl/arcgis/rest/services/Geocoder_BAG_RD/GeocodeServer">

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.

In [4]:
from arcgis.geocoding import geocode
In [5]:
results = geocode('New York St, Redlands, CA')
# query the first matched result
results[0]['location']
Out[5]:
{'x': -117.19568625471618, 'y': 34.054890875214824}

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.

In [6]:
results = geocode('Raadhuisstraat 52, 1016 Amsterdam',  geocoder=esrinl_geocoder)
# query the first matched result
results[0]['location']
Out[6]:
{'x': 120842.00295538208, 'y': 487472.9997233086, 'z': 0}


Properties of a geocoder

Geocoders have several properties and they can be accessed on geocoder.properties as shown in the intellisence below

geocoder properties

The code snippet below lists the properties of the default geocoder:

In [7]:
geocoder = get_geocoders(gis)[0]
[prop_name for prop_name in geocoder.properties.keys()]
Out[7]:
['currentVersion',
 'spatialReference',
 'serviceDescription',
 'capabilities',
 'locatorProperties',
 'addressFields',
 'categories',
 'candidateFields',
 'countries',
 'singleLineAddressField']

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:

In [8]:
for addrfld in geocoder.properties.addressFields:
    print(addrfld['name'] + " (" + str(addrfld['length']) +" chars)")
Address (100 chars)
Neighborhood (50 chars)
City (50 chars)
Subregion (50 chars)
Region (50 chars)
Postal (20 chars)
PostalExt (20 chars)
CountryCode (100 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:

In [9]:
geocoder.properties.singleLineAddressField['name']
Out[9]:
'SingleLine'

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:

In [10]:
for addrfld in geocoder.properties.addressFields:
    print(addrfld['name'], end='')
    print(": " + str(addrfld['localizedNames']['hi'] if 'hi' in addrfld['localizedNames'] else '-'))
Address: प्रमाचार
Neighborhood: इलाका
City: सिटी
Subregion: जनपद
Region: राष्ट्र
Postal: डाक - संबंधी
PostalExt: -
CountryCode: कंट्री कोड

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.

In [11]:
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)
Address
	Point Address
	Building Name
	Street Address
	Intersection
	Street Name
	Distance Marker
Postal
	Primary Postal
	Postal Locality
	Postal Extension
Coordinate System
	LatLong
	MGRS
	XY
	YX
	USNG
Populated Place
	Neighborhood
	City
	Subregion
	Region
	Country
	Zone
POI
	Arts and Entertainment
		Amusement Park
		Aquarium
		Art Gallery
		Art Museum
		Billiards
		Bowling Alley
		Casino
		Cinema
		Historical Monument
		History Museum
		Indoor Sports
		Jazz Club
		Landmark
		Live Music
		Museum
		Other Arts and Entertainment
		Performing Arts
		Ruin
		Science Museum
		Tourist Attraction
		Wild Animal Park
		Zoo
	Education
		College
		Fine Arts School
		Other Education
		School
		Vocational School
	Food
		African Food
		American Food
		Argentinean Food
		Australian Food
		Austrian Food
		Bakery
		BBQ and Southern Food
		Belgian Food
		Bistro
		Brazilian Food
		Breakfast
		Brewpub
		British Isles Food
		Burgers
		Cajun and Creole Food
		Californian Food
		Caribbean Food
		Chicken Restaurant
		Chilean Food
		Chinese Food
		Coffee Shop
		Continental Food
		Creperie
		East European Food
		Fast Food
		Filipino Food
		Fondue
		French Food
		Fusion Food
		German Food
		Greek Food
		Grill
		Hawaiian Food
		Ice Cream Shop
		Indian Food
		Indonesian Food
		International Food
		Irish Food
		Italian Food
		Japanese Food
		Korean Food
		Kosher Food
		Latin American Food
		Malaysian Food
		Mexican Food
		Middle Eastern Food
		Moroccan Food
		Other Restaurant
		Pastries
		Pizza
		Polish Food
		Portuguese Food
		Russian Food
		Sandwich Shop
		Scandinavian Food
		Seafood
		Snacks
		South American Food
		Southeast Asian Food
		Southwestern Food
		Spanish Food
		Steak House
		Sushi
		Swiss Food
		Tapas
		Thai Food
		Turkish Food
		Vegetarian Food
		Vietnamese Food
		Winery
	Land Features
		Atoll
		Basin
		Butte
		Canyon
		Cape
		Cave
		Cliff
		Desert
		Dune
		Flat
		Forest
		Glacier
		Grassland
		Hill
		Island
		Isthmus
		Lava
		Marsh
		Meadow
		Mesa
		Mountain
		Mountain Range
		Oasis
		Other Land Feature
		Peninsula
		Plain
		Plateau
		Point
		Ravine
		Ridge
		Rock
		Scrubland
		Swamp
		Valley
		Volcano
		Wetland
	Nightlife Spot
		Bar or Pub
		Dancing
		Karaoke
		Night Club
		Nightlife
		Other Nightlife Spot
	Parks and Outdoors
		Basketball
		Beach
		Campground
		Diving Center
		Fishing
		Garden
		Golf Course
		Golf Driving Range
		Harbor
		Hockey
		Ice Skating Rink
		Nature Reserve
		Other Parks and Outdoors
		Park
		Racetrack
		Scenic Overlook
		Shooting Range
		Ski Lift
		Ski Resort
		Soccer
		Sports Center
		Sports Field
		Swimming Pool
		Tennis Court
		Trail
		Wildlife Reserve
	Professional and Other Places
		Advertising
		Ashram
		Banquet Hall
		Border Crossing
		Building
		Business Facility
		Cemetery
		Church
		City Hall
		Civic Center
		Convention Center
		Court House
		Dentist
		Doctor
		Embassy
		Factory
		Farm
		Fire Station
		Government Office
		Hospital
		Industrial Zone
		Insurance
		Library
		Livestock
		Medical Clinic
		Military Base
		Mill
		Mine
		Mosque
		Observatory
		Oil Facility
		Orchard
		Other Professional Place
		Other Religious Place
		Plantation
		Police Station
		Post Office
		Power Station
		Prison
		Public Restroom
		Radio Station
		Ranch
		Recreation Facility
		Religious Center
		Scientific Research
		Shrine
		Storage
		Synagogue
		Telecom
		Temple
		Tower
		Veterinarian
		Vineyard
		Warehouse
		Water Tank
		Water Treatment
	Residence
		Estate
		House
		Nursing Home
		Other Residence
		Residential Area
	Shops and Service
		ATM
		Auto Dealership
		Auto Maintenance
		Auto Parts
		Bank
		Beauty Salon
		Bookstore
		Butcher
		Candy Store
		Car Wash
		Childrens Apparel
		Clothing Store
		Consumer Electronics Store
		Convenience Store
		Department Store
		Farmers Market
		Fitness Center
		Flea Market
		Food and Beverage Shop
		Footwear
		Furniture Store
		Gas Station
		Grocery
		Home Improvement Store
		Market
		Mens Apparel
		Mobile Phone Shop
		Motorcycle Shop
		Office Supplies Store
		Other Shops and Service
		Pet Store
		Pharmacy
		Real Estate
		Repair Services
		Shopping Center
		Spa
		Specialty Store
		Sporting Goods Store
		Tire Store
		Toy Store
		Used Car Dealership
		Wholesale Warehouse
		Womens Apparel
		Yoga Studio
	Travel and Transport
		Airport
		Bed and Breakfast
		Bridge
		Bus Station
		Bus Stop
		Dock
		Ferry
		Heliport
		Hostel
		Hotel
		Marina
		Metro Station
		Motel
		Other Travel
		Parking
		Pier
		Port
		Rental Cars
		Resort
		Rest Area
		Taxi
		Tourist Information
		Train Station
		Travel Agency
		Truck Stop
		Tunnel
	Water Features
		Bay
		Canal
		Channel
		Cove
		Dam
		Delta
		Estuary
		Fjord
		Gulf
		Hot Spring
		Irrigation
		Jetty
		Lagoon
		Lake
		Ocean
		Other Water Feature
		Reef
		Reservoir
		Sea
		Sound
		Spring
		Strait
		Stream
		Waterfall
		Well
		Wharf

candidateFields property

The CandidateFields property of the geocoder contains the fields that are returned for each candidate.

In [12]:
for addrfld in geocoder.properties.candidateFields:
    print(addrfld['name'])
Loc_name
Shape
Score
Match_addr
Addr_type
Type
PlaceName
Place_addr
Phone
URL
Rank
AddBldg
AddNum
AddNumFrom
AddNumTo
Side
StPreDir
StPreType
StName
StType
StDir
StAddr
Nbrhd
City
Subregion
Region
Postal
PostalExt
Country
LangCode
Distance
X
Y
DisplayX
DisplayY
Xmin
Xmax
Ymin
Ymax

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.

In [13]:
geocoder.properties.spatialReference['wkid']
Out[13]:
4326

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.

In [14]:
for key, value in geocoder.properties.locatorProperties.items():
    print(key + " : "+ str(value))
MaxBatchSize : 1000
WritePercentAlongField : FALSE
WriteReferenceIDField : FALSE
SuggestedBatchSize : 150
UICLSID : {3D486637-6BCF-4A0C-83DB-A02D437FB8FC}
WriteStandardizedAddressField : FALSE
IntersectionConnectors : &amp; @ | and
WriteXYCoordFields : TRUE
LoadBalancerTimeOut : 60

Feedback on this topic?