Skip To Content

Create Locator

Summary

Creates a locator that can be used to find the location of an address or a place, convert a table of addresses or places into a collection of point features, or identify the address of a point location.

Note:

Locators created by this tool can be used in ArcGIS Pro 2.2 or later, Enterprise 10.6.1 or later, and as a locator service in ArcMap. Locators created by this tool cannot be used as a local locator in ArcMap. To use a locator locally in ArcMap, use the Create Address Locator tool.

Usage

  • The locator role defines the type of data that is being used (parcel, street centerline, postal, point of interest, and so on) and provides the appropriate fields to be used when building the locator and the information returned in the geocoding results. The primary locator roles provided with ArcGIS Pro allow you to build the following types of locators:

    • PointAddress—A street address based on points that represent house and building locations. This includes Subaddress, which is based on points that represent house and building subaddress locations, such as suite, floor, or apartment.
    • StreetAddress—A street address based on streets where the house number is interpolated from a range of numbers. This includes intersections, street name, and street extension.
    • Point of Interest—Consists of administrative divisions, place-names, businesses, landmarks, and geographic features—for example, Starbucks.
    • Postal—Postal codes, postal codes with extensions, and postal localities where polygon reference data should be used to return optimal reverse geocoding results.
    • Localities—Administrative zones or areas such as cities, neighborhoods, states, and so on, where polygon reference data should be used to return optimal reverse geocoding results.
    • DistanceMarker—A street address that represents the linear distance along a street, typically in kilometers or miles, from a designated origin location.
    • DistanceRange—A type of distance marker representing interpolated distance values along a street centerline based on line features.

  • Alternate name tables can be used for all of the supported locator roles and support alternate names for the features in the primary reference data.

    Learn more about alternate name tables

  • The output of this tool can be used as input to the Create Composite Address Locator tool.

Syntax

CreateLocator_geocoding (country_code, primary_reference_data, field_mapping, out_locator, language_code, {alternatename_tables}, {alternate_field_mapping}, {custom_output_fields})
ParameterExplanationData Type
country_code

Identifies where country-specific geocoding logic should be applied to the reference data for the locator.

It can be specified by AS_DEFINED_IN_DATA and a value can be mapped from primary_reference_data in field_mapping, or it can be applied to the entire dataset by specifying the 3-character country code name such as USA, CAN, or PRI.

It provides a country template containing the expected field names that are available for use by the field_mapping parameter for the specified country of the locator to be created.

String
primary_reference_data
[[reference_data, {role}],...]

The reference data feature classes and their roles that will be used to create the locator.

Only one primary table can be used per role.

Note:

When creating an address locator with reference data that contains millions of features, it is necessary to have at least 3 to 4 times the size of the data in free disk space on the drive containing your temp directory because 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 at some point during execution when it runs out of space. Also, keep in mind that when creating very large locators, you should have a machine with enough RAM to handle large memory-intensive processes.

Value Table
field_mapping
[field_mapping,...]

The mapping of primary reference dataset fields to the fields supported by the locator role. Each field mapping in this parameter is in the following format:

The following is an example of primary field_mapping.

# <locator role field name> <primary data field name>

# This shows an example:
primary_reference_data_field_map =
"'*StreetAddress.HOUSE_NUMBER_FROM_LEFT streets.L_F_ADD';"\
"'*StreetAddress.HOUSE_NUMBER_TO_LEFT streets.L_T_ADD';"\
"'*StreetAddress.HOUSE_NUMBER_FROM_RIGHT streets.R_F_ADD';"\
"'*StreetAddress.HOUSE_NUMBER_TO_RIGHT streets.R_T_ADD';"\
"'StreetAddress.STREET_PREFIX_DIR streets.PREFIX';"\
"'StreetAddress.STREET_PREFIX_TYPE streets.PRE_TYPE';"\
"'*StreetAddress.STREET_NAME streets.NAME';"\
"'StreetAddress.STREET_SUFFIX_TYPE streets.TYPE';"\
"'StreetAddress.STREET_SUFFIX_DIR streets.SUFFIX';"\
"'StreetAddress.CITY_LEFT streets.CITYL';"\
"'StreetAddress.CITY_RIGHT streets.CITYR';"\
"'StreetAddress.REGION_LEFT streets.STATE_ABBR';"\
"'StreetAddress.REGION_RIGHT streets.STATE_ABBR';"\
"'StreetAddress.POSTAL_LEFT streets.ZIPL';"\
"'StreetAddress.POSTAL_RIGHT streets.ZIPR'"

