Skip to main content

Locator

Summary

The Locator class allows you to modify locators and use them for geocoding. Geocoding is the process of transforming a description of a location—such as a pair of coordinates, an address, or a name of a place—to a location on the earth's surface.

The Geocoding module supports locators created with the Create Locator tool. Locators created with legacy tools may have limited functionality, and a number of properties and parameters are not supported.

Discussion

A locator is a portable file used to perform geocoding, which is the process of finding addresses and places on a map. Locators contain a snapshot of the reference data used for geocoding, as well as indexes and local addressing information that help return the best match during the geocoding process.

A locator can be accessed as a service on your portal, such as ArcGIS World Geocoding Service, as a service accessed through an ArcGIS Server connection, or as a file on disk.

Syntax

Locator(path)

Name Explanation Data type

path

The path to the locator.

String

Properties

Name Explanation Data type

capabilities

(Read only)

Specifies the capabilities that are available for a locator that is shared as a service to ArcGIS Enterprise or published as a geocode service to ArcGIS Server. The available capabilities are as follows:

  • FindAddressCandidates—If this value is included in the property, the geocode service supports finding a location for an address or place.

    Note:

    FindAddressCandidates is only available when sharing a locator to ArcGIS Enterprise 11.5 or later. This operation will not be recognized by ArcGIS Enterprise 11.4 or earlier.

  • GeocodeAddresses—If this value is included in the property, the geocode service supports geocoding a table of addresses.

    Note:

    GeocodeAddresses is only available when sharing a locator to ArcGIS Enterprise 11.5 or later. This operation will not be recognized by ArcGIS Enterprise 11.4 or earlier.

  • Geocode—If this value is included in the property, the geocode service supports geocoding operations, finding a location for an address or place, and geocoding a table of addresses.

  • ReverseGeocode—If this value is included in the property, the geocode service supports reverse geocoding operations, and finding the closest place or address to a given location.

  • Suggest—If this value is included in the property, the geocode service supports generating autocomplete suggestions from input.

A single string containing all supported capabilities will be returned for this property.

This property is only supported for geocode services. It is not supported for local locators, and an error will be returned if you attempt to access this property for a local locator.

String

categories

(Read and Write)

Controls precision by limiting the categories that can be returned from the locator to a defined set. If you have a multirole locator that supports multiple address types, you can modify this property to exclude matches to certain types. For example, a locator supports matches to PointAddress level, StreetAddress level, StreetName level, and Postal level, and you want to exclude matches to the Postal level. This setting allows you to control the precision of the results.

This property is read-only for geocode services. To change this property in a published locator, modify the property locally, and publish the locator again.

Note:

This property is set as a run-time property only. It is not persisted to the locator outside of the current session unless you use the updateLocator method.

String

compatibilityVersion

(Read only)

The earliest version of ArcGIS Pro with which the locator is compatible. The locator will also only be supported in the corresponding versions of ArcGIS Server and ArcGIS Enterprise. For example, a value of 3.4 will only be supported in ArcGIS Pro 3.4 or later and ArcGIS Server and ArcGIS Enterprise 11.4 or later.

String

comprehensiveZoneMatch

(Read and Write)

Specifies whether input addresses that do not exactly match the city name will return candidates from the geocode and geocodeWithSuggest methods. The default is True.

When this property is set to True, addresses will match even when the city name is incorrect. When this property is set to False, no match will be returned or the match will have a significantly lower score. For more information about how to use this property, see Comprehensive zone matching.

This property is read-only for geocode services. To change this property in a published locator, modify the property locally, and publish the locator again.

Note:

This property is set as a run-time property only. It is not persisted to the locator outside of the current session unless you use the updateLocator method.

Boolean

defaultLocationType

(Read and Write)

Specifies the preferred output geometry for POINT_ADDRESS matches returned from the geocode, geocodeWithSuggest, and reverseGeocode methods.

The options for this parameter are Routing_Location, which is the side of street location that can be used for routing, and Address_Location, which is the location that represents the rooftop, parcel centroid, or front door of the address. If the preferred location does not exist in the data, the default location of Address_Location will be returned instead. For geocode results with Addr_type = PointAddress, the x,y attribute values describe the coordinates of the address along the street, and the DisplayX and DisplayY values describe the rooftop or building centroid coordinates. For more information about how to use this property, see Preferred location type.

This property is read-only for geocode services. To change this property in a published locator, modify the property locally, and publish the locator again.

Note:

This property is set as a run-time property only. It is not persisted to the locator outside of the current session unless you use the updateLocator method.

String

defaultSuggestCandidates

(Read and Write)

The number of suggestion candidates that will be returned by default from the suggest method.

This property is read-only for geocode services. To change this property in a published locator, modify the property locally, and publish the locator again.

Note:

This property is set as a run-time property only. It is not persisted to the locator outside of the current session unless you use the updateLocator method.

Integer

endOffset

(Read and Write)

The distance in meters that will be used to offset the result away from the end (toward the center) of a street feature for display purposes. For more information about how to use this property, see End offset.

This property is read-only for geocode services. To change this property in a published locator, modify the property locally, and publish the locator again.

Note:

This property is set as a run-time property only. It is not persisted to the locator outside of the current session unless you use the updateLocator method.

Double

excludeIntersectionType

(Read and Write)

