Create Feature Locator (Geocoding)

Summary

Creates a locator using reference data that contains a unique name or value for every feature stored in a single field. A locator created with this tool has broad applications. It can be used to search for names or unique attributes of features, such as water meters, short place names, cell towers, or alphanumeric strings used to identify locations (for example, N1N115).

Locators created by this tool will use the indexed values in a single field to search for values in the single field and return them as a collection of points, or to identify features near a point location. Tables of addresses that can be geocoded using a locator created with this tool must also contain a single field with the same unique name or value that can be used to identify the locations.

Note:

Locators created by this tool can be used in ArcGIS Pro 2.5 or later, Enterprise 10.8 or later, and as a locator service in ArcMap. Locators created by this tool cannot be used as a local locator in ArcMap.

Usage

  • Feature classes represented as services are supported data types for use as reference data.

  • The tool supports feature classes that contain point and polygon geometry as reference data.

  • A locator created with this tool can be used to search for unique identifiers or short string values of no more than five words.

  • Locators created with this tool support global searches for coordinates (latitude/longitude, MGRS, DD, or USNG). At least one feature must be included in the primary reference data used to build the locator. Support for coordinate searching is disabled or enabled under Categories to support on the Geocoding options page of the Locator Properties dialog box for the locator.

  • Additional fields from the reference data can be provided and added to the locator as custom output fields when the locator is created. These fields are used to provide additional information of the geocode result candidates. For example, if you want to know which Census block or fire district a fire hydrant is associated with, you can geocode the hydrant ID and spatially join the attributes of the Census block or fire district to the geocode results. By spatially joining the attributes from the layers with the additional information to the reference data used to build the locator, you can specify the joined fields as user-defined custom output fields when building the locator. The geocode result will include the additional custom output fields and their values.

  • The output of this tool can be used as input to the Create Composite Address Locator tool. However, combining a locator created with this tool with other address role based locators in a composite locator should be treated with caution because field mapping of the Name feature locator role field may lead to unexpected behavior. Best practice is to use a locator created with the Create Locator tool based on the POI role instead.

  • To generate the correct Python syntax, first run the tool from the Geoprocessing pane using the appropriate parameter options. Then open the Run menu and choose the Copy Python Command option.

  • You can build locators using z-aware point feature classes as the primary reference data. The z-aware features should be created at an absolute elevation so that the geocode results will be displayed at the expected elevation in the map.

Parameters

LabelExplanationData Type
Input Features

The reference data feature class or feature layer that will be used to create the locator.

Feature classes represented as services are supported data types for use as reference data.

Caution:

When a definition query is defined for the reference data or there are selected features, only the queried and selected features are included when the locator is created.

Note:

When creating a locator with reference data that contains millions of features, you must have at least three to four times the size of the data in free disk space on the drive containing your temp directory, as files used to build the locator are written to this location before the locator is copied to the output location. If you do not have enough disk space, the tool will fail when it runs out of space. Also, when creating large locators, your machine must have enough RAM to handle large memory-intensive processes.

Feature Layer
Search Fields

Maps the reference data field to the field used for search in the Input Features parameter value. Fields with an asterisk (*) next to their names are required. The selected field will be indexed and used for search.

Field Info
Output Locator

The output locator file to be created in a file folder. Once the locator is created, additional properties and options can be modified in the locator's settings.

Address Locator
Additional Locator Fields
(Optional)

Maps additional fields for extent and rank if they exist in the data. The Rank field is used to sort results for ambiguous queries or candidates with the same name and score. The extent fields help set the map extent for displaying geocoded results.

Field Info
Custom Output Fields
(Optional)

Adds user-defined output fields to the locator. The values specified for this parameter will define the names of the custom output fields that will be returned in the geocode result; however, each new field must be mapped to a field in the reference data. The maximum number of fields supported in the locator is 50.

Do the following to add custom output fields to the locator for use in the geocode result:

  • Type the names of the custom output fields. The custom output field names will be added to the field mapping.
  • Select the field in the reference data that contains the additional values to be included in the geocode output.
String

arcpy.geocoding.CreateFeatureLocator(in_features, search_fields, output_locator, {locator_fields}, {custom_output_fields})
NameExplanationData Type
in_features