<locator role field name> is the name of the field supported by the locator role, and <primary data field name> is the name of the field in the primary reference dataset. Fields with an asterisk (*) next to their names are required by the locator role. Map the relevant fields for each table in the primary_reference_data parameter.

If you choose not to map an optional reference data field used by the locator role to a field in a reference dataset, it is not necessary to specify that there is no mapping by using <None> in place of a field name.

To determine the <locator role field name> for a reference data field used by a locator role, open the Create Locator tool and choose the locator role. The name that appears in the Field Name column of the Field Mapping parameter is the field's role field name.

Note:

If you are using an alternate name table, map Join ID in primary_reference_data.

To add additional custom output fields, the names of the fields must be defined in the custom_output_fields parameter as well as the field_mapping parameter. The field_mapping parameter will use the format '<locator role field name> <primary data field name>', where <locator role field name> is defined as 'RoleName.CustomFieldName', and <primary data field name> is the name of the field in the primary reference dataset as shown in the mapped fields in the example above. If a custom field is added to a Street Address role, you will need to map 'StreetAddress.CustomFieldName_Left' and 'StreetAddress.CustomFieldName_Right' for each side of the street.

String
out_locator

The output address locator file.

Address Locator
language_code

Identifies where language-specific geocoding logic should be applied to the reference data for the locator.

If a language code field exists in the primary reference data, providing a language code can improve the results of the geocoding.

It can be specified by setting AS_DEFINED_IN_DATA as the language_code and mapping a value from primary_reference_data in field_mapping, or it can be applied to the entire dataset by specifying a language using the 3-character language code representing the language of the address, such as ENG.

  • AS_DEFINED_IN_DATA3-character language code value defined in the reference data for each feature.
  • ENGEnglish
  • FREFrench
  • SPASpanish
String
alternatename_tables
[alternatename_tables,...]
(Optional)

The tables that contain alternate names for the features in the primary role tables.

Value Table
alternate_field_mapping
[alternate_field_mapping,...]
(Optional)

The mapping of alternate name table fields to the alternate name fields supported by the locator role. Each field mapping should use the following format:

The following is an example of alternate_field_mapping for alternatename_tables.

# <locator role alternate field name> <alternate data table field name>

# This shows an example:
alternate_data__table_field_map =
"'*AlternateStreetName.STREET_NAME_JOIN_ID altname.JOINID';"\
"'AlternateStreetName.STREET_PREFIX_DIR altname.PRE_DIR';"\
"'AlternateStreetName.STREET_PREFIX_TYPE altname.PRE_TYPE';"\
"'*AlternateStreetName.STREET_NAME altname.ST_NAME';"\
"'AlternateStreetName.STREET_SUFFIX_TYPE altname.ST_TYPE';"\
"'AlternateStreetName.STREET_SUFFIX_DIR altname.SUF_DIR'"

<locator role alternate field name> is the name of the alternate name field supported by the locator role, and <alternate data table field name> is the name of the field in the alternate name table. Fields with an asterisk (*) next to their names are required by the locator role. Map the relevant fields for each table in alternatename_tables.

Note:

If the data is normalized and the primary table does not contain city name values but the alternate name table does, the Primary Name Indicator field can be mapped to a field in the alternate name table that contains a value that indicates whether the record is the primary field (for exampe, true/false or Yes/No). If this field is not mapped, the first record in the alternate name table will be used as the primary value.

