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 was designed to support locators created with the Create Locator tool. Locators created with legacy tools may have limited functionality, and a number of properties and parameters will not be supported.
Discussion
A locator is a portable file used to perform geocoding, 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 knowledge 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 AGS server connection, or as a file on disk.
Syntax
Locator (path)
| Parameter | Explanation | Data Type |
path | A path to the locator. | String |
Note:
If you are working with locators on your portal, make sure 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 the SignInToPortal function.Create a Locator object from a locator stored 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 a Locator object from ArcGIS World Geocoding Service.
import arcpy
# Log in to Portal
#arcpy.SignInToPortal("https://www.arcgis.com", "MyUsername", "MyPassword")
# 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 a Locator object from 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 a Locator object from a locator item on your own ArcGIS Enterprise Portal.
import arcpy
# Log in to Portal
#arcpy.SignInToPortal("https://www.myenterpriseportal.esri.com/portal", "MyUsername", "MyPassword")
# Create a new Locator object from the locator on your portal
locator_path = "https://myenterpriseportal.esri.com/server/rest/services/Geocode/Atlanta/GeocodeServer/Atlanta"
locator = arcpy.geocoding.Locator(locator_path)Properties
| Property | 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:
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. You want to exclude matches to the Postal level because you consider matches to that level to be too imprecise for your purposes. 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 runtime property only. It is not persisted to the locator outside of the current session unless you use the updateLocator method. | 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 the comprehensiveZoneMatch 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 runtime 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 Routing_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 the defaultLocationType 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 runtime 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 runtime 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 the endOffset 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 runtime property only. It is not persisted to the locator outside of the current session unless you use the updateLocator method. | Double |
| 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 runtime 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. The matchOutOfRange property only applies to locators that support and return StreetAddress matches. For more information about the matchOutOfRange 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 runtime 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 runtime 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 the maxSuggestCandidates 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 runtime 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 runtime 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 runtime 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) | Specifies the number of threads that will be used for batch geocoding. For optimal use of this setting, determine the number of cores available on your machine that you can devote to a geocoding job. All of the 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 cores available, but it can be configured to use more cores if you know you have them available. It can be set to Auto to detect the cores on your machine and optimize the number of threads used, or you can use a specified number of cores for geocoding if you know 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 property 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 runtime 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 the partialHouseNumberSuggestions 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 runtime 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 the partialSubaddressSuggestions 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 runtime 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. The 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 runtime 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 the returnCollections 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 runtime 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 runtime property only. It is not persisted to the locator outside of the current session unless you use the updateLocator method. | Boolean |
| reverseOutputFields (Read and Write) | Specifies 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 runtime 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 the sideOffset 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 runtime 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 runtime 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 setting 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 the subaddressAfterBaseAddressSuggestions 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 runtime 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 the subaddressSummaryWithBaseAddress 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 runtime 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 the reverseGeocodeFeatureTypes 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 runtime property only. It is not persisted to the locator outside of the current session unless you use the updateLocator method. | String |
Method Overview
| Method | Explanation |
| geocode (searchText, forStorage, {preferredSearchLocation}, {countryCode}, {categories}, {locationType}, {outFields}, {maxResults}, {minScore}, {outputLanguageCode}, {preferredLabelValues}, {searchExtent}) |
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. |
| 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. |
| suggest (searchText, {preferredSearchLocation}, {countryCode}, {categories}, {maxResults}, {preferredLabelValues}, {returnCollections}, {searchExtent}) | 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. |
| geocodeWithSuggest (suggestResult, forStorage, {preferredSearchLocation}, {countryCode}, {categories}, {locationType}, {outFields}, {maxResults}, {minScore}, {outputLanguageCode}, {preferredLabelValues}, {searchExtent}) | 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. |
| updateLocator () | Persists changes made to Locator properties during the current Python session to the locator so that the properties are applied for future use. |
Methods
geocode (searchText, forStorage, {preferredSearchLocation}, {countryCode}, {categories}, {locationType}, {outFields}, {maxResults}, {minScore}, {outputLanguageCode}, {preferredLabelValues}, {searchExtent})| Parameter | Explanation | Data Type |
searchText | The address or place-name for which to find the location. | String |
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. | Boolean |
preferredSearchLocation | 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 | 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 | 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 | 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. 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. This parameter only affects the geometry, not the attribute values.
| String |
outFields | 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 | The maximum number of locations, 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 | 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 | 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 | 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 | An extent that limits the area that will be searched. All results that are returned outside of the specified extent will be excluded. | Extent |
| Data Type | Explanation |
| List | The output of the geocode operation 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. |
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.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})| Parameter | 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 | The match types that will be returned. If only one value is provided, the search tolerance is adjusted. For more information on how this parameter is used in ArcGIS World Geocoding Service, see the REST API documentation. | String |
locationType | 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 reverse geocoding 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 this parameter, see the Reverse Geocode REST API documentation. This parameter only affects the geometry, not the attribute values.
| String |
outputLanguageCode | 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 | 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 |
| 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. |
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.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})| Parameter | Explanation | Data Type |
searchText | The partial text that will be used to generate suggestions. | String |
preferredSearchLocation | 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 | 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 | 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 | 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 | 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 | 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 | An extent that limits the area that will be searched. All results that are returned outside of the specified extent will be excluded. | Extent |
| 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. |
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.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})| Parameter | 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. | Boolean |
preferredSearchLocation | 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 | 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 | 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 | 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. 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. This parameter only affects the geometry, not the attribute values.
| String |
outFields | 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 | 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 | 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 | 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 will ensure 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 | 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 | An extent that limits the area that will be searched. All results that are returned outside of the specified extent will be excluded. | Extent |
| 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. |
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.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 ()
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()