Specifies which intersection types will be excluded from locator search results. Virtual is the supported value for this property. For more information about how to use this property, see Exclude intersection type.

Note:

This property is set as a run-time property only. It is not persisted to the locator outside of the current session unless you use the updateLocator method.

String

intersectionConnectors

(Read and Write)

The list of intersection connectors, which can be symbols or words, that will be used to override the default intersection connectors. Use a quoted comma-separated list to list the intersection connectors, for example, "&","|","//","@".

This property is read-only for geocode services. To change this property in a published locator, modify the property locally, and publish the locator again.

Note:

This property is set as a run-time property only. It is not persisted to the locator outside of the current session unless you use the updateLocator method.

String

matchOutOfRange

(Read and Write)

Specifies whether a match will be returned if the street number searched for is slightly out of range of what is included in the street segment of the data on which the locator was built.

To match to a street segment, even if the street number doesn't exist on the line segment in the data but is within a reasonable threshold and is likely to exist, set the property to True. When this property is set to True, the point is placed on the end of the street segment where the address is slightly outside of the house number range. This ensures that you do not miss a potential match because the data is not 100 percent up to date.

This property only applies to locators that support and return StreetAddress matches. For more information about this property, see Match out of range.

This property is read-only for geocode services. To change this property in a published locator, modify the property locally, and publish the locator again.

Note:

This property is set as a run-time property only. It is not persisted to the locator outside of the current session unless you use the updateLocator method.

Boolean

maxCandidates

(Read and Write)

The maximum number of candidates that will be returned from the geocode method.

If geocoding is taking a long time and you are getting high-quality matches, ensure that this property is not set too high. If you are getting good results, performance can be improved by generating fewer results and focusing on the top few.

This property is read-only for geocode services. To change this property in a published locator, modify the property locally, and publish the locator again.

Note:

This property is set as a run-time property only. It is not persisted to the locator outside of the current session unless you use the updateLocator method.

Integer

maxSuggestCandidates

(Read and Write)

The maximum number of suggestion results that will be returned from the suggest method.

If the suggest method is performing poorly, it may be because the locator is generating a very large number of suggestion results. Setting this value to a lower number can improve performance. For more information about this property, see Maximum number of suggest candidates.

This property is read-only for geocode services. To change this property in a published locator, modify the property locally, and publish the locator again.

Note:

This property is set as a run-time property only. It is not persisted to the locator outside of the current session unless you use the updateLocator method.

Integer

minCandidateScore

(Read and Write)

The minimum score that a result must have to be considered a match candidate for the geocode operation. The minimum score for a locator is a value between 0 and 100. Only candidates that meet or exceed the minimum candidate score will be returned from the geocode method.

This property is read-only for geocode services. To change this property in a published locator, modify the property locally, and publish the locator again.

Note:

This property is set as a run-time property only. It is not persisted to the locator outside of the current session unless you use the updateLocator method.

Integer

minMatchScore

(Read and Write)

The minimum score that a geocode method result must have to be considered a match.

The minimum score is a threshold that allows you to control how closely addresses must match their most likely candidate in the reference data to be considered a match. If the potential candidate is below the threshold, the address is not matched to the candidate.

The minimum match score for a locator is a value between 0 and 100. A perfect match yields a score of 100. If your workflows require matched addresses with a high level of confidence, set the property to a higher threshold. A higher setting ensures that only the highest-quality matches are returned. To maximize the number of addresses that can be matched, and if you do not mind if some addresses are potentially matched incorrectly, use a lower threshold setting.

This property is read-only for geocode services. To change this property in a published locator, modify the property locally, and publish the locator again.

Note:

This property is set as a run-time property only. It is not persisted to the locator outside of the current session unless you use the updateLocator method.

Integer

multilineInputFields

(Read only)

The locator fields for multiline geocoding. This property returns a list of arcpy.Field objects for the multiline input fields for the locator. Multiline geocoding table fields can be mapped to a Field object name property when geocoding a table.

Field

numberOfThreads

(Read and Write)

The number of threads that will be used for batch geocoding.

For optimal use of this property, determine the number of physical cores available on your machine that you can devote to a geocoding job. All of the physical cores on a machine can be used to complete a geocoding job more quickly. By default, this value is set to a smaller number that should work on any machine regardless of the number of physical cores available, but it can be configured to use more physical cores if you know they are available. For example, to detect the physical cores on your machine and optimize the number of threads used, use numberOfThreads = 0, which is equivalent to selecting Auto on the Locator Properties dialog box of the locator. The number of physical cores used for geocoding can also specified, for example, numberOfThreads = 2, if you need other resources available for other applications.

If you plan to share the locator to ArcGIS Enterprise, it is recommended that you set the value to 4.

This property is read-only for geocode services. To change this property in a published locator, modify the property locally, and publish the locator again.

Note:

This property is set as a run-time property only. It is not persisted to the locator outside of the current session unless you use the updateLocator method.

Integer

partialHouseNumberSuggestions

(Read and Write)

Specifies whether suggestions will be returned for house numbers when only a partial house number value is entered. This option only applies to countries where the house number follows the street name. For more information about how to use this property, see Tips for improving geocoding quality.

This property is read-only for geocode services. To change this property in a published locator, modify the property locally, and publish the locator again.

Note:

