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) The
Geocoder
class represents Geocoder objects.Geocoder
objects 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.Note
A
GIS
includes one or more geocoders, which can be queried using get_geocoders(gis).Note
Geocoders
shared asItem
objects in the GIS can be obtained using Geocoder.fromitem(item).Note
Geocoder
objects may also be created using the constructor by passing in their location, such as a url to aGeocoding Service
.
PlacesAPI
-
class
arcgis.geocoding.
PlacesAPI
(gis) The places service is a ready-to-use location service that can search for businesses and geographic locations around the world. It allows you to find, locate, and discover detailed information about each place.
-
examine_category
(category) Get the category details for a category ID.
Parameter
Description
category
Required String. The category ID to examine.
- Returns
Dictionary
-
find_category
(query) Return the name and category ID of all categories, or categories which satisfy a filter.
A category describes a type of place, such as “movie theater” or “zoo”. The places service has over 1,000 categories (or types) of place. The categories fall into ten general groups: Arts and Entertainment, Business and Professional Services, Community and Government, Dining and Drinking, Events, Health and Medicine, Landmarks and Outdoors, Retail, Sports and Recreation, and Travel and Transportation.
Parameter
Description
query
Required String. The filter string used to find the matching categories.
- Returns
Dictionary
-
get_place_by_id
(placeid, filters=None) Get place details including name, address, description, and other attributes.
Parameter
Description
placeid
Required String. The Id of the place for which you want to fetch additional details.
fields
Optional list[string]. The array of fields that define the attributes to return for a place.
- Returns
dict[str,Any]
-
search_by_extent
(bbox, categories=None, search_text=None, page_size=10) Search for places within an extent (bounding box).
Parameter
Description
bbox
list/tuple[float]. The min X/Y and max X/Y coordinates to search within. Coordinates must be in WGS-1984 (Lat/Long).
Example: [-54,-75,54,75]
categories
Optional list[str]. The category IDs to examine.
search_text
Optional str. The free search text for places against names, categories etc.
page_size
Optional Integer. The amount of records to return per query. The default is 10.
- Returns
Iterator[dict[str,Any]]
-
search_by_radius
(point, radius=1000, categories=None, search_text=None, page_size=10) Search for places near a point or location by radius.
Parameter
Description
point
list/tuple[float]. The X/Y coordinates centroid to search by radius by. The coordinates must be in WGS-1984 (Lat/Long).
Example: [-73.991997,40.743648]
categories
Optional list[str]. The category IDs to examine.
search_text
Optional str. The free search text for places against names, categories etc.
page_size
Optional Integer. The amount of records to return per query. The default is 10.
- Yield
dict[str,Any]
-
PlaceIdEnums
get_geocoders
-
arcgis.geocoding.
get_geocoders
(gis) The
get_geocoders
method is used to query the list of geocoders registered with theGIS
.Note
A
GIS
includes one or moreGeocoder
objects.- Parameters
gis – the GIS whose registered geocoders are to be queried
Parameter
Description
gis
A required
Gis
object. TheGIS
whose registeredgeocoders
are to be queried.- Returns
A list of
Geocoder
objects registered with theGIS
.
geocode
-
geocoding.
geocode
(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, match_out_of_range=True, location_type='street', lang_code=None, source_country=None) The
geocode
function geocodes one location per request.Parameter
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
Optional [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 include. 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
Optional string. The find operation retrieves results quicker when you pass a valid text and magic_key value.
for_storage
Optional Boolean. 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.
Note
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.Note
If not specified, the active
GIS
object’s first geocoder is used.as_featureset
Optional boolean, If
True
, the result set is returned as aFeatureSet
object, else it is a dictionary.match_out_of_range
Optional Boolean. Provides better spatial accuracy for inexact street addresses by specifying whether matches will be returned when the input number is outside of the house range defined for the input street. Out of range matches will be defined as Addr_type=StreetAddressExt. Input house numbers that exceed the range on a street segment by more than 100 will not result in StreetAddressExt matches. The default value of this parameter is True.
location_type
Optional Str. Specifies whether the rooftop point or street entrance is used as the output geometry of PointAddress matches. By default, street is used, which is useful in routing scenarios, as the rooftop location of some addresses may be offset from a street by a large distance. However, for map display purposes, you may want to use rooftop instead, especially when large buildings or landmarks are geocoded. The location_type parameter only affects the location object in the JSON response and does not change the x,y or DisplayX/DisplayY attribute values.
Values: street or rooftop
lang_code
Optional str. Sets the language in which geocode results are returned.
source_country
Optional str. Limits the returned candidates to the specified country or countries for either single-field or multifield requests. Acceptable values include the 3-character country code.
# Usage Example >>> geocoded = geocode(addresses = { Street: "1234 W Main St", City: "Small Town", State: "WA", Zone: "99027" }, distance = 1000, max_locations = 50, as_featureset = True, match_out_of_range = True, location_type = "Street" ) >>> type(geocoded) <:class:`~arcgis.features.FeatureSet>
- Returns
A dictionary or
FeatureSet
object.
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
geocode_from_items
method createsGeocoder
objects from anItem
orLayer
objects.Note
geocode_from_items
geocodes the entire file regardless of size.Parameter
Description
input_data
required Item, string, Layer. Data to geocode.
output_type
optional string. Export item types. Allowed values are “CSV”, “XLS”, or “FeatureLayer”.
Note
The default for
output_type
is “FeatureLayer”.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 fromanalyze_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:
Extent (extent) - A bounding box that defines the analysis area. Only those points in inputLayer that intersect the bounding box are analyzed.
Output Spatial Reference (outSR) - The output features are projected into the output spatial reference.
Syntax: { “extent” : {extent} “outSR” : {spatial reference} }
gis
optional
GIS
, theGIS
on which this tool runs.Note
If not specified, the active
GIS
is used.# Usage Example >>> fl_item = geocode_from_items(csv_item, output_type='Feature Layer', geocode_parameters={"field_info": ['Addresses', 'TEXT', 255], "column_names": ["Addresses"], "field_mapping": ['Addresses', 'Address'] }, output_name="address_file_matching", gis=gis) >>> type(fl_item) <:class:`~arcgis.gis.Item`>
- Returns
A
Item
object.
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 ageocode_parameters
dictionary. Thisgeocode_parameters
dictionary output is the an input to theBatch Geocode
tool. The outputgeocode_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.Parameter
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
Geocoder
object. 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,zipinput_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 analysisarea. Only those points in inputLayer that intersect the bounding box are analyzed.
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 activeGIS
is used.- Returns
A dictionary
reverse_geocode
-
arcgis.geocoding.
reverse_geocode
(location, distance=None, out_sr=None, lang_code=None, return_intersection=False, for_storage=False, geocoder=None, feature_types=None, roof_top='street') 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.Parameter
Description
location
Required location input as list, dict (with or without SpatialReference), or
Point
object.distance
optional float, radial distance in meters to search for an address.
Note
The default for
distance
is 100 meters.out_sr
optional integer or
SpatialReference
of the x/y coordinate returned.lang_code
optional string. Sets the language in which geocode results are returned. This is useful for ensuring that results are returned in the expected language. If the lang_code parameter isn’t included in a request, or if it is included but there are no matching features with the input language code, the resultant match is returned in the language code of the primary matched components from the input search string.
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.Note
If not specified, the active
GIS
instances firstGeocoder
is used.feature_types
Optional String. Limits the possible match types performed by the reverse_geocode method. If a single value is included, the search tolerance for the input feature type is 500 meters. If multiple values (separated by a comma, with no spaces) are included, the default search distances specified in the feature type hierarchy table are applied.
- Values: `StreetInt, DistanceMarker, StreetAddress,
StreetName, POI, PointAddress, Postal, and Locality`
location_type
Optional string. Specifies whether the rooftop point or street entrance is used as the output geometry of point address matches. By default,
street
is used, which is useful in routing scenarios, as the rooftop location of some addresses may be offset from a street by a large distance. However, for map display purposes, you may want to userooftop
instead, especially when large buildings or landmarks are geocoded. Thelocation_type
parameter only affects the location object in the JSON response and does not change the x,y orDisplayX/DisplayY
attribute values.Values:
street
,rooftop
# Usage Example >>> reversed = Geocoder.reverse_geocode(location = point1, distance = 50, for_storage = True, feature_types = "StreetName", location_type = "street") >>> type(reversed) <Dictionary>
- Returns
A dictionary
batch_geocode
-
arcgis.geocoding.
batch_geocode
(addresses, source_country=None, category=None, out_sr=None, geocoder=None, as_featureset=False, match_out_of_range=True, location_type='street', search_extent=None, lang_code='EN', preferred_label_values=None, out_fields=None) The
batch_geocode
function geocodes an entire list of addresses.Note
Geocoding many addresses at once is also known as bulk geocoding.
Parameter
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.
Note
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”
- },{
“OBJECTID”: 2, “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.Note
Added at 10.3 and only supported by geocoders published with ArcGIS 10.3 for Server and later versions.
category
Optional String. 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
Geocoder
, the geocoder to be used.Note
If not specified, the active
GIS
instances firstGeocoder
is used.match_out_of_range
Optional, A Boolean which specifies if StreetAddress matches should be returned even when the input house number is outside of the house number range defined for the input street.
location_type
Optional, Specifies if the output geometry of PointAddress matches should be the rooftop point or street entrance location. Valid values are rooftop and street.
search_extent
Optional, a set of bounding box coordinates that limit the search area to a specific region. The input can either be a comma-separated list of coordinates defining the bounding box or a JSON envelope object.
lang_code
Optional, sets the language in which geocode results are returned. See the table of supported countries for valid language code values in each country.
preferred_label_values
Optional, allows simple configuration of output fields returned in a response from the World Geocoding Service by specifying which address component values should be included in output fields. Supports a single value or a comma-delimited collection of values as input. e.g. =’matchedCity,primaryStreet’
out_fields
Optional String. A string of comma seperated fields names used to limit the return attributes of a geocoded location.
# Usage Example >>> batched = batch_geocode(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"] as_featureset = True, match_out_of_range = True, ) >>> type(batched) <:class:`~arcgis.features.FeatureSet>
- Returns
A dictionary or
FeatureSet
suggest
-
arcgis.geocoding.
suggest
(text, location=None, distance=None, category=None, geocoder=None, search_extent=None, max_suggestions=5, country_code=None) The
suggest
method retrieves 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.
Note
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.
Note
Only
geocoders
published using ArcGIS 10.3 for Server orlater 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.Parameter
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
Optional x/y dictionary. 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.
Note
The
location
parameter can be specified without specifying adistance
. If distance is not specified, it defaults to 2000 meters.distance
Optional float. 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.
Note
If the
distance
parameter is specified, thelocation
parameter must be specified as well.It is important to note that the
location
anddistance
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
Geocoder
- the geocoder to be used. If not specified, the activeGIS
object’s first geocoder is used.search_extent
Optional String/Dict. A set of bounding box coordinates that limit the search area to a specific region. You can specify the spatial reference of the search_extent coordinates, which is necessary if the map spatial reference is different than that of the geocoding service; otherwise, the spatial reference of the map coordinates is assumed to be the same as that of the geocoding service. The input can either be a comma-separated list of coordinates defining the bounding box or a JSON envelope object.
Note
The
search_extent
coordinates should always use a period as the decimal separator, even in countries where traditionally a comma is used.max_suggestions
Optional Int. The maximum number of suggestions returned by the suggest operation, up to the maximum number allowed by the service.
Note
If
maxSuggestions
is not included in the suggest request, the default value is 5. The maximum suggestions value can be modified in the source address locator.country_code
Optional Str. Limits the returned suggestions to values in a particular country. Valid two- and three-character country code values for each country are available in geocode coverage.
Note
When the
country_code
parameter is specified in a suggest request, the correspondinggeocode
call must also include thecountry_code
parameter with the same value.# Usage Example >>> suggested = suggest(text = "geocoding_text" location = point1, distance = 5000, max_suggestions = 10 ) >>> type(suggested) <Dictionary>
- Returns
A dictionary