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 SignInToPortal.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
# 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
# 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) | Returns 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 setting to exclude matches to certain types. For example, your locator can support matches to PointAddress level, StreetAddress level, StreetName level, and Postal level. You may 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 your geocoding experience. This property is read-only for geocode services. To change this property in a published locator, modify the property locally, and publish your locator again. Note:This property is set as a runtime property only. It is not persisted to the locator outside of your current session unless you use the updateLocator method. | String |
| 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, the side of street location, which can be used for routing, or Address_Location, the location that represents the rooftop, parcel centroid for the address, or front door. 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, while 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 your locator again. Note:This property is set as a runtime property only. It is not persisted to the locator outside of your current session unless you use the updateLocator method. | String |
| defaultSuggestCandidates (Read and Write) | The number of suggestion candidates that are 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 your locator again. Note:This property is set as a runtime property only. It is not persisted to the locator outside of your current session unless you use the updateLocator method. | Integer |
| endOffset (Read and Write) | The distance in meters 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 your locator again. Note:This property is set as a runtime property only. It is not persisted to the locator outside of your current session unless you use the updateLocator method. | Double |
| intersectionConnectors (Read and Write) | The list of intersection connectors, which can be symbols or words, with which to override the default intersection connectors. The list of intersection connectors should be in a quoted comma-separated list, for example, "&","|","//","@". This property is read-only for geocode services. To change this property in a published locator, modify the property locally, and publish your locator again. Note:This property is set as a runtime property only. It is not persisted to the locator outside of your current session unless you use the updateLocator method. | String |
| matchOutOfRange (Read and Write) | Controls 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 your 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 your locator again. Note:This property is set as a runtime property only. It is not persisted to the locator outside of your current session unless you use the updateLocator method. | Boolean |
| maxCandidates (Read and Write) | The maximum number of candidates that are returned from the geocode method. If you find that geocoding is taking a long time and you are also getting high-quality matches, ensure that this property is not set too high. Assuming 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 your locator again. Note:This property is set as a runtime property only. It is not persisted to the locator outside of your current session unless you use the updateLocator method. | Integer |
| maxSuggestCandidates (Read and Write) | The maximum number of suggestion results that are returned from the suggest method. If you find that the suggest method has poor performance, 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 your locator again. Note:This property is set as a runtime property only. It is not persisted to the locator outside of your 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 are 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 your locator again. Note:This property is set as a runtime property only. It is not persisted to the locator outside of your current session unless you use the updateLocator method. | Integer |
| minMatchScore (Read and Write) | The minimum score that a result of the geocode method 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 your locator again. Note:This property is set as a runtime property only. It is not persisted to the locator outside of your 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 are used for batch geocoding. To make best use of this setting, consider the machine you will be using for geocoding and determine the number of cores available on your machine that you can devote to a geocoding job. Geocoding has the ability to use all of the cores on your machine 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 for your machine, or you can choose to devote a specified number of cores to geocoding if you know you need to leave some other resources available for other applications. If you plan to share your 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 your locator again. Note:This property is set as a runtime property only. It is not persisted to the locator outside of your current session unless you use the updateLocator method. | Integer |
| partialHouseNumberSuggestions (Read and Write) | Determines whether suggestions are returned for house numbers when only a partial house number value is entered. This option only applies for 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 your locator again. Note:This property is set as a runtime property only. It is not persisted to the locator outside of your current session unless you use the updateLocator method. | Boolean |
| partialSubaddressSuggestions (Read and Write) | Determines whether subaddresses are returned by the suggest method when only a partial subaddress value is used 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 your locator again. Note:This property is set as a runtime property only. It is not persisted to the locator outside of your current session unless you use the updateLocator method. | Boolean |
| sideOffset (Read and Write) | The distance in meters 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 your locator again. Note:This property is set as a runtime property only. It is not persisted to the locator outside of your current session unless you use the updateLocator method. | Double |
| singleLineInputField (Read Only) | The locator field for singleline geocoding. This property returns an arcpy.Field object representing the singleline input field for the locator. A singleline 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 your current session unless you use the updateLocator method. | String |
| subaddressAfterBaseAddressSuggestions (Read and Write) | Determines whether suggestions are returned for subaddresses after the base address is entered. When selecting this option, 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 your locator again. Note:This property is set as a runtime property only. It is not persisted to the locator outside of your current session unless you use the updateLocator method. | Boolean |
| subaddressSummaryWithBaseAddress (Read and Write) | Determines whether a summary of the subaddress units at an address is returned after the base address is entered. The summary of the subunits can either be 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 mix 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 your locator again. Note:This property is set as a runtime property only. It is not persisted to the locator outside of your 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) | 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 your locator again. Note:This property is set as a runtime property only. It is not persisted to the locator outside of your current session unless you use the updateLocator method. | String |
Method Overview
| Method | Explanation |
| geocode (searchText, forStorage, {preferredSearchLocation}, {countryCode}, {categories}, {locationType}, {outFields}, {maxResults}, {minScore}, {outputLanguageCode}, {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}) |
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}, {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}, {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}, {searchExtent})| Parameter | Explanation | Data Type |
searchText | An address or place-name to find the location of. | String |
forStorage | Specifies whether the results will be persisted. The default value is False, which indicates the results can't be stored, but they can be temporarily displayed on a map, for instance. If you store the results, in a database, for example, 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 log 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 | An origin point that is 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 against all countries supported by the locator. If you are using ArcGIS World Geocoding Service, refer to this list of supported countries. | String |
categories | A comma-separated list of categories that limits the types of places the locator searches, thus 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 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, while the DisplayX and DisplayY values describe the rooftop, or building centroid, coordinates. This argument only affects the geometry, not the attribute values.
| String |
outFields | The list of fields to 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 (without 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 not specified, all matching candidates up to the maximum specified in the Locator properties are returned. | Integer |
minScore | Limits the candidates that are returned to those with a score above the value set for this property. The value should be between 0 and 100. | Integer |
outputLanguageCode | The language in which the geocode results are 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, refer to the list of supported countries to see what language codes are supported for those countries. | String |
searchExtent | An extent that limits the area to be searched. All results that are returned outside of the specified extent are 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 used and the outFields specified. |
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 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})| 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 persisted. The default value is False, which indicates the results can't be stored, but they can be temporarily displayed on a map, for instance. If you store the results, in a database, for example, 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 log 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 | Specify one or more match types to be returned. If only one value is specified, the search tolerance is adjusted. For more information on how this argument is used in ArcGIS World Geocoding Service, refer to the REST API documentation. | String |
locationType | Specifies the preferred output location. 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, while the DisplayX and DisplayY values describe the rooftop, or building centroid, coordinates. For more information about this parameter, reference the information on the parameter in the Reverse Geocode REST API documentation. This argument only affects the geometry, not the attribute values.
| String |
outputLanguageCode | The language in which the reverse geocode results are 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, refer to the list of supported countries to see what language codes are supported for those countries. | 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 used, as well as a Shape key for which the value is a PointGeometry object. |
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 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}, {searchExtent})| Parameter | Explanation | Data Type |
searchText | The partial text for which you want to generate suggestions. | String |
preferredSearchLocation | An origin point that is 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 are generated from all countries supported by the locator. If you are using ArcGIS World Geocoding Service, refer to the list of supported countries in Geocode coverage. | String |
categories | A comma-separated list of categories that limits the types of places for which the locator generates suggestions, thus 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 to be returned, up to the maximum number allowed by the Locator. If not specified, all matching suggestions up to the maximum specified in the Locator maxSuggestCandidates property are returned. | Integer |
searchExtent | An extent that limits the area to be searched. All results that are returned outside of the specified extent are 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 following keys: text, magicKey, and isCollection. To use the output of the suggest method, the entire dictionary at the desired index of the list should be passed to the geocodeWithSuggest method. Note:To learn more about the dictionary keys, refer to the REST API documentation. |
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 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}, {searchExtent})| Parameter | Explanation | Data Type |
suggestResult | The output from the suggest method is used to locate an address or place. The suggestion result is a dictionary that contains text, magicKey, and isCollection keys. To learn more about the keys included in the suggestion result dictionary objects, refer to the REST API documentation. | Dictionary |
forStorage | Specifies whether the results will be persisted. The default value is False, which indicates the results of the operation can't be stored, but they can be temporarily displayed on a map, for instance. If you store the results, in a database, for example, 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. 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 log 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 | An origin point that is 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 against all supported countries of the locator. If you are using ArcGIS World Geocoding Service, refer to this list of supported countries. | String |
categories | A comma-separated list of categories that limits the types of places the locator searches, thus 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 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, while the DisplayX and DisplayY values describe the rooftop, or building centroid, coordinates. This argument only affects the geometry, not the attribute values.
| String |
outFields | The list of fields to 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 (without 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 not specified, all matching candidates up to the maximum specified by the maxCandidate property in the Locator properties are returned. | Integer |
minScore | Limits the candidates that are returned to those with a score above the value set for this property. The value should be between 0 and 100. | Integer |
outputLanguageCode | The language in which the geocode results are 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, refer to the list of supported countries to see what language codes are supported for those countries. | String |
searchExtent | An extent that limits the area to be searched. All results that are returned outside of the specified extent are 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 used and the outFields specified. |
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 SignInToPortal.Generate suggestions based on 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 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 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()