This property is set as a run-time property only. It is not persisted to the locator outside of the current session unless you use the updateLocator method.

Boolean

partialSubaddressSuggestions

(Read and Write)

Specifies whether subaddresses will be returned by the suggest method when only a partial subaddress value is provided as input. For more information about how to use this property, see Suggestions for subaddresses.

This property is read-only for geocode services. To change this property in a published locator, modify the property locally, and publish the locator again.

Note:

This property is set as a run-time property only. It is not persisted to the locator outside of the current session unless you use the updateLocator method.

Boolean

preferredLabelValues

(Read and Write)

This property allows configuration of output fields returned in a response from the locator by specifying which address component values will be included in output fields. This property supports a single value or a comma-delimited string of values as input. For more information about how this property works, see Additional tuning options.

Possible values include postalCity, localCity, matchedCity, primaryStreet, and matchedStreet.

Note:

Only one value for city labeling and one value for street labeling can be included.

This property is read-only for geocode services. To change this property in a published locator, modify the property locally, and publish the locator again.

Note:

This property is set as a run-time property only. It is not persisted to the locator outside of the current session unless you use the updateLocator method.

String

returnCollections

(Read and Write)

Specifies whether collections (points of interest [POI] categories) will be returned by the suggest method when searching for POI. For more information about how to use this property, see Return collections.

The default setting is True. When this property is set to False, if the first character is associated with a category that exists in the data used to build a locator based on the POI role, the category name will not be included in the list of POI candidates returned.

This property is read-only for geocode services. To change this property in a published locator, modify the property locally, and publish the locator again.

Note:

This property is set as a run-time property only. It is not persisted to the locator outside of the current session unless you use the updateLocator method.

Boolean

returnInputLocation

(Read and Write)

Specifies whether the geometry returned by the reverseGeocode method is the original input geometry or the geometry of the returned matched address.

The default is False. When set to True, the reverseGeocode result will be returned with the original input geometry.

This property is read-only for geocode services. To change this property in a published locator, modify the property locally, and publish the locator again.

Note:

This property is set as a run-time property only. It is not persisted to the locator outside of the current session unless you use the updateLocator method.

Boolean

reverseDistance

(Read and Write)

The distance value in meters used to define the search area for the reverseGeocode method. Specifying a value will override the predefined search tolerances for the reverse feature type match returned.

The default option uses the predefined search tolerances. For more information about how to use this property, see Distance.

This property is read-only for geocode services. To change this property in a published locator, modify the property locally, and publish the locator again.

Note:

This property is set as a run-time property only. It is not persisted to the locator outside of the current session unless you use the updateLocator method.

Double

reverseOutputFields

(Read and Write)

The output fields that will be returned by the reverseGeocode method.

The default value is an empty string, which indicates that all output fields will be returned with reverseGeocode results. The value can be a string containing a comma delimited list of the subset of fields to be returned with reverseGeocode results.

This property is read-only for geocode services. To change this property in a published locator, modify the property locally, and publish the locator again.

Note:

This property is set as a run-time property only. It is not persisted to the locator outside of the current session unless you use the updateLocator method.

String

sideOffset

(Read and Write)

The distance in meters that will be used to offset the result away from and to the side of a street feature for display purposes. For more information about how to use this property, see Side offset.

This property is read-only for geocode services. To change this property in a published locator, modify the property locally, and publish the locator again.

Note:

This property is set as a run-time property only. It is not persisted to the locator outside of the current session unless you use the updateLocator method.

Double

singleLineInputField

(Read only)

The locator field for single-line geocoding. This property returns an arcpy.Field object representing the single-line input field for the locator. A single-line geocoding table field can be mapped to this Field object's name property when geocoding a table.

Field

spatialReference

(Read only)

The spatial reference of the locator. The spatial reference will be the same as the data used to create the locator.

Note:

This property is set as a run-time property only. It is not persisted to the locator outside of the current session unless you use the updateLocator method.

String

subaddressAfterBaseAddressSuggestions

(Read and Write)

Specifies whether suggestions will be returned for subaddresses after the base address is entered. When set to True, entering a full unit or a partial unit are also supported. A feature that represents the base address must be present in the locator to see the suggest candidates listed for the base address. For more information about how to use this property, see Tips for improving geocoding quality.

This property is read-only for geocode services. To change this property in a published locator, modify the property locally, and publish the locator again.

Note:

This property is set as a run-time property only. It is not persisted to the locator outside of the current session unless you use the updateLocator method.

Boolean

subaddressSummaryWithBaseAddress

(Read and Write)

Specifies whether a summary of the subaddress units at an address will be returned after the base address is entered. The summary of the subunits can be either a range of the subunit values based on the attributes in the reference data or the number of subunits at the address if there is a combination of unit types in the reference data or multiple subaddress elements mapped in the locator. A feature that represents the base address must be present in the locator to see the summary of the subunits after typing the base address. For more information about how to use this property, see Tips for improving geocoding quality.

This property is read-only for geocode services. To change this property in a published locator, modify the property locally, and publish the locator again.

Note:

This property is set as a run-time property only. It is not persisted to the locator outside of the current session unless you use the updateLocator method.

Boolean

supportedCategories

(Read only)

The categories that are supported by the locator. For more information about the supported categories available for custom-built locators and ArcGIS StreetMap Premium locators, see Categories to support.

