Summary
Creates a locator that can 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. 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. 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, and street extension.
- Point of Interest—Consists of 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.
The Create Locator 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.
Learn more about combining multiple roles into a single locator
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.
Syntax
arcpy.geocoding.CreateLocator(country_code, primary_reference_data, field_mapping, out_locator, language_code, {alternatename_tables}, {alternate_field_mapping}, {custom_output_fields}, {precision_type})| Parameter | 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 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 Three-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. 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 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. | 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 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 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 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 primary_reference_data. 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 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.
| 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 are 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 should 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 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 |
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, 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"
# Execute 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"
# Execute 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"
# Execute 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 multi-role 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"
# Execute CreateLocator
arcpy.geocoding.CreateLocator(country, in_table, field_mapping, out_locator, language)Environments
Licensing information
- Basic: Yes
- Standard: Yes
- Advanced: Yes