arcgis.geocoding module

The arcgis.geocoding module provides types and functions for geocoding, batch geocoding and reverse geocoding.

Geocoders can find point locations of addresses, business names, 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. It is 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.

Geocoder

class arcgis.geocoding.Geocoder(location, gis=None)

Geocoders can find point locations of addresses, business names, 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. It is 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.

A GIS includes one or more geocoders, that can be queried using get_geocoders(gis).

Geocoders shared as Items in the GIS can be obtained using Geocoder.fromitem(item).

Geocoders may also be created using the constructor by passing in their location, such as a url to a Geocoding Service.

classmethod fromitem(item)

Creates a Geocoder from an Item in the GIS :param item: an Item of type ‘Geocoding Service’ :return: Geocoder

properties

The properties of this object

get_geocoders

arcgis.geocoding.get_geocoders(gis)

A GIS includes one or more geocoders. The list of geocoders registered with the GIS can be queried using get_geocoders.

Parameters:gis – the GIS whose registered geocoders are to be queried
Returns:list of geocoders registered with the GIS

geocode

geocoding.geocode(address, search_extent=None, location=None, distance=None, out_sr=None, category=None, out_fields='*', max_locations=20, magic_key=None, for_storage=False, geocoder=None, as_featureset=False)

The geocode function geocodes one location per request.

Argument Description
address

required list of strings or dictionaries. Specifies the location to be geocoded. This can be a string containing the street address, place name, postal code, or POI.

Alternatively, this can be a dictionary containing the various address fields accepted by the corresponding geocoder. These fields are listed in the addressFields property of the associated geocoder. For example, if the address_fields of a geocoder includes fields with the following names: Street, City, State and Zone, then the address argument is of the form: {

Street: “1234 W Main St”, City: “Small Town”, State: “WA”, Zone: “99027”

}

search_extent optional string, A set of bounding box coordinates that limit the search area to a specific region. This is especially useful for applications in which a user will search for places and addresses only within the current map extent.
location optionl [x,y], Defines an origin point location that is used with the distance parameter to sort geocoding candidates based upon their proximity to the location.
distance optional float, Specifies the radius of an area around a point location which is used to boost the rank of geocoding candidates so that candidates closest to the location are returned first. The distance value is in meters.
out_sr optional dictionary, 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.
category optional string, A place or address type which can be used to filter find results. The parameter supports input of single category values or multiple comma-separated values. The category parameter can be passed in a request with or without the text parameter.
out_fields optional string, name of all the fields to inlcude. The default is “*” which means all fields.
max_location optional integer, The number of locations to be returned from the service. The default is 20.
magic_key The find operation retrieves results quicker when you pass a valid text and magickey value.
for_storage 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.
geocoder Optional, the geocoder to be used. If not specified, the active GIS’s first geocoder is used.
as_featureset optional boolean, if True, the result set is returned as a FeatureSet object, else it is a dictionary.
Returns:dictionary

geocode_from_items

arcgis.geocoding.geocode_from_items(input_data, output_type='Feature Layer', geocode_service_url=None, geocode_parameters=None, country=None, output_fields=None, header_rows_to_skip=1, output_name=None, category=None, context=None, gis=None)

The Batch Geocode geocodes a table or file of addresses and returns the geocoded results. It supports CSV, XLS or table input. The task geocodes the entire file regardless of size.

Argument Description
input_data required Item, string, Layer. Data to geocode.
output_type optional string. Export item types. Allowed values are CSV, XLS, or Feature Layer (default)
geocode_service_url optional string of Geocoder. Optional geocoder to use to spatially enable the dataset.
geocode_parameters

optional dictionary. This includes parameters that help parse the input data, as well the field lengths and a field mapping. This value is the output from the analyze_geocode_input() available on your server designated to geocode. It is important to inspect the field mapping closely and adjust them accordingly before submitting your job, otherwise your geocoding results may not be accurate. It is recommended to use the output from analyze_geocode_input() and modify the field mapping instead of constructing this dictionary by hand.

Values

field_info - A list of triples with the field names of your input data, the field type (usually TEXT), and the allowed length (usually 255). Example: [[‘ObjectID’, ‘TEXT’, 255], [‘Address’, ‘TEXT’, 255],

[‘Region’, ‘TEXT’, 255], [‘Postal’, ‘TEXT’, 255]]

header_row_exists - Enter true or false.

column_names - Submit the column names of your data if your data does not have a header row.