String

supportedCountries

(Read only)

The countries that are supported by the locator.

String

supportedRoles

(Read only)

The roles that are supported by the locator.

String

reverseGeocodeFeatureTypes

(Read and Write)

The types of features that are supported for the reverseGeocode method. For more information about this property, see Features to support for reverse geocoding.

This property is read-only for geocode services. To change this property in a published locator, modify the property locally, and publish the locator again.

Note:

This property is set as a run-time property only. It is not persisted to the locator outside of the current session unless you use the updateLocator method.

String

Methods

geocode(searchText, forStorage, {preferredSearchLocation}, {countryCode}, {categories}, {locationType}, {outFields}, {maxResults}, {minScore}, {outputLanguageCode}, {preferredLabelValues}, {searchExtent}, {matchNarrative}, {searchWithin}, {start}, {num}, {matchID}, {comprehensiveZoneMatch}, {excludeIntersectionType})

Takes an address or location as input and returns geocoding result candidates. The result candidates are points that you can display on a map or use as input for other analyses.

Note:

If you are working with locators on your portal, ensure that you are signed in and have it set as your active portal in ArcGIS Pro. To access a locator that is on a portal other than your active portal, you can authenticate using SignInToPortal..

Name Explanation Data type

searchText

The address or place-name that will be used to find the location.

String

forStorage

Specifies whether the results will be stored. When set to False, the results can be temporarily displayed on a map. If you store the results—in a database, for example—set this argument to True.

This argument only applies to geocoding requests made with ArcGIS World Geocoding Service. For all other locators, it is ignored.

Note:

Applications are contractually prohibited from storing the results of geocoding operations using ArcGIS World Geocoding Service unless they make the request by passing this argument with a value of True. For a locator using ArcGIS World Geocoding Service to be valid, you must sign in to ArcGIS Online with a valid organizational account. ArcGIS Online service credits are deducted from the organizational account for each geocode transaction.

Boolean

preferredSearchLocation

(Optional)

The origin point that will be used to prefer or boost geocoding candidates based on their proximity to the location. Candidates near the location are prioritized relative to those farther away.

PointGeometry

countryCode

(Optional)

A comma-delimited string of three-character country codes that limits geocoding results to the set of specified countries, which will improve the accuracy of geocoding in most cases. When no country is specified, geocoding with suggestions is performed using all countries supported by the locator.

If you are using ArcGIS World Geocoding Service, see the list of supported countries.

String

categories

(Optional)

A comma-separated list of categories that limits the types of places the locator searches, eliminating false positive matches and potentially speeding up the search process. See the REST API web help for details about category filtering.

String

locationType

(Optional)

Specifies the preferred output location that will be used for PointAddress matches. If the preferred location does not exist in the data, the default location will be returned instead.

This argument only affects the geometry, not the attribute values.

  • rooftop—An address location such as rooftop location, parcel centroid, or front door will be used.

  • street—A location close to the side of the street that can be used for vehicle routing will be used.

The default value is rooftop.

String

outFields

(Optional)

The list of fields that will be returned as part of the attributes in the result. This argument supports a single field name or a comma-delimited string of field names (with no spaces). To return the default output fields, this argument does not need to be passed. Use an asterisk ("*") to return all available output fields with the result. The output fields are described in What's included in the geocoded results.

String

maxResults

(Optional)

The maximum number of locations that will be returned, up to the maximum number allowed by the locator. If no value is provided, all matching candidates up to the maximum specified in the Locator properties will be returned.

Integer

minScore

(Optional)

Limits the candidates that are returned to those with a score above this value. Valid values are between 0 and 100.

Integer

outputLanguageCode

(Optional)

The language in which the geocode results will be returned. Since addresses and places in many countries are available in more than one language, this ensures that results are returned in the expected language.

If you are using ArcGIS World Geocoding Service, see the list of supported countries for the language codes that are supported for those countries.

String

preferredLabelValues

(Optional)

Configures the output fields returned in a response from the locator by specifying the address component values that should be included in the output fields. This argument supports a single value or a comma-delimited string of values as input. For more information about how this argument works, see Additional tuning options.

Possible values include postalCity, localCity, matchedCity, primaryStreet, and matchedStreet.

Note:

Only one value for city labeling and one value for street labeling can be included.

String

searchExtent

(Optional)

An extent that limits the area that will be searched. All results that are returned outside of the specified extent will be excluded.

Extent

matchNarrative

(Optional)

Specifies whether information about how a geocoding result was obtained will be returned.

When this argument is set to True, the return value will describe how each portion of an input string in a geocode request was processed, or classified, by the locator. This information is included as an additional JSON object named match-narrative.

For example, if the string is 380 New York Street, Redlands, the match-narrative object will describe how each part of the input was matched. In the match-narrative object, each part of the input search string is represented with a subobject, the order of which corresponds to that of the input parts. For example, with an address of 380 New York Street, Redlands, each subobject will include the following keys:

  • field—The address component that the input part was matched to. This key value would have a value of 'House Number'.

  • input—The part of the input string that is being described. This key would have a value of '380'.

  • datum—The value in the locator reference data that the input part matched to. This key would have a value of '380'.

  • narrative-code—A code that describes how the input part was matched. This key would have a value of 'cm'.

  • narrative-desc—A detailed description of how the input part was matched. This key would have a value of 'classified+matched'.