String
custom_output_fields
[custom_output_fields,...]
(Optional)

Adds output fields to the geocode result. The values specified for this parameter will define the names of the output fields that will be returned by the geocode result; however, each new field must be mapped to a field in your reference data. This new output field will apply for all roles that were used in the locator. If the locator role has a left and right side, _left and _right will be appended to the end of the field name.

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

CreateLocator example 1 (stand-alone Python script)

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

# Description: Create a POI locator using a feature class in a file geodatabase that 
# contains points of interest for Arts & Entertainment locations as reference data,
# where country_code and language_code are defined in the data.
# The new locator will be created in a file folder.

# Import system modules
import arcpy

# Set workspace
arcpy.env.workspace = "C:/Data/RhodeIsland"

# Set local variables:
primary_reference_data = "RI_Arts_POI POI"
field_maping = "'POI.PLACE_NAME RI_Arts_POI.PLACE_NAME';"\
               "'POI.CATEGORY RI_Arts_POI.CATEGORY';"\
               "'POI.SUBCATEGORY RI_Arts_POI.SUBCATEGORY';"\
               "'POI.HOUSE_NUMBER RI_Arts_POI.HOUSE_NUMB';"\
               "'POI.STREET_NAME RI_Arts_POI.STREET_NAME';"\
               "'POI.NEIGHBORHOOD RI_Arts_POI.NEIGHBORHOOD';"\
               "'POI.CITY RI_Arts_POI.CITY_NAME';"\
               "'POI.SUBREGION RI_Arts_POI.SUBREGION';"\
               "'POI.REGION RI_Arts_POI.REGION_NAME';"\
               "'POI.POSTAL RI_Arts_POI.POSTAL_CODE';"\
               "'POI.COUNTRY_CODE RI_Arts_POI.COUNTRY_CODE';"\
               "'POI.LANG_CODE RI_Arts_POI.LANGUAGE_CODE';"\
               "'POI.RANK RI_Arts_POI.RANK'"
out_locator = "Arts_Entertainment_POIs"

# Execute CreateLocator
arcpy.geocoding.CreateLocator("AS_DEFINED_IN_DATA", primary_reference_data, field_mapping, 
                              out_locator, "AS_DEFINED_IN_DATA", None, None, None)
CreateLocator example 2 (Python window)

The following Python script demonstrates how to use the CreateLocator function in immediate mode.

# Description: Create a StreetAddress locator using a street centerline feature class in a
# file geodatabase as reference data, where multiple custom_output_fields are added
# to the locator for use in the geocode result. country_code and language_code
# are specified and will be applied to the entire reference dataset.
# The new locator will be created in a file folder.

# Import system modules
import arcpy

# Set workspace
arcpy.env.workspace = "C:/Data/Denver"

# Set local variables
country_code = "USA"
primary_reference_data = "Street_Centerline StreetAddress"
field_mapping = "'StreetAddress.HOUSE_NUMBER_FROM_LEFT Street_Centerline.L_F_ADD';"\
                "'StreetAddress.HOUSE_NUMBER_TO_LEFT Street_Centerline.L_T_ADD';"\
                "'StreetAddress.HOUSE_NUMBER_FROM_RIGHT Street_Centerline.R_F_ADD';"\
                "'StreetAddress.HOUSE_NUMBER_TO_RIGHT Street_Centerline.R_T_ADD';"\
                "'StreetAddress.STREET_PREFIX_DIR Street_Centerline.PREFIX';"\
                "'StreetAddress.STREET_PREFIX_TYPE Street_Centerline.TYPE';"\
                "'StreetAddress.STREET_NAME Street_Centerline.NAME';"\
                "'StreetAddress.STREET_SUFFIX_TYPE Street_Centerline.TYPE';"\
                "'StreetAddress.STREET_SUFFIX_DIR Street_Centerline.SUFFIX';"\
                "'StreetAddress.POSTAL_LEFT Street_Centerline.ZIPLEFT';"\
                "'StreetAddress.POSTAL_RIGHT Street_Centerline.ZIPRIGHT';"\
                "'StreetAddress.CustomField1_left Street_Centerline.LEFTFIRE';"\
                "'StreetAddress.CustomField1_right Street_Centerline.RTFIRE';"\
                "'StreetAddress.CustomField2_left Street_Centerline.LEFTEMS';"\
                "'StreetAddress.CustomField2_right Street_Centerline.RTEMS'"
