GeezerVison

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.

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 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.
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 separated 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

classmethod fromitem(item: Item)

The fromitem method creates a Geocoder from an Item in the class:~arcgis.gis.GIS instance.

Parameter	Description
item	A required Item object. The Item to convert to a Geocoder object. Note The Item must be of type Geocoding Service.

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 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_locations	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.
as_featureset	Optional boolean. If True, the result set will be a FeatureSet instead of a dictionary. False is default
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 multifields requests. Acceptable values include the 3-character country code.

Returns:

dictionary or FeatureSet

property properties

The properties property retrieves and set properties of this object.

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 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
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 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, 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 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:

1. 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.

2. The geocoder must have the Suggest capability enabled.

Note

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.

# Usage Example
>>> suggested = suggest(text = "geocoding_text"
                                location = point1,
                                distance = 5000,
                                max_suggestions = 10
                                )
>>> type(suggested)
<Dictionary>

Returns:

A dictionary

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: 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 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: 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 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: 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 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]

When obtaining a single place by ID, the enumerations can filter and return specific information about a specific place ID. To obtain a place ID, you must perform a query first.

ADDITIONALLOCATIONS = 'additionalLocations'

ADDITIONALLOCATIONS_DROPOFF = 'additionalLocations:dropOff'

ADDITIONALLOCATIONS_FRONTDOOR = 'additionalLocations:frontDoor'

ADDITIONALLOCATIONS_ROAD = 'additionalLocations:road'

ADDITIONALLOCATIONS_ROOF = 'additionalLocations:roof'

ADDRESS = 'address'

ADDRESS_ADMINREGION = 'address:adminRegion'

ADDRESS_CENSUSBLOCKID = 'address:censusBlockId'

ADDRESS_COUNTRY = 'address:country'

ADDRESS_DESIGNATEDMARKETAREA = 'address:designatedMarketArea'

ADDRESS_EXTENDED = 'address:extended'

ADDRESS_LOCALITY = 'address:locality'

ADDRESS_NEIGHBORHOOD = 'address:neighborhood'

ADDRESS_POBOX = 'address:poBox'

ADDRESS_POSTCODE = 'address:postcode'

ADDRESS_POSTTOWN = 'address:postTown'

ADDRESS_REGION = 'address:region'

ADDRESS_STREETADDRESS = 'address:streetAddress'

ALL = 'all'

CATEGORIES = 'categories'

CHAINS = 'chains'

CONTACTINFO = 'contactInfo'

CONTACTINFO_EMAIL = 'contactInfo:email'

CONTACTINFO_FAX = 'contactInfo:fax'

CONTACTINFO_TELEPHONE = 'contactInfo:telephone'

CONTACTINFO_WEBSITE = 'contactInfo:website'

DESCRIPTION = 'description'

HOURS = 'hours'

HOURS_OPENING = 'hours:opening'

HOURS_OPENINGTEXT = 'hours:openingText'

HOURS_POPULAR = 'hours:popular'

LOCATION = 'location'

NAME = 'name'

RATING = 'rating'

RATING_PRICE = 'rating:price'

RATING_USER = 'rating:user'

SOCIALMEDIA = 'socialMedia'

SOCIALMEDIA_FACEBOOKID = 'socialMedia:facebookId'

SOCIALMEDIA_INSTAGRAM = 'socialMedia:instagram'

SOCIALMEDIA_TWITTER = 'socialMedia:twitter'

The get_geocoders method is used to query the list of geocoders registered with the GIS.

Parameters:

gis – the GIS whose registered geocoders are to be queried

Returns:

A list of Geocoder objects registered with the GIS.

The geocode function geocodes one location per request.

# 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.

The geocode_from_items method creates Geocoder objects from an Item or Layer objects.

# 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.

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.

Returns:

A dictionary

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.

# 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

The batch_geocode function geocodes an entire list of addresses.

# 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

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:

1.) The address locator from which the geocoder was published

must support suggestions.

2.) The geocoder must have the Suggest capability enabled.

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.

# Usage Example
>>> suggested = suggest(text = "geocoding_text"
                                location = point1,
                                distance = 5000,
                                max_suggestions = 10
                                )
>>> type(suggested)
<Dictionary>

Returns:

A dictionary

Returns the PlacesAPI class for a given GIS object

Returns:

An instance of the PlacesAPI for the GIS