For a complete list of the match narrative codes and descriptions, see Match narrative code descriptions.

The default value is False.

Boolean

searchWithin

(Optional)

Specifies the feature types that are returned for a collection of places that are related to a geocoded location. For example, this argument can be used to return all addresses that exist within a postal code or all businesses located at a particular address. Collections can be returned for geocoded matches with Addr_type values PointAddress and PostalExt only. This argument supports a single value or a comma-delimited string of values as input, for example, searchWithin="POI,Subaddress". For more information about how this argument works, see Return associated features or the REST API documentation.

Possible values include PointAddress, Subaddress, and POI.

This argument supports pagination. Because there can be hundreds or thousands of places that exist at or within a geocoded location, this argument is used with the start and num arguments to break up large collections into manageable result sets, or pages, of 50 or fewer candidates. This is accomplished by passing consecutive requests to the locator with different start values. To support pagination, the JSON response includes the following keys at the end of the response when a collection is returned for a searchWithin request:

  • total—The total count of candidates in the collection, including the geocoded object

  • start—The value that was passed in the request for the start argument

  • num—The number of candidates in the page

  • nextStart—The value that should be used for the start argument in the subsequent geocode request

If this argument is used with the ArcGIS World Geocoding Service, the request must also include a valid token.

Note:

This argument is not supported for composite geocode services.

Note:

The first object in the response (candidate 1) is always the geocoded object: the place that was searched for. What follows are the features that are associated with the geocoded object and correspond to the feature types specified.

String

start

(Optional)

The index number of the first entry in a collection of candidates to be returned in the return value. This argument is used with the searchWithin and num arguments to page through large result sets of more than 50 candidates.

Only use this argument when the searchWithin value is specified.

The default value is 1.

Integer

num

(Optional)

The number of collection candidate results that will be returned in each page. This argument is used with the searchWithin and start arguments to page through large result sets of more than 50 candidates. Values should be integers between 1 and 50. If a value larger than 50 is specified, a maximum of 50 candidates will be returned.

Only use this argument when the searchWithin value is specified.

The default value is 50.

Integer

matchID

(Optional)

The ID of an address or place.

This value can be obtained from the result and used at later time. In most cases, the value for a particular address will be constant across releases of the ArcGIS World Geocoding Service and ArcGIS StreetMap Premium locators; however, for custom locators, the MatchID field value will be as consistent as the data used to build the locator with the Create Locator tool.

This is an example of using this argument: matchID="AQFV9QAAmeQBAJUBBAAAAAAMD05FVyBZT1JLIFNUUkVFVBUDMzgwZgNFTkc".

To learn more about this argument, see the REST API documentation.

String

comprehensiveZoneMatch

(Optional)

Specifies whether input addresses that do not exactly match the city name will return candidates.

When set to True, addresses will match even when the city name is incorrect. When set to False, no match will be returned or the match will have a significantly lower score. For more information about how to use this argument, see Comprehensive zone matching.

The default value is True.

Boolean

excludeIntersectionType

(Optional)

Specifies which intersection types will be excluded from locator search results. Virtual is the supported value for this property. For more information about how to use this property, see Exclude intersection type.

When set to Virtual, virtual intersections will be excluded from geocoding results. Intersections with a value of Virtual in the Type field will be excluded from results returned by the locator. If no supported value is specified, all intersection types will be returned.

String

Return value

Data type Explanation

List

The output is a list of dictionary objects. Each dictionary object represents a single geocoding result. Each geocoding result contains information about the match address or location, geometry information including x- and y-coordinates, and additional attributes depending on the Locator object used and the outFields value specified.

Geocode to find the location of a place or address using a locator on disk.

import arcpy

# Create a new Locator object from a locator on disk
locator_path = r"C:\Locators\Atlanta.loc"
locator = arcpy.geocoding.Locator(locator_path)

# Geocode to find the location of an address
geocoding_candidates = locator.geocode("1670 W Peachtree St NE, Atlanta, GA 30309", False)

Geocode to find the location of a place or address using ArcGIS World Geocoding Service.

import arcpy

# Create a new Locator object from the ArcGIS World Geocoding Service
locator_path = "https://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer/ArcGIS World Geocoding Service"
locator = arcpy.geocoding.Locator(locator_path)

# Geocode to find the location of an address
geocoding_candidates = locator.geocode("1670 W Peachtree St NE, Atlanta, GA 30309", True)

Geocode to find the location of a place or address using a locator accessed through an AGS connection.

import arcpy

# Create a new Locator object from a locator published to ArcGIS Server
locator_path = r"C:\AGS Files\MyAGSConnectionFile.ags\Atlanta"
locator = arcpy.geocoding.Locator(locator_path)

# Geocode to find the location of an address
geocoding_candidates = locator.geocode("1670 W Peachtree St NE, Atlanta, GA 30309", False)

reverseGeocode(location, forStorage, {featureTypes}, {locationType}, {outputLanguageCode}, {preferredLabelValues})

Takes a PointGeometry object as input and returns the closest address, point of interest, or intersection to that point. The result is a reverse geocoded result that contains information about the match address or location, geometry information including x- and y-coordinates, and additional attributes depending on the Locator used.

Note:

If you are working with locators on your portal, ensure that you are signed in and have it set as your active portal in ArcGIS Pro. To access a locator that is on a portal other than your active portal, you can authenticate using SignInToPortal..

Name Explanation Data type

location

A point for which you want to find the nearest address, point of interest, or intersection.

PointGeometry

forStorage

Specifies whether the results will be stored. The default value is False, which indicates the results won't be stored, but they can be temporarily displayed on a map. If you store the results, in a database, for example, set this parameter to True.

This parameter only applies to geocoding requests made with ArcGIS World Geocoding Service. For all other locators, the parameter is ignored.

Note:

Applications are contractually prohibited from storing the results of geocoding operations using ArcGIS World Geocoding Service unless they make the request by passing the forStorage parameter with a value of True. For a locator using ArcGIS World Geocoding Service to be valid, you must sign in to ArcGIS Online with a valid organizational account. ArcGIS Online service credits are deducted from the organizational account for each geocode transaction that includes the forStorage parameter with a value of True.

The default value is False.

Boolean

featureTypes

(Optional)

The match types that will be returned. If only one value is provided, the search tolerance is adjusted.

For more information about how this parameter is used in ArcGIS World Geocoding Service, see the REST API documentation.

String

locationType

(Optional)

Specifies the preferred output location that will be used. If the preferred location does not exist in the data, the default location will be returned instead. For more information about this parameter, see the Reverse Geocode REST API documentation.

This parameter only affects the geometry, not the attribute values.

  • rooftop—An address location such as rooftop location, parcel centroid, or front door will be used. This is the default.

  • street—A location close to the side of the street that can be used for vehicle routing will be used.

The default value is rooftop.

String

outputLanguageCode

(Optional)

The language in which the reverse geocode results will be returned. Since addresses and places in many countries are available in more than one language, this ensures that results are returned in the expected language.

If you are using ArcGIS World Geocoding Service, see the list of supported countries for the language codes that are supported for those countries.

String

preferredLabelValues

(Optional)

Configures the output fields returned in a response from the locator by specifying the address component values that should be included in the output fields. The parameter supports a single value or a comma-delimited string of values as input. For more information about how this parameter works, see Additional tuning options.

Possible values include postalCity, localCity, matchedCity, primaryStreet, and matchedStreet.

Note:

Only one value for city labeling and one value for street labeling can be included.

String

Return value

Data type Explanation

List

The reverse geocoding result contains information about the match address or location, geometry information including x- and y-coordinates, and additional attributes depending on the Locator object used and the Shape key when the value is a PointGeometry object.

Reverse geocode to find the nearest place or address to a given location using a locator on disk.

import arcpy

# Create a new Locator object from a locator on disk
locator_path = r"C:\Locators\Atlanta.loc"
locator = arcpy.geocoding.Locator(locator_path)

# Create input PointGeometry object
spatial_reference = arcpy.SpatialReference(4326)
point = arcpy.Point(-84.374, 33.797)
point_geometry = arcpy.PointGeometry(point, spatial_reference)

# Reverse geocode to find the nearest address or place to the point
reverse_geocode_result = locator.reverseGeocode(point_geometry, False)

Reverse geocode to find the nearest place or address to a given location using ArcGIS World Geocoding Service.

import arcpy

# Create a new Locator object from the ArcGIS World Geocoding Service
locator_path = "https://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer/ArcGIS World Geocoding Service"
locator = arcpy.geocoding.Locator(locator_path)

# Create input PointGeometry object
spatial_reference = arcpy.SpatialReference(4326)
point = arcpy.Point(-84.374, 33.797)
point_geometry = arcpy.PointGeometry(point, spatial_reference)

# Reverse geocode to find the nearest address or place to the point
geocoding_candidates = locator.reverseGeocode(point_geometry, True)

Geocode to find the nearest place or address to a given location using a locator accessed through an AGS connection.

import arcpy

# Create a new Locator object from a locator published to ArcGIS Server
locator_path = r"C:\AGS Files\MyAGSConnectionFile.ags\Atlanta"
locator = arcpy.geocoding.Locator(locator_path)

# Create input PointGeometry object
spatial_reference = arcpy.SpatialReference(4326)
point = arcpy.Point(-84.374, 33.797)
point_geometry = arcpy.PointGeometry(point, spatial_reference)

# Reverse geocode to find the nearest address or place to the point
geocoding_candidates = locator.reverseGeocode(point_geometry, False)

suggest(searchText, {preferredSearchLocation}, {countryCode}, {categories}, {maxResults}, {preferredLabelValues}, {returnCollections}, {searchExtent}, {excludeIntersectionType})

Generates autocomplete suggestions for incomplete or partial user input. A single suggestion result can be passed to the geocodeWithSuggest method to generate points that you can display on a map or use as input for other analyses.

Note:

If you are working with locators on your portal, ensure that you are signed in and have it set as your active portal in ArcGIS Pro. To access a locator that is on a portal other than your active portal, you can authenticate using SignInToPortal..

Name Explanation Data type

searchText

The partial text that will be used to generate suggestions.

String

preferredSearchLocation

(Optional)

The origin point that will be used to prefer or boost suggestion candidates based on their proximity to the location. Candidates near the location are prioritized relative to those farther away.

PointGeometry

countryCode

(Optional)

