| Label | Explanation | Data Type |
Country or Region | Specifies where country-specific geocoding logic will be applied to the reference data for the locator. The default is the regional setting of the operating system. It can be specified by selecting <As defined in data> from the list and mapping a value from the data in the field mapping, or it can be applied to the entire dataset by selecting a country from the list. It provides a country template containing the expected field names that display in the Field Mapping parameter value for the specified country of the locator to be created.
| String |
Primary Table(s)
| 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. Feature classes represented as services are supported data types for use as primary reference data. Caution:When a definition query is defined for the primary reference data or there are selected features, only the queried and selected features will be 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. | Value Table |
Field Mapping
| The mapping of primary reference dataset fields to the fields supported by the locator role. Fields with an asterisk (*) next to their names are required by the locator role. Map the relevant fields for each table from the Primary Table(s) parameter value. Note:If you are using an alternate name table, map Join ID in the Primary Table(s) parameter value. To add custom output fields, provide the name of the fields in the Custom Output Fields parameter. The new fields will be added to the Field Mapping parameter value. You can then select the fields from the Primary Table(s) parameter value that contain the additional values to be included in the geocode output. | String |
Output Locator
| The output address locator file. | Address Locator |
Language Code
| Specifies where language-specific geocoding logic will 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 selecting <As defined in data> from the list and mapping a value from the primary reference data in the field mapping, or it can be applied to the entire dataset by selecting a language from the list.
| String |
Alternate Name Tables
(Optional) | The tables that contain alternate names for the features in the primary role tables. Tables represented as services are supported data types for use as alternate name tables. Caution:When a definition query is defined for the alternate name table or there are selected records, only the queried and selected records will be included when the locator is created. | Value Table |
Alternate Data Field Mapping
(Optional) | Maps alternate name table fields to the alternate data fields supported by the locator role. Fields with an asterisk (*) next to their names are required by the locator role. Map the relevant fields for each table in Alternate Name 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 example, 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
(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. 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 is appended to the end of the field name. 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:
| String |
Precision Type
(Optional) | Specifies the precision of the locator.
Note:Locators created with Global Extra High or Local Extra High precision can be used in ArcGIS Pro 2.6 or later and Enterprise 10.8.1 or later. | String |
Summary
Creates a locator that can find the location of an address or a place, convert a table of addresses or places to 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. Not all locator functionality may be supported prior to Enterprise 10.7. This will apply as additional functionality is added to newer versions of the software. Locators created by this tool cannot be used as a local locator in ArcMap.
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. Only the roles supported by the selected Country or Region value will be listed along with their corresponding locator role fields.
Note:
- Only one primary table can be used per role when building a locator with this tool.
- The Point of Interest (POI) locator role replaces the place-name alias table, but it requires a point or polygon feature class of place-names along with the associated address in the attribute table.
The primary locator roles provided with ArcGIS Pro allow you to build the following common 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.
- Parcel—An address or parcel name based on points or polygons that represent a plot of land that is considered real property and may include one or more homes or other structures that typically have an address and parcel identification number assigned to it, such as 17 011100120063.
- StreetAddress—A street address based on streets where the house number is interpolated from a range of numbers. This includes intersections, street name, street blocks, and street extension.
- Point of Interest—Administrative divisions, place-names, businesses, landmarks, and geographic features—for example, Starbucks.
- 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.
- 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.
This tool can be used to create a multirole locator. A multirole locator allows you to combine multiple reference data layers and roles into a single locator to search for multiple types of locations at once. If you have multiple layers of the same geometry type that can be assigned to the same role, it is best to merge the layers into a single layer and use the merged layer as the primary reference data for the corresponding role.
Learn more about combining multiple roles into a single locator
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 specified 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 an address is associated with you can geocode the addresses, 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.
Feature classes and tables represented as services are supported data types for use as primary reference data and alternate name tables.
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.
The output of this tool can be used as input to the Create Composite Address Locator tool.
Parameters
arcpy.geocoding.CreateLocator(country_code, primary_reference_data, field_mapping, out_locator, language_code, {alternatename_tables}, {alternate_field_mapping}, {custom_output_fields}, {precision_type})| Name | Explanation | Data Type |
country_code | Specifies where country-specific geocoding logic will be applied to the reference data for the locator. It can be specified using 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 three-character country code name such as USA for the United States of America, CAN for Canada, or PRI for Puerto Rico. 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. Feature classes represented as services are supported data types for use as primary reference data. Caution:When a definition query is defined for the primary reference data or there are selected features, only the queried and selected features will be 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. | 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 in which <role name> is the locator role name, <locator role field name> is the name of the field supported by the locator role, <primary data> is the name of the data used in the primary_reference_data parameter, and <primary data field name> is the name of the field in the primary reference dataset. The following is an example of primary field_mapping. Map the relevant fields for each table from the primary_reference_data parameter. If you do not 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 using <None> in place of a field name. To determine the <locator role field name> value for a reference data field used by a locator role, open the Create Locator tool in ArcGIS Pro 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 the primary_reference_data parameter value. To add 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>' in which <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 | Specifies where language-specific geocoding logic will 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 value 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 three-character language code representing the language of the address, such as ENG for English.
| String |
alternatename_tables [alternatename_tables,...] (Optional) | The tables that contain alternate names for the features in the primary role tables. Tables represented as services are supported data types for use as alternate name tables. Caution:When a definition query is defined for the alternate name table or there are selected records, only the queried and selected records will be included when the locator is created. | Value Table |
alternate_field_mapping [alternate_field_mapping,...] (Optional) | Maps alternate name table fields to the alternate data fields supported by the locator role. Each field mapping must use the following format, in which <alternate name table role> is the name of the alternate name table role, <locator role alternate field name> is the name of the alternate data field supported by the alternate name table locator role, <alternate data table> is the name of the alternate name table, and <alternate data table field name> is the name of the field in the alternate name table. Map the relevant fields for each table in alternatename_tables. The following is an example of alternate_field_mapping for 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 example, 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 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. 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. 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 |
precision_type (Optional) | Specifies the precision of the locator. Note:Locators created with GLOBAL_EXTRA_HIGH or LOCAL_EXTRA_HIGH precision can be used in ArcGIS Pro 2.6 or later and Enterprise 10.8.1 or later.
| String |
Code sample
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_mapping = "'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"
# Run CreateLocator
arcpy.geocoding.CreateLocator("AS_DEFINED_IN_DATA", primary_reference_data, field_mapping,
out_locator, "AS_DEFINED_IN_DATA")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"
# Run CreateLocator
arcpy.geocoding.CreateLocator(country_code, primary_reference_data, field_mapping,
language_code, None, None, "CustomField1;CustomField2")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"
# Run CreateLocator
arcpy.geocoding.CreateLocator("USA", primary_reference_data, field_mapping,
out_locator, "ENG", alternatename_tables,
alternate_field_mapping)The following Python script demonstrates how to use the CreateLocator function in immediate mode.
# Description: Create a multirole locator (PointAddress & StreetAddress) using a hosted
# feature service from ArcGIS Online as reference data.
# 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
# Sign in to ArcGIS Online to use feature services as input
arcpy.SignInToPortal("https://www.arcgis.com", "<username>", "<password>")
# Set local variables
country = "USA"
in_table = "https://services.arcgis.com/<layer_id>/arcgis/rest/services/<service_name>/FeatureServer/<layer_number> PointAddress;"\
"https://services.arcgis.com/<layer_id>/arcgis/rest/services/<service_name>/FeatureServer/<layer_number> StreetAddress"
field_mapping = "'PointAddress.ADDRESS_JOIN_ID 0.PT_ADDR_ID';"\
"'PointAddress.HOUSE_NUMBER 0.ADDRESS';"\
"'PointAddress.STREET_NAME 0.ST_NAME';"\
"'PointAddress.SIDE 0.SIDE';"\
"'PointAddress.CITY 0.CITY';"\
"'PointAddress.REGION 0.STATE';"\
"'StreetAddress.HOUSE_NUMBER_FROM_LEFT 1.L_F_ADD_INT';"\
"'StreetAddress.HOUSE_NUMBER_TO_LEFT 1.L_T_ADD_INT';"\
"'StreetAddress.HOUSE_NUMBER_FROM_RIGHT 1.R_F_ADD_INT';"\
"'StreetAddress.HOUSE_NUMBER_TO_RIGHT 1.R_T_ADD_INT';"\
"'StreetAddress.STREET_PREFIX_DIR 1.PREFIX';"\
"'StreetAddress.STREET_PREFIX_TYPE 1.PRETYPE';"\
"'StreetAddress.STREET_NAME 1.NAME';"\
"'StreetAddress.STREET_SUFFIX_TYPE 1.TYPE';"\
"'StreetAddress.STREET_SUFFIX_DIR 1.SUFFIX';"\
"'StreetAddress.CITY_LEFT 1.PLACENAME_L';"\
"'StreetAddress.CITY_RIGHT 1.PLACENAME_R';"\
"'StreetAddress.REGION_LEFT 1.STATE';"\
"'StreetAddress.REGION_ABBR_LEFT 1.STATE_L';"\
"'StreetAddress.REGION_RIGHT 1.STATE';"\
"'StreetAddress.REGION_ABBR_RIGHT 1.STATE_R'"
out_locator = r"C:\output\locators\MultiroleFeatureServiceBasedLocator"
language = "ENG"
# Run CreateLocator
arcpy.geocoding.CreateLocator(country, in_table, field_mapping, out_locator, language)Environments
Licensing information
- Basic: Yes
- Standard: Yes
- Advanced: Yes
Related topics
- Create Composite Address Locator
- Assign Zones To Streets
- Fundamentals of creating a locator
- Primary locator roles
- Alternate name table roles
- Locator role fields
- Address elements
- Publish a geocode service
- Share a locator
- Split Address Into Components
- An overview of the Geocoding toolbox
- Find a geoprocessing tool