field_mapping - Field mapping between each input field and candidate fields on the geocoding service. Example: [[‘ObjectID’, ‘OBJECTID’], [‘Address’, ‘Address’],

[‘Region’, ‘Region’], [‘Postal’, ‘Postal’]]
country optional string. If all your data is in one country, this helps improve performance for locators that accept that variable.
output_fields optional string. Enter the output fields from the geocoding service that you want returned in the results, separated by commas. To output all available outputFields, leave this parameter blank. Example: score,match_addr,x,y
header_rows_to_skip optional integer. Describes on which row your data begins in your file or table. The default is 1 (since the first row contains the headers). The default is 1.
output_name optional string, The task will create a feature service of the results. You define the name of the service.
category optional string. Enter a category for more precise geocoding results, if applicable. Some geocoding services do not support category, and the available options depend on your geocode service.
context

optional dictionary. Context contains additional settings that affect task execution. Batch Geocode has the following two settings:

  1. Extent (extent) - A bounding box that defines the analysis area. Only those points in inputLayer that intersect the bounding box are analyzed.
  2. Output Spatial Reference (outSR) - The output features are projected into the output spatial reference.

Syntax: { “extent” : {extent} “outSR” : {spatial reference} }

gis optional GIS, the GIS on which this tool runs. If not specified, the active GIS is used.
Returns:arcgis.gis.Item

analyze_geocode_input

arcgis.geocoding.analyze_geocode_input(input_table_or_item, geocode_service_url=None, column_names=None, input_file_parameters=None, locale='en', context=None, gis=None)

The analyze_geocode_input function takes in a geocode input (either a table or file of addresses) and returns an output dictionary that includes a suggested field mapping. It supports CSV, XLS, or table input. The table can be from a big data file share or from a feature service. The task generates a suggested field mapping based on the input fields and the geocoding service candidate fields and returns it in a geocode_parameters dictionary. This geocode_parameters dictionary output is the an input to the Batch Geocode tool. The output geocode_parameters dictionary also includes field info (name, length, and type) as well as additional information that helps the geocode tool parse the input file or table.

Argument Description
input_table_or_item

required Item, string or dictionary. The input to analyze for geocoding.

For tables:

The input table specification must include the following:

  • A URL to an input table
  • A service token to access the table

Note that if the table is a hosted table on the same portal, serviceToken is not required.

Example: {“url”:”<table url>”,”serviceToken”:”<token>”}

For File Items:

The input file should be a portal item. Input the itemid of the item in the portal. The format of the item in the portal can be in one of the following formats:

  • CSV
  • Microsoft Excel spreadsheet (XLSX)

Example: {“itemid”: “<itemid of file>” }

geocode_service_url Optional string or Geocode class. The geocode service that you want to geocode your addresses against.
column_names Optional string. Only used when input table or Item has no header row. Example: address,city,state,zip
input_file_parameters

Optional dictionary. Enter information about how to parse the file. If you are using an input table instead of an Item as input, this parameter can be left blank. Any of the key values in the dictionary can be left blank using the “”.

Values:

fileType - Enter CSV or XLS for the file format of file Item. headerRowExists - Enter true if your file has a header row,

false if it does not.

columnDelimiter - Enter SPACE, TAB, COMMA, PIPE, or SEMICOLON. textQualifier - Enter either SINGLE_QUOTE or DOUBLE_QUOTE.

Example: {“fileType”:”xlsx”,”headerRowExists”:”true”,
“columnDelimiter”:”“,”textQualifier”:”“}
locale Optional string. Enter the 2-letter (“en”) or 4-letter (“ar-il”) specific locale if geocodeInput is in a language other than English.
context

Optional dictionary. Context contains additional settings that affect task execution. Analyze_geocode_input() has the following two settings: 1. Extent (extent) - A bounding box that defines the analysis

area. Only those points in inputLayer that intersect the bounding box are analyzed.
  1. Output Spatial Reference (outSR) - The output features are projected into the output spatial reference.
gis Optional GIS. Connection to the site. If None is given, the active GIS is used.
Returns:dictionary
Usage Example:
>>>res = analyze_geocode_input(geocode_service_url=Geocoder,

input_table_or_item={“itemid” : “abc123545asv”}, input_file_parameters={“fileType”:”csv”,”headerRowExists”:”true”,

“columnDelimiter”:”“,”textQualifier”:”“})
>>> print(res)
{'header_row_exists': True, 'field_info': '[["Address", "TEXT", 255], ["City", "TEXT", 255],
["State", "TEXT", 255], ["ZipCode", "TEXT", 255]]', 'file_type': 'csv', 'field_mapping': '[["Address", ""],
["City", "City"], ["State", "State"], ["ZipCode", ""]]', 'column_names': '',
'column_delimiter': '', 'text_qualifier': '', 'singleline_field': 'Single Line Input'}
Usage Example 2:
 