out_locator = "DenverStreetsCustomFieldsLocator"
language_code = "ENG"

# Execute CreateLocator
arcpy.geocoding.CreateLocator(country_code, primary_reference_data, field_mapping, 
                              language_code, None, None, "CustomField1;CustomField2")
CreateLocator example 3 (Python window)

The following Python script demonstrates how to use the CreateLocator function in immediate mode.

# Create a StreetAddress locator using a street centerline feature class and an alternate
# name table, for alternate street names, in a file geodatabase as reference data.
# The new locator will be created in a file folder.

# Import system modules
import arcpy

# Set workspace
arcpy.env.workspace = "C:/ArcTutor/Geocoding/Atlanta"

# Set local variables
primary_reference_data = "streets StreetAddress"
field_mapping = "'StreetAddress.STREET_NAME_JOIN_ID streets.STREETID';"\
                "'StreetAddress.HOUSE_NUMBER_FROM_LEFT streets.L_F_ADD';"\
                "'StreetAddress.HOUSE_NUMBER_TO_LEFT streets.L_T_ADD';"\
                "'StreetAddress.HOUSE_NUMBER_FROM_RIGHT streets.R_F_ADD';"\
                "'StreetAddress.HOUSE_NUMBER_TO_RIGHT streets.R_T_ADD';"\
                "'StreetAddress.STREET_PREFIX_DIR streets.PREFIX';"\
                "'StreetAddress.STREET_PREFIX_TYPE streets.PRE_TYPE';"\
                "'StreetAddress.STREET_NAME streets.NAME';"\
                "'StreetAddress.STREET_SUFFIX_TYPE streets.TYPE';"\
                "'StreetAddress.STREET_SUFFIX_DIR streets.SUFFIX';"\
                "'StreetAddress.CITY_LEFT streets.CITYL';"\
                "'StreetAddress.CITY_RIGHT streets.CITYR';"\
                "'StreetAddress.REGION_LEFT streets.STATE_ABBR';"\
                "'StreetAddress.REGION_RIGHT streets.STATE_ABBR';"\
                "'StreetAddress.POSTAL_LEFT streets.ZIPL';"\
                "'StreetAddress.POSTAL_RIGHT streets.ZIPR'"
alternatename_tables = "altname AlternateStreetName"
alternate_field_mapping = "'AlternateStreetName.STREET_NAME_JOIN_ID altname.STREETID';"\
                          "'AlternateStreetName.STREET_PREFIX_DIR altname.PRE_DIR';"\
                          "'AlternateStreetName.STREET_PREFIX_TYPE altname.PRE_TYPE';"\
                          "'AlternateStreetName.STREET_NAME altname.ST_NAME';"\
                          "'AlternateStreetName.STREET_SUFFIX_TYPE altname.ST_TYPE';"\
                          "'AlternateStreetName.STREET_SUFFIX_DIR altname.SUF_DIR';"\
                          "'AlternateStreetName.PRIMARY_NAME_INDICATOR altname.PRIMARY'"
out_locator = "AtlantaAlternateStreetsLocator"

# Execute CreateLocator
arcpy.geocoding.CreateLocator("USA", primary_reference_data, field_mapping, out_locator, 
                              "ENG", alternatename_tables, alternate_field_mapping, None)

Environments

This tool does not use any geoprocessing environments.

Licensing information

  • Basic: Yes
  • Standard: Yes
  • Advanced: Yes

Related topics