A comma-delimited string of three-character country codes that limits suggestion results to the set of specified countries, which will improve the accuracy of suggestions in most cases. When no country is specified, suggestions will be generated from all countries supported by the locator.

If you are using ArcGIS World Geocoding Service, see the list of supported countries in Geocode data coverage.

String

categories

(Optional)

A comma-separated list of categories that limits the types of places the locator uses to generate suggestions, eliminating false positive matches and potentially speeding up the process. See the REST API web help for details about category filtering.

String

maxResults

(Optional)

The maximum number of suggestions that will be returned, up to the maximum number allowed by the locator. If no value is provided, all matching suggestions up to the maximum specified by the maxSuggestCandidates property in the Locator properties will be returned.

Integer

preferredLabelValues

(Optional)

Configures the output fields returned in a response from the locator by specifying the address component values that should be included in the output fields. The parameter supports a single value or a comma-delimited string of values as input. For more information about how this parameter works, see Additional tuning options.

Possible values include postalCity, localCity, matchedCity, primaryStreet, and matchedStreet.

Note:

Only one value for city labeling and one value for street labeling can be included.

String

returnCollections

(Optional)

Specifies whether collections (points of interest [POI] categories) will be returned when searching for POI. For more information about how to use the returnCollections parameter, see Return collections.

When this parameter is False, if the first character is associated with a category that exists in the data used to build a locator based on the POI role, the category name will not be included in the list of POI candidates returned.

The default value is True.

Boolean

searchExtent

(Optional)

An extent that limits the area that will be searched. All results that are returned outside of the specified extent will be excluded.

Extent

excludeIntersectionType

(Optional)

Specifies which intersection types will be excluded from locator search results. Virtual is the supported value for this property. For more information about how to use this property, see Exclude intersection type.

When set to Virtual, virtual intersections will be excluded from geocoding results. Intersections with a value of Virtual in the Type field will be excluded from results returned by the locator. If no supported value is specified, all intersection types will be returned.

String

Return value

Data type Explanation

List

The output of the suggest method is an array of dictionary objects. Each dictionary represents a single suggestion result. Each suggestion result contains the text, magicKey, and isCollection keys.

To use the output of this method, pass the entire dictionary at the desired index of the list to the geocodeWithSuggest method.

Note:

To learn more about the dictionary keys, see the REST API documentation.

Generate suggestions based on an incomplete user input string using a locator on disk.

import arcpy

# Create a new Locator object from a locator on disk
locator_path = r"C:\Locators\Atlanta.loc"
locator = arcpy.geocoding.Locator(locator_path)

# Generate suggestions from partial user input
suggestion_candidates = locator.suggest("1670 w peach")

Generate suggestions based on an incomplete user input string using ArcGIS World Geocoding Service.

import arcpy

# Create a new Locator object from the ArcGIS World Geocoding Service
locator_path = "https://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer/ArcGIS World Geocoding Service"
locator = arcpy.geocoding.Locator(locator_path)

# Generate suggestions from partial user input
suggestion_candidates = locator.suggest("1670 w peach")

Generate suggestions based on an incomplete user input string using a locator accessed through an AGS connection.

import arcpy

# Create a new Locator object from a locator published to ArcGIS Server
locator_path = r"C:\AGS Files\MyAGSConnectionFile.ags\Atlanta"
locator = arcpy.geocoding.Locator(locator_path)

# Generate suggestions from partial user input
suggestion_candidates = locator.suggest("1670 w peach")

geocodeWithSuggest(suggestResult, forStorage, {preferredSearchLocation}, {countryCode}, {categories}, {locationType}, {outFields}, {maxResults}, {minScore}, {outputLanguageCode}, {preferredLabelValues}, {searchExtent}, {excludeIntersectionType})

Takes a single suggest method result as input and returns geocoding result candidates. The result candidates are points that you can display on a map or use as input for other analyses.

It is recommended that you pass the same parameters to the geocodeWithSuggest method that you passed when you generated the suggest method result that you are using to achieve consistent results.

Note:

If you are working with locators on your portal, ensure that you are signed in and have it set as your active portal in ArcGIS Pro. To access a locator that is on a portal other than your active portal, you can authenticate using SignInToPortal.

Name Explanation Data type

suggestResult

The output from the suggest method. The suggestion result is a dictionary that contains text, magicKey, and isCollection keys and is used to locate an address or place.

To learn more about the keys included in the suggestion result dictionary objects, see the REST API documentation.

Dictionary

forStorage

Specifies whether the results will be stored. The default value is False, which indicates the results won't be stored, but they can be temporarily displayed on a map. If you store the results, in a database, for example, set this parameter to True.

This parameter only applies to geocoding requests made with ArcGIS World Geocoding Service. For all other locators, the parameter is ignored.

Note:

Applications are contractually prohibited from storing the results of geocoding operations using ArcGIS World Geocoding Service unless they make the request by passing the forStorage parameter with a value of True. For a locator using ArcGIS World Geocoding Service to be valid, you must sign in to ArcGIS Online with a valid organizational account. ArcGIS Online service credits are deducted from the organizational account for each geocode transaction that stores results.

The default value is False.

Boolean

preferredSearchLocation

(Optional)

The origin point that will be used to prefer or boost geocoding candidates based on their proximity to the location. Candidates near the location are prioritized relative to those farther away.

