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 generatebatch results for a set of addresses, as well as for reverse geocoding,i.e. determining the address at a particular x/y location.
Geocoder
- classarcgis.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 generatebatch 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 usingget_geocoders(gis).Note
Geocoders
shared asItem
objects in the GIS can be obtained usingGeocoder.fromitem(item).Note
Geocoder
objects may also be created using the constructor by passing in their location, such asa url to aGeocodingService
.- batch_geocode(addresses:list,source_country:str|None=None,category:str|None=None,out_sr:str|None=None,as_featureset:bool|None=False,match_out_of_range:bool|None=True,location_type:str|None='street',search_extent:str|None=None,lang_code:str|None='EN',preferred_label_values:str|None=None,out_fields:str|None=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 textmultifield batch geocoding - use the address fields describedin the Geocoder documentation.
Note
The maximum number of addresses that can be geocoded in asingle request is limited to the SuggestedBatchSize property ofthe 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 isonly supported by geocoders published using StreetMapPremium locators.Note
Added at 10.3 and only supported by geocoders publishedwith ArcGIS 10.3 for Server and later versions.
category
Optional String. The
category
parameter is only supported by geocodeservices published using StreetMap Premium locators.out_sr
Optional dictionary, The spatial reference of thex/y coordinates returned by a geocode request. Thisis useful for applications using a map with a spatialreference different than that of the geocode service.
as_featureset
Optional boolean, if True, the result set isreturned as a FeatureSet object, else it is adictionary.
match_out_of_range
Optional, A Boolean which specifies if StreetAddress matches shouldbe returned even when the input house number is outside of the housenumber range defined for the input street.
location_type
Optional, Specifies if the output geometry of PointAddress matchesshould be the rooftop point or street entrance location. Valid valuesare rooftop and street.
search_extent
Optional, a set of bounding box coordinates that limit the searcharea to a specific region. The input can either be a comma-separatedlist of coordinates defining the bounding box or a JSON envelopeobject.
lang_code
Optional, sets the language in which geocode results are returned.See the table of supported countries for valid language code valuesin each country.
preferred_label_values
Optional, allows simple configuration of output fields returnedin a response from the World Geocoding Service by specifying whichaddress component values should be included in output fields. Supportsa single value or a comma-delimited collection of values as input.e.g. =’matchedCity,primaryStreet’
out_fields
Optional String. A string of comma separated fields names used tolimit 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
- classmethodfromitem(item:Item)
The
fromitem
method creates aGeocoder
from anItem
in theclass:~arcgis.gis.GIS instance.Parameter
Description
item
A required
Item
object. TheItem
to convert to aGeocoder
object.Note
The
Item
must be of typeGeocodingService
.- Returns:
A
Geocoder
object.
- 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,as_featureset=False,match_out_of_range=True,location_type='street',lang_code=None,source_country=None)
The geocode method geocodes one location per request.
Parameter
Description
address
Required list of strings or dictionaries.Specifies the location to be geocoded. This can bea string containing the street address, place name,postal code, or POI.
Alternatively, this can be a dictionary containingthe various address fields accepted by thecorresponding geocoder. These fields are listed inthe addressFields property of the associatedgeocoder. For example, if the address_fields of ageocoder includes fields with the following names:Street, City, State and Zone, then the addressargument 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 coordinatesthat limit the search area to a specific region.This is especially useful for applications in whicha user will search for places and addresses onlywithin the current map extent.
location
Optional [x,y]. Defines an origin point location thatis used with the distance parameter to sortgeocoding candidates based upon their proximity tothe location.
distance
Optional float. Specifies the radius of an areaaround a point location which is used to boost therank of geocoding candidates so that candidatesclosest to the location are returned first. Thedistance value is in meters.
out_sr
Optional dictionary. The spatial reference of thex/y coordinates returned by a geocode request. Thisis useful for applications using a map with a spatialreference different than that of the geocode service.
category
Optional string. A place or address type which canbe used to filter find results. The parametersupports input of single category values or multiplecomma-separated values. The category parameter can bepassed in a request with or without the textparameter.
out_fields
Optional string. Name of all the fields to include.The default is “*” which means all fields.
max_locations
Optional integer. The number of locations to bereturned from the service. The default is 20.
magic_key
The find operation retrieves results quicker whenyou pass a valid text and magickey value.
for_storage
Specifies whether the results of the operation willbe persisted. The default value is false, whichindicates the results of the operation can’t bestored, but they can be temporarily displayed on amap for instance. If you store the results, in adatabase for example, you need to set this parameterto true.
as_featureset
Optional boolean. If True, the result set will be aFeatureSet instead of a dictionary. False is default
match_out_of_range
Optional Boolean. Provides better spatial accuracyfor inexact street addresses by specifying whethermatches will be returned when the input number isoutside of the house range defined for the inputstreet. Out of range matches will be defined asAddr_type=StreetAddressExt. Input house numbersthat exceed the range on a street segment by morethan 100 will not result inStreetAddressExtmatches. The default value of this parameter isTrue.
location_type
Optional Str. Specifies whether the rooftop point orstreet entrance is used as the output geometry ofPointAddress matches. By default, street is used,which is useful in routing scenarios, as the rooftoplocation of some addresses may be offset from astreet by a large distance. However, for map displaypurposes, you may want to use rooftop instead,especially when large buildings or landmarks aregeocoded. Thelocation_type parameter only affectsthe location object in the JSON response and doesnot change the x,y or DisplayX/DisplayY attributevalues.
Values:street orrooftop
lang_code
Optional str. Sets the language in which geocoderesults are returned.
source_country
Optional str. Limits the returned candidates to thespecified country or countries for either single-fieldor multifields requests. Acceptable values includethe 3-character country code.
- Returns:
dictionary or FeatureSet
- reverse_geocode(location,distance=None,out_sr=None,lang_code=None,return_intersection=False,for_storage=False,as_featureset=False,feature_types=None,location_type='street')
The
reverse_geocode
operation determines the address at a particularx/y location. You pass the coordinates of a point location to thegeocoding service, and the service returns the address that isclosest 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 tosearch for an address.
Note
The default for
distance
is 100 meters.out_sr
optional integer or
SpatialReference
of thex/y coordinate returned.lang_code
optional string. Sets the language in which geocoderesults are returned. This is useful for ensuringthat results are returned in the expected language.If the lang_code parameter isn’t included in arequest, or if it is included but there are nomatching features with the input language code, theresultant match is returned in the language code ofthe primary matched components from the input searchstring.
return_intersection
optional Boolean, which specifies whether theservice should return the nearest streetintersection or the nearest address to the inputlocation
for_storage
optional boolean, specifies whether the results ofthe operation will be persisted
feature_types
Optional String. Limits the possible match typesperformed by thereverse_geocode method. If asingle value is included, the search tolerance forthe input feature type is 500 meters. If multiplevalues (separated by a comma, with no spaces) areincluded, the default search distances specified inthe feature type hierarchy table are applied.
- Values:`StreetInt, DistanceMarker, StreetAddress,
StreetName, POI, PointAddress, Postal, andLocality`
location_type
Optional string. Specifies whether the rooftop pointor street entrance is used as the output geometry ofpoint address matches. By default,
street
is used,which is useful in routing scenarios, as the rooftoplocation of some addresses may be offset from astreet by a large distance. However, for map displaypurposes, you may want to userooftop
instead,especially when large buildings or landmarks aregeocoded. Thelocation_type
parameter onlyaffects the location object in the JSON responseand 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
- suggest(text:str,location:tuple|Point|None=None,category:str=None,search_extent:tuple|Envelope|None=None,max_suggestions:int=5,country_code:str=None,preferred_label_values:str|None=None,return_collections:bool=True,distance:float|None=None)
The
suggest
method retrieves a resource representing a list ofsuggested matches for the input text. This resource provides thematching text as well as a unique ID value, which links asuggestion to a specific place or address.A geocoder must meet the following requirements to supportthe suggest operation:The address locator from which the geocoder was published
must support suggestions.
Note
Only address locators created usingArcGIS 10.3 for Desktop and later can support suggestions. Seethe Create Address Locator geoprocessing tool help topic for moreinformation.
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-completesuggestions to be generated for user input in a client application.This capability facilitates the interactive search user experienceby reducing the number of characters that need to be typed beforea suggested match is obtained. A client application can provide alist of suggestions that is updated with each character typed by auser until the address they are looking for appears in the list.# Usage Example>>>suggested=suggest(text="geocoding_text"location=point1,distance=5000,max_suggestions=10)>>>type(suggested)<Dictionary>
- Returns:
A dictionary
PlacesAPI
- classarcgis.geocoding.PlacesAPI(gis:GIS)
The places service is a ready-to-use location service that can searchfor businesses and geographic locations around the world. It allowsyou to find, locate, and discover detailed information about each place.
- examine_category(category:str)→dict[str,Any]
Get the category details for a category ID.
Parameter
Description
category
Required String. The category ID to examine.
- Returns:
Dictionary
- find_category(query:str)→dict[str,Any]
Return the name and category ID of all categories, or categorieswhich 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) ofplace. The categories fall into ten general groups: Arts andEntertainment, Business and Professional Services, Community andGovernment, Dining and Drinking, Events, Health and Medicine,Landmarks and Outdoors, Retail, Sports and Recreation, and Traveland Transportation.
Parameter
Description
query
Required String. The filter string used to find the matchingcategories.
- Returns:
Dictionary
- get_place_by_id(placeid:str,filters:list[PlaceIdEnums]|None=None)→dict[str,Any]
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:list[float]|list[int],categories:list[str]|None=None,search_text:str|None=None,page_size:int=10)→Iterator[dict[str,Any]]
Search for places within an extent (bounding box).
Parameter
Description
bbox
list/tuple[float]. The min X/Y and max X/Y coordinates tosearch 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:list[float]|list[int],radius:float|int=1000,categories:list[str]|None=None,search_text:str|None=None,page_size:int=10)→Iterator[dict[str,Any]]
Search for places near a point or location by radius.
Parameter
Description
point
list/tuple[float]. The X/Y coordinates centroid to search byradius 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: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 bequeried.- Returns:
A list of
Geocoder
objects registered with theGIS
.
geocode
- geocoding.geocode(search_extent:str|None=None,location:list|tuple|None=None,distance:int|None=None,out_sr:dict[str,Any]|None=None,category:str|None=None,out_fields:str='*',max_locations:int=20,magic_key:str|None=None,for_storage:bool=False,geocoder:Geocoder|None=None,as_featureset:bool=False,match_out_of_range:bool=True,location_type:str='street',lang_code:str|None=None,source_country:str|None=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 bea string containing the street address, place name,postal code, or POI.
Alternatively, this can be a dictionary containingthe various address fields accepted by thecorresponding geocoder. These fields are listed inthe addressFields property of the associatedgeocoder. For example, if the address_fields of ageocoder includes fields with the following names:Street, City, State and Zone, then the addressargument 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 coordinatesthat limit the search area to a specific region.This is especially useful for applications in whicha user will search for places and addresses onlywithin the current map extent.
location
Optional [x,y], Defines an origin point location thatis used with the distance parameter to sortgeocoding candidates based upon their proximity tothe location.
distance
Optional float, Specifies the radius of an areaaround a point location which is used to boost therank of geocoding candidates so that candidatesclosest to the location are returned first. Thedistance value is in meters.
out_sr
Optional dictionary, The spatial reference of thex/y coordinates returned by a geocode request. Thisis useful for applications using a map with a spatialreference different than that of the geocode service.
category
Optional string, A place or address type which canbe used to filter find results. The parametersupports input of single category values or multiplecomma-separated values. The category parameter can bepassed in a request with or without the textparameter.
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 bereturned from the service. The default is 20.
magic_key
Optional string. The find operation retrievesresults quicker when you pass a valid text andmagic_key value.
for_storage
Optional Boolean. Specifies whether the results ofthe operation willbe persisted. The default value is false, whichindicates the results of the operation can’t bestored, but they can be temporarily displayed on amap for instance.
Note
If you store the results, in adatabase for example, you need to set this parameterto
True
.geocoder
Optional, the
Geocoder
tobe used.Note
If not specified, the active
GIS
object’sfirst geocoder is used.as_featureset
Optional boolean, If
True
, the result set isreturned as aFeatureSet
object, else it is a dictionary.match_out_of_range
Optional Boolean. Provides better spatial accuracyfor inexact street addresses by specifying whethermatches will be returned when the input number isoutside of the house range defined for the inputstreet. Out of range matches will be defined asAddr_type=StreetAddressExt. Input house numbersthat exceed the range on a street segment by morethan 100 will not result inStreetAddressExtmatches. The default value of this parameter isTrue.
location_type
Optional Str. Specifies whether the rooftop point orstreet entrance is used as the output geometry ofPointAddress matches. By default, street is used,which is useful in routing scenarios, as the rooftoplocation of some addresses may be offset from astreet by a large distance. However, for map displaypurposes, you may want to use rooftop instead,especially when large buildings or landmarks aregeocoded. Thelocation_type parameter only affectsthe location object in the JSON response and doesnot change the x,y or DisplayX/DisplayY attributevalues.
Values:street orrooftop
lang_code
Optional str. Sets the language in which geocoderesults are returned.
source_country
Optional str. Limits the returned candidates to thespecified country or countries for either single-fieldor multifield requests. Acceptable values includethe 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)<classarcgis.features.FeatureSet>
- Returns:
A dictionary or
FeatureSet
object.
geocode_from_items
- arcgis.geocoding.geocode_from_items(input_data:Item|str|FeatureLayer,output_type:str='FeatureLayer',geocode_service_url:str|Geocoder|None=None,geocode_parameters:dict[str,Any]|None=None,country:str|None=None,output_fields:str|None=None,header_rows_to_skip:int=1,output_name:str|None=None,category:str|None=None,context:dict[str,Any]|None=None,gis:GIS|None=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 tospatially enable the dataset.geocode_parameters
optional dictionary. This includes parameters that help parsethe 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 importantto inspect the field mapping closely and adjust them accordinglybefore submitting your job, otherwise your geocoding results maynot be accurate. It is recommended to use the output fromanalyze_geocode_input
and modify the field mapping instead ofconstructing this dictionary by hand.Values
field_info
- A list of triples with the field names of your inputdata, 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 datadoes not have a header row.field_mapping
- Field mapping between each input field andcandidate 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 helpsimprove performance for locators that accept that variable.
output_fields
optional string. Enter the output fields from the geocodingservice that you want returned in the results, separated bycommas. To output all available outputFields, leave thisparameter blank.
Example: score,match_addr,x,y
header_rows_to_skip
optional integer. Describes on which row your data begins inyour file or table. The default is 1 (since the first rowcontains the headers). The default is 1.
output_name
optional string, The task will create a feature service of theresults. You define the name of the service.
category
optional string. Enter a category for more precise geocodingresults, if applicable. Some geocoding services do not supportcategory, and the available options depend on your geocode service.
context
optional dictionary. Context contains additional settings thataffect task execution. Batch Geocode has the following twosettings:
Extent (extent) - A bounding box that defines the analysisarea. Only those points in inputLayer that intersect thebounding box are analyzed.
Output Spatial Reference (outSR) - The output features areprojected into the output spatial reference.
Syntax:{“extent” : {extent}“outSR” : {spatial reference}}
gis
optional
GIS
, theGIS
on which thistool 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:Item|str|dict[str,str],geocode_service_url:str|Geocoder|None=None,column_names:str|None=None,input_file_parameters:dict[str,str]|None=None,locale:str='en',context:dict[str,Any]|None=None,gis:GIS|None=None)
The
analyze_geocode_input
function takes in a geocode input (either a table or file ofaddresses) 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. Thetask generates a suggested field mapping based on the input fields and the geocoding servicecandidate fields and returns it in ageocode_parameters
dictionary. Thisgeocode_parameters
dictionary output is the an input to theBatchGeocode
tool. The outputgeocode_parameters
dictionary also includes field info (name, length, and type) as well as additional informationthat 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 ofthe item in the portal. The format of the item in the portalcan 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 servicethat you want to geocode your addresses against.column_names
Optional string. Only used when input table or
Item
has noheader row.Example: address,city,state,zipinput_file_parameters
Optional dictionary. Enter information about how to parse thefile. If you are using an input table instead of an Item asinput, this parameter can be left blank.Any of the key values in the dictionary can be left blank usingthe “”.
Values:
fileType
- Enter CSV or XLS for the file format of fileItem.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 thanEnglish.
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 thebounding box are analyzed.
Output Spatial Reference (outSR) - The output features areprojected into the output spatial reference.
gis
Optional
GIS
. Connection to the site. If None is given, theactiveGIS
is used.- Returns:
A dictionary
reverse_geocode
- arcgis.geocoding.reverse_geocode(location:list|dict|Point,distance:float|None=None,out_sr:int|SpatialReference|None=None,lang_code:str|None=None,return_intersection:bool=False,for_storage:bool=False,geocoder:Geocoder|None=None,feature_types:str|None=None,location_top:str='street')
The
reverse_geocode
operation determines the address at a particularx/y location. You pass the coordinates of a point location to thegeocoding service, and the service returns the address that isclosest 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 tosearch for an address.
Note
The default for
distance
is 100 meters.out_sr
optional integer or
SpatialReference
of thex/y coordinate returned.lang_code
optional string. Sets the language in which geocoderesults are returned. This is useful for ensuringthat results are returned in the expected language.If the lang_code parameter isn’t included in arequest, or if it is included but there are nomatching features with the input language code, theresultant match is returned in the language code ofthe primary matched components from the input searchstring.
return_intersection
optional Boolean, which specifies whether theservice should return the nearest streetintersection or the nearest address to the inputlocation
for_storage
optional boolean, specifies whether the results ofthe operation will be persisted
geocoder
optional
Geocoder
,the geocoder to be used.Note
If not specified, the active
GIS
instancesfirstGeocoder
is used.feature_types
Optional String. Limits the possible match typesperformed by thereverse_geocode method. If asingle value is included, the search tolerance forthe input feature type is 500 meters. If multiplevalues (separated by a comma, with no spaces) areincluded, the default search distances specified inthe feature type hierarchy table are applied.
- Values:`StreetInt, DistanceMarker, StreetAddress,
StreetName, POI, PointAddress, Postal, andLocality`
location_type
Optional string. Specifies whether the rooftop pointor street entrance is used as the output geometry ofpoint address matches. By default,
street
is used,which is useful in routing scenarios, as the rooftoplocation of some addresses may be offset from astreet by a large distance. However, for map displaypurposes, you may want to userooftop
instead,especially when large buildings or landmarks aregeocoded. Thelocation_type
parameter onlyaffects the location object in the JSON responseand 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:list[str]|dict[str,str],source_country:str|None=None,category:str|None=None,out_sr:dict|None=None,geocoder:Geocoder|None=None,as_featureset:bool=False,match_out_of_range:bool=True,location_type:str='street',search_extent:list[dict[str,Any]]|dict[str,Any]|None=None,lang_code:str='EN',preferred_label_values:str|None=None,out_fields:str|None=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 textmultifield batch geocoding - use the address fields describedin the Geocoder documentation.
Note
The maximum number of addresses that can be geocoded in asingle request is limited to the SuggestedBatchSize property ofthe 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 isonly supported by geocoders published using StreetMapPremium locators.Note
Added at 10.3 and only supported by geocoders publishedwith ArcGIS 10.3 for Server and later versions.
category
Optional String. The
category
parameter is only supported by geocodeservices published using StreetMap Premium locators.out_sr
Optional dictionary, The spatial reference of thex/y coordinates returned by a geocode request. Thisis useful for applications using a map with a spatialreference different than that of the geocode service.
as_featureset
Optional boolean, if True, the result set isreturned as a FeatureSet object, else it is adictionary.
geocoder
Optional
Geocoder
,the geocoder to be used.Note
If not specified, the active
GIS
instancesfirstGeocoder
is used.match_out_of_range
Optional, A Boolean which specifies if StreetAddress matches shouldbe returned even when the input house number is outside of the housenumber range defined for the input street.
location_type
Optional, Specifies if the output geometry of PointAddress matchesshould be the rooftop point or street entrance location. Valid valuesare rooftop and street.
search_extent
Optional, a set of bounding box coordinates that limit the searcharea to a specific region. The input can either be a comma-separatedlist of coordinates defining the bounding box or a JSON envelopeobject.
lang_code
Optional, sets the language in which geocode results are returned.See the table of supported countries for valid language code valuesin each country.
preferred_label_values
Optional, allows simple configuration of output fields returnedin a response from the World Geocoding Service by specifying whichaddress component values should be included in output fields. Supportsa single value or a comma-delimited collection of values as input.e.g. =’matchedCity,primaryStreet’
out_fields
Optional String. A string of comma separated fields names used tolimit 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:str,location:dict[str,Any]|None=None,category:str|None=None,geocoder:Geocoder|None=None,search_extent:list[dict[str,Any]]|dict[str,Any]|None=None,max_suggestions:int=5,country_code:str|None=None,preferred_label_values:str|None=None,return_collections:bool=True)→dict
The
suggest
method retrieves a resource representing a list ofsuggested matches for the input text. This resource provides thematching text as well as a unique ID value, which links asuggestion to a specific place or address.A geocoder must meet the following requirements to supportthe suggest operation:- 1.) The address locator from which the geocoder was published
must support suggestions.
Note
Only address locators created usingArcGIS 10.3 for Desktop and later can support suggestions. Seethe Create Address Locator geoprocessing tool help topic for moreinformation.
2.) 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-completesuggestions to be generated for user input in a client application.This capability facilitates the interactive search user experienceby reducing the number of characters that need to be typed beforea suggested match is obtained. A client application can provide alist of suggestions that is updated with each character typed by auser 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 thesuggest operation to generate a list of possiblematches. This is a required parameter.
location
Optional tuple[float, float] | Point. Defines an origin pointlocation that is used with the distance parameter to sortsuggested candidates based on their proximity to the location.Thesearch_extent parameter specifies the radial distance fromthe location in meters. The priority of candidates within thisradius is boosted relative to those outside the radius.This is useful in mobile applications where a userwants to search for places in the vicinity of theircurrent GPS location. It is also useful for webmapping applications where a user wants to findplaces within or near the map extent.
Note
The
location
parameter can be specified withoutspecifying adistance
. If distance is not specified,it defaults to 2000 meters.category
The category parameter is only supported by geocodeservices published using StreetMap Premium locators.
geocoder
Optional
Geocoder
- the geocoder tobe used. If not specified, the activeGIS
object’s first geocoder is used.search_extent
Optional String/Dict. A set of bounding box coordinates thatlimit the search area to a specific region. You can specify thespatial reference of thesearch_extent coordinates, which isnecessary if the map spatial reference is different than that ofthe geocoding service; otherwise, the spatial reference of themap coordinates is assumed to be the same as that of thegeocoding service. The input can either be a comma-separated listof coordinates defining the bounding box or a JSON envelopeobject.
Note
The
search_extent
coordinates should always use aperiod as the decimal separator, even in countries wheretraditionally a comma is used.max_suggestions
Optional Int. The maximum number of suggestions returned by thesuggest operation, up to the maximum number allowed by theservice.
Note
If
maxSuggestions
is not included in the suggestrequest, the default value is 5. The maximum suggestions valuecan be modified in the source address locator.country_code
Optional Str. Limits the returned suggestions to values in aparticular country. Valid two- and three-character country codevalues for each country are available in geocode coverage.
Note
When the
country_code
parameter is specified in asuggest request, the correspondinggeocode
call mustalso include thecountry_code
parameter with thesame value.preferred_label_values
Optional str. Allows simple configuration of suggestion labelsreturned in a response from the geocode service by specifyingwhich address component values should be included in the label. Asingle value is supported as input. If the parameter is blank orexcluded from a request, the default address formats are used.
return_collections
Optional Boolean. The parameter is used to prevent collectionsfrom being returned in suggest responses. The default value isTrue, which means that collections are included in suggestresponses by default.
# Usage Example>>>suggested=suggest(text="geocoding_text"location=point1,distance=5000,max_suggestions=10)>>>type(suggested)<Dictionary>
- Returns:
A dictionary