>>> table_lyr = Table(url="http://testsite.com/server/rest/services/Hosted/addresses/FeatureServer/0", gis=gis)
>>> res = analyze_geocode_input()

reverse_geocode

arcgis.geocoding.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.

Argument Description
location required list/Point Geometry
distance optional float, radial distance in meteres to search for an address. The default is 100 meters.
out_sr optional integer, spatial reference of the x/y coordinate returned.
return_intersection optional Boolean, which specifies whether the service should return the nearest street intersection or the nearest address to the input location
for_storage optional boolean, specifies whether the results of the operation will be persisted
geocoder optional geocoder, the geocoder to be used. If not specified, the active GIS’s first geocoder is used.
Returns:dictionary

batch_geocode

arcgis.geocoding.batch_geocode(addresses, source_country=None, category=None, out_sr=None, geocoder=None, as_featureset=False)

The batch_geocode() function geocodes an entire list of addresses. Geocoding many addresses at once is also known as bulk geocoding.

Argument Description
addresses

required list of strings or dictionaries. A list of addresses to be geocoded. For passing in the location name as a single line of text - single field batch geocoding - use a string. For passing in the location name as multiple lines of text multifield batch geocoding - use the address fields described in the Geocoder documentation.

The maximum number of addresses that can be geocoded in a single request is limited to the SuggestedBatchSize property of the locator. Syntax:

addresses = [“380 New York St, Redlands, CA”, “1 World Way, Los Angeles, CA”, “1200 Getty Center Drive, Los Angeles, CA”, “5905 Wilshire Boulevard, Los Angeles, CA”, “100 Universal City Plaza, Universal City, CA 91608”, “4800 Oak Grove Dr, Pasadena, CA 91109”]

OR

addresses= [{
“Address”: “380 New York St.”, “City”: “Redlands”, “Region”: “CA”, “Postal”: “92373”
},{
“Address”: “1 World Way”, “City”: “Los Angeles”, “Region”: “CA”, “Postal”: “90045”

}]

source_country optional string, The source_country parameter is only supported by geocoders published using StreetMap Premium locators. Added at 10.3 and only supported by geocoders published with ArcGIS 10.3 for Server and later versions.
category The category parameter is only supported by geocode services published using StreetMap Premium locators.
out_sr optional dictionary, 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.
as_featureset optional boolean, if True, the result set is returned as a FeatureSet object, else it is a dictionary.
geocoder Optional, the geocoder to be used. If not specified, the active GIS’s first geocoder is used.
Returns:dictionary or FeatureSet

suggest

arcgis.geocoding.suggest(text, location, distance=None, category=None, geocoder=None)

The result of this operation is a resource representing a list of suggested matches for the input text. This resource provides the matching text as well as a unique ID value, which links a suggestion to a specific place or address. A geocoder must meet the following requirements to support the suggest operation:

The address locator from which the geocoder was published must support suggestions. Only address locators created using ArcGIS 10.3 for Desktop and later can support suggestions. See the Create Address Locator geoprocessing tool help topic for more information. The geocoder must have the Suggest capability enabled. Only geocoders published using ArcGIS 10.3 for Server or later support the Suggest capability.

The suggest operation allows character-by-character auto-complete suggestions to be generated for user input in a client application. This capability facilitates the interactive search user experience by reducing the number of characters that need to be typed before a suggested match is obtained. A client application can provide a list of suggestions that is updated with each character typed by a user until the address they are looking for appears in the list.

Argument Description
text The input text provided by a user that is used by the suggest operation to generate a list of possible matches. This is a required parameter.
location Defines an origin point location that is used with the distance parameter to sort suggested candidates based on their proximity to the location. The distance parameter specifies the radial distance from the location in meters. The priority of candidates within this radius is boosted relative to those outside the radius. This is useful in mobile applications where a user wants to search for places in the vicinity of their current GPS location. It is also useful for web mapping applications where a user wants to find places within or near the map extent. The location parameter can be specified without specifying a distance. If distance is not specified, it defaults to 2000 meters.
distance Specifies the radius around the point defined in the location parameter to create an area, which is used to boost the rank of suggested candidates so that candidates closest to the location are returned first. The distance value is in meters. If the distance parameter is specified, the location parameter must be specified as well. It is important to note that the location and distance parameters allow searches to extend beyond the specified search radius. They are not used to filter results, but rather to rank resulting candidates based on their distance from a location.
category The category parameter is only supported by geocode services published using StreetMap Premium locators.
geocoder Optional, the geocoder to be used. If not specified, the active GIS’s first geocoder is used.