PointGeometry

countryCode

(Optional)

A comma-delimited string of three-character country codes that limits geocoding results to the set of specified countries, which will improve the accuracy of geocoding in most cases. When no country is specified, geocoding with suggestions will be performed using all countries supported by the locator.

If you are using ArcGIS World Geocoding Service, see the list of supported countries.

String

categories

(Optional)

A comma-separated list of categories that limits the types of places the locator searches, eliminating false positive matches and potentially speeding up the search process. See the REST API web help for details about category filtering.

String

locationType

(Optional)

Specifies the preferred output geometry that will be used for PointAddress matches. If the preferred location does not exist in the data, the default location will be returned instead. This parameter only affects the geometry, not the attribute values.

  • rooftop—An address location such as rooftop location, parcel centroid, or front door will be used. This is the default.

  • street—A location close to the side of the street that can be used for vehicle routing will be used.

The default value is rooftop.

String

outFields

(Optional)

The list of fields that will be returned as part of the attributes in the result. This parameter supports a single field name or a comma-delimited string of field names (with no spaces). To return the default output fields, outFields does not need to be passed. Use an asterisk ("*") to return all available output fields with the result. The output fields are described in What's included in the geocoded results.

String

maxResults

(Optional)

The maximum number of locations that will be returned, up to the maximum number allowed by the locator. If no value is provided, all matching candidates up to the maximum specified by the maxCandidate property in the Locator properties will be returned.

Integer

minScore

(Optional)

Limits the candidates that are returned to those with a score above the value set for this parameter. Valid values are between 0 and 100.

Integer

outputLanguageCode

(Optional)

The language in which the geocode results will be returned. Since addresses and places in many countries are available in more than one language, this ensures that results are returned in the expected language.

If you are using ArcGIS World Geocoding Service, see the list of supported countries for the language codes that are supported for those countries.

String

preferredLabelValues

(Optional)

Configures the output fields returned in a response from the locator by specifying the address component values that should be included in the output fields. The parameter supports a single value or a comma-delimited string of values as input. For more information about how this parameter works, see Additional tuning options.

Possible values include postalCity, localCity, matchedCity, primaryStreet, and matchedStreet.

Note:

Only one value for city labeling and one value for street labeling can be included.

String

searchExtent

(Optional)

An extent that limits the area that will be searched. All results that are returned outside of the specified extent will be excluded.

Extent

excludeIntersectionType

(Optional)

Specifies which intersection types will be excluded from locator search results. Virtual is the supported value for this property. For more information about how to use this property, see Exclude intersection type.

When set to Virtual, virtual intersections will be excluded from geocoding results. Intersections with a value of Virtual in the Type field will be excluded from results returned by the locator. If no supported value is specified, all intersection types will be returned.

String

Return value

Data type Explanation

List

The output of the geocodeWithSuggest method is a list of dictionary objects. Each dictionary represents a single geocoding result. Each geocoding result contains information about the match address or location, geometry information including x- and y-coordinates, and additional attributes depending on the Locator object used and the outFields value specified.

Generate suggestions based on an incomplete user input string, and geocode with one of the suggestions generated as the output of that operation to find a location using a locator on disk.

import arcpy

# Create a new Locator object from a locator on disk
locator_path = r"C:\Locators\Atlanta.loc"
locator = arcpy.geocoding.Locator(locator_path)

# Generate suggestions from partial user input
suggestion_candidates = locator.suggest("1670 w peach")

# Geocode using one of the suggestions generated as the output of the suggest
# operation
geocoding_candidates = locator.geocodeWithSuggest(suggestion_candidates[0], False)

Generate suggestions based on an incomplete user input string, and geocode with one of the suggestions generated as the output of that operation to find a location using ArcGIS World Geocoding Service.

import arcpy

# Create a new Locator object from the ArcGIS World Geocoding Service
locator_path = "https://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer/ArcGIS World Geocoding Service"
locator = arcpy.geocoding.Locator(locator_path)

# Generate suggestions from partial user input
suggestion_candidates = locator.suggest("1670 w peach")

# Geocode using one of the suggestions generated as the output of the suggest
# operation
geocoding_candidates = locator.geocodeWithSuggest(suggestion_candidates[0], True)

Generate suggestions based on an incomplete user input string, and geocode with one of the suggestions generated as the output of that operation to find a location using a locator accessed through an AGS connection.

import arcpy

# Create a new Locator object from a locator published to ArcGIS Server
locator_path = r"C:\AGS Files\MyAGSConnectionFile.ags\Atlanta"
locator = arcpy.geocoding.Locator(locator_path)

# Generate suggestions from partial user input
suggestion_candidates = locator.suggest("1670 w peach")

# Geocode using one of the suggestions generated as the output of the suggest
# operation
geocoding_candidates = locator.geocodeWithSuggest(suggestion_candidates[0], False)

updateLocator()

Persists changes made to Locator properties during the current Python session to the locator so that the properties are applied for future use.

Update a property of a locator on disk, and persist changes.

import arcpy

# Create a new Locator object from a locator on disk
locator_path = r"C:\Locators\Atlanta.loc"
locator = arcpy.geocoding.Locator(locator_path)

# Update the minimum match score property on the locator
locator.minMatchScore = 95

# Persist changes to the .loc file
locator.updateLocator()