The reference data feature class or feature layer that will be used to create the locator.

Feature classes represented as services are supported data types for use as reference data.

Caution:

When a definition query is defined for the reference data or there are selected features, only the queried and selected features are included when the locator is created.

Note:

When creating a locator with reference data that contains millions of features, you must have at least three to four times the size of the data in free disk space on the drive containing your temp directory, as files used to build the locator are written to this location before the locator is copied to the output location. If you do not have enough disk space, the tool will fail when it runs out of space. Also, when creating large locators, your machine must have enough RAM to handle large memory-intensive processes.

Feature Layer
search_fields

Maps the reference data field to the field used for search in the in_features parameter value. The search_fields mapping is done in the following format in which <locator field name> is the name of the field supported by the locator role, and <data field name> is the name of the field used for search in the in_features parameter.

# <locator field name> <data field name>

# This shows an example:
reference_data_field_map = """
"'Name' AssetName"
"""

The selected field will be indexed and used for search. Map the relevant field for the reference data in the in_features parameter.

Field Info
output_locator

The output locator file to be created in a file folder. Once the locator is created, additional properties and options can be modified in the locator's settings.

Address Locator
locator_fields
(Optional)

Maps additional fields for extent and rank if they exist in the data. The Rank field is used to sort results for ambiguous queries or candidates with the same name and score. The extent fields help set the map extent for displaying geocoded results. The locator_fields mapping is done in the following format:

# <additional locator field name> <additional data field name>

# This shows an example:
additional_fields_map = """
"'Rank' RANK;'Min X' Xmin;
'Max X' Xmax;'Min Y' Ymin;
'Max Y' Ymax"
"""

The <additional locator field name> field is the name of the additional fields supported by the locator, and the <additional data field name> field is the name of the field in the in_features parameter. Map the relevant fields for the reference data in the in_features parameter.

Field Info
custom_output_fields
[custom_output_fields,...]
(Optional)

Adds user-defined output fields to the locator. The values specified for this parameter will define the names of the custom output fields that will be returned in the geocode result; however, each new field must be mapped to a field in the reference data. The maximum number of fields supported in the locator is 50.

Note:

You must first include the custom output field names in the field_mapping parameter; then list the names in the custom_output_fields parameter.

String

Code sample

CreateFeatureLocator example 1 (stand-alone script)

The following Python script demonstrates how to use the CreateFeatureLocator function in a stand-alone script.

# Description: Create a feature locator using local data.

# Import system modules
import arcpy

# Set local variables
in_features = r"C:\data\arizona.gdb\az_points"
search_field = "*Name NAME VISIBLE NONE"
output_locator = r"C:\output\locators\az_points_locator"
locator_fields = "Rank <None> VISIBLE NONE;'Min X' <None> VISIBLE NONE;'Max X' <None> VISIBLE NONE;'Min Y' <None> VISIBLE NONE;'Max Y' <None> VISIBLE NONE"

# Run CreateFeatureLocator
arcpy.geocoding.CreateFeatureLocator(in_features, search_field, output_locator, 
                                     locator_fields)
CreateFeatureLocator example 2 (stand-alone script)

The following Python script demonstrates how to use the CreateFeatureLocator function in a stand-alone script.

# Description: Create a feature locator using data from a hosted feature service in ArcGIS Online.

# Import system modules
import arcpy

# Sign in to Portal
arcpy.SignInToPortal("https://www.arcgis.com", "<username>", "<password>")

# Set local variables
in_features = "https://services.arcgis.com/<layer_id>/arcgis/rest/services/<service_name>/FeatureServer/<layer_number>"
search_field = "*Name NAME VISIBLE NONE"
output_locator = r"C:\output\locators\service_locator"
locator_fields = "Rank <None> VISIBLE NONE;'Min X' <None> VISIBLE NONE;'Max X' <None> VISIBLE NONE;'Min Y' <None> VISIBLE NONE;'Max Y' <None> VISIBLE NONE"

arcpy.geocoding.CreateFeatureLocator(in_features, search_field, output_locator, 
                                     locator_fields)

Environments