Create Composite Address Locator (Geocoding)

Summary

Creates a composite locator. A composite locator consists of two or more individual locators that allow addresses and places to be matched using multiple locators.

Learn more about composite locators

Usage

  • Before creating composite locators, use the Create Locator tool or Create Feature Locator tool to create participating locators.

  • Spatial reference for a composite locator is required. The spatial reference of the first participating locator is used unless you specify a different output coordinate system in the tool's environment settings.

  • Use the Order by role and score option for the Result Order parameter for a multirole locator, an ArcGIS StreetMap Premium locator (for example), and several single role locators. This option orders the locators and roles into an optimal fallback order.

  • To generate the correct Python syntax for the in_result_ordering parameter, first run the tool from the Geoprocessing pane using the appropriate Result Order parameter option. Then open the Run menu and select Copy Python Command.

Parameters

LabelExplanationData Type
Address Locators

The locators that will be used to create the composite locator. The order of the participating locators determines how candidates are searched and a place or address is matched. When you geocode a single place or address, the place or address will be matched using all participating locators unless the locator is specified with a selection criterion. All the found candidates will be displayed based on the order of the listed participating locators. If you geocode a table of addresses or places, addresses or places will be matched automatically to the first best candidate found from the first participating locators. If the address or place fails to match, it will fall back to the subsequent locator in the list.

A reference name for each participating locator is required. This is the name of the locator referred to by the composite locator. Do not use spaces or special symbols in the name. The maximum length of the name is 14 characters.

Value Table
Field Map

The mapping of input fields used by each participating locator to the input fields of the composite locator.

This includes the fields and field contents that are generated by the participating locators. Each unique input field is listed in the Field Map parameter. On the left in the Input Fields column, is a list of all the input fields for the composite locator. When you select a field, you can view the fields from each participating locator that are mapped to that field under the Subfield and Properties columns. These fields are the input fields for the composite locator.

Caution:

Do not delete any locator fields from the Field Map parameter. A composite locator created without all locator fields is invalid.

Field Mappings
Selection criteria
(Optional)

The selection criteria for each participating locator. Only one selection criterion is supported for each participating locator.

When building a composite locator, you can specify which locators are used based on the values of input address fields. For example, if the composite locator uses a locator that contains street data for a specific city, you can filter out any addresses or places that do not have that city name. Using selection criteria will disqualify participating locators that do not meet the criteria for a particular address so that the geocoding process will be more efficient. For instance, if a street address locator is specified with a selection criterion as "City" = 'Atlanta', only addresses that contain the city name Atlanta will be geocoded using this locator.

To specify a selection criterion, check the locator check box under the Selection Criteria column that you want to apply the criterion to. You can enter an expression such as "City" = 'Atlanta' in the text box or click the more button to open the Specify Locator Selection Criteria dialog box and define the criteria.

Value Table
Output Composite Address Locator

The composite address locator that will be created. ArcGIS AllSource only supports saving locators in a file folder.

Address Locator
Result Order
(Optional)

Specifies the fallback order of the participating locators to which addresses can be matched to increase the probability of finding the best match when geocoding.

  • Use locator order—Participating locators will be in the order they were added and adhere to the fallback order described in Combine multiple locators into a composite locator. This is the default.
  • Order by role and score—Individual roles of participating locators will be grouped and ordered from most to least precise. Results will be returned for more precise roles first followed by less precise roles, and for results that are returned for different locators with the same role, results will be returned based on score. It is recommended that you use this option if you have a multirole locator and several single role locators or if you have more than one multirole locator. This automatically orders the locators and roles into a recommended, optimal fallback order.
  • Custom order—A customizable fallback order for participating locators will be used that allows you to insert locators between the roles of a multirole locator.
String

arcpy.geocoding.CreateCompositeAddressLocator(in_address_locators, in_field_map, {in_selection_criteria}, out_composite_address_locator, {in_result_ordering})
NameExplanationData Type
in_address_locators
[[in_address_locator, name],...]

The locators that will be used to create the composite locator. The order of the participating locators determines how candidates are searched and a place or address is matched. When you geocode a single place or address, the place or address will be matched using all participating locators unless the locator is specified with a selection criterion. All the found candidates will be displayed based on the order of the listed participating locators. If you geocode a table of addresses or places, addresses or places will be matched automatically to the first best candidate found from the first participating locators. If the address or place fails to match, it will fall back to the subsequent locator in the list.

A reference name for each participating locator is required. This is the name of the locator referred to by the composite locator. Do not use spaces or special symbols in the name. The maximum length of the name is 14 characters.

Value Table
in_field_map

The mapping of input fields used by each participating locator to the input fields of the composite address locator.

For each locator input field, format the field information as in this sample string: "Address 'Address or Intersection' true true false 4 Text 0 0 ,First,'#',Street". The information in this string is composed of the following:

  • New field name (Address)—The new locator field name for the composite locator.

    One locator in the composite may have an Address field and the other locator may have a Street Address field. You can designate the new composite locator field as Address, which references both original locator fields.

  • Alias for the new field name ('Address or Intersection')—The new locator field name alias for the composite locator.

    For a composite locator with the new field name Address, you can designate an alias of 'Address or Intersection' for the field.

  • isEditable (true)—Specifies whether the new composite locator field is editable. The options are true or false.
  • Allow NULL Values (true)—Specifies whether the new composite locator field allows null values. The options are true or false.
  • Required (false)—Specifies whether the new composite locator field is a required field. The options are true or false.
  • Length (4)—The length of the new composite locator field.
  • Type (Text)—The data type of the new composite locator field. This value should always be Text for a locator.
  • Scale (0)—The scale of the new composite locator field. Any value between 1 and 100 can be used. This value does not apply to locators, but a valid value must be used.
  • Precision (0)—The precision of the new composite locator field. Any value between 1 and 100 can be used. This value does not apply to locators, but a valid value must be used.
  • Merge rule (First)—The merge rule for the new composite locator field. Any merge rule value can be used. This value does not apply to locators, but a valid value must be used.
  • Delimiter ('#')—The delimiter for the new composite locator field. Any supported delimiter can be used.
  • Original locator field name (Street)—The locator field name in the original participating locator.
Field Mappings
in_selection_criteria
[[in_address_locator, selection_criteria],...]
(Optional)

The selection criteria for each participating locator. Only one selection criterion is supported for each participating locator.

Using selection criteria will disqualify participating locators that do not meet the criteria for a particular address or place so that the geocoding process will be more efficient. See Fundamentals of combining multiple locators into a composite locator to learn more about the use of selection criteria in the geocoding process.

Value Table
out_composite_address_locator

The composite address locator that will be created. ArcGIS AllSource only supports saving locators in a file folder.

Address Locator
in_result_ordering
(Optional)

Specifies the fallback order of the participating locators to which addresses can be matched to increase the probability of finding the best match when geocoding.

  • Use locator order—Participating locators will be in the order they were added and adhere to the fallback order described in Combine multiple locators into a composite locator. This is the default.
    • Syntax is a comma delimited string of locator names.
    • For a composite locator containing two locators (Atlanta.loc and Memphis.loc, for example), the syntax should be "Atlanta, Memphis".
  • Order by role and score—Individual roles of participating locators will be grouped and ordered from most to least precise. Results will be returned for more precise roles first followed by less precise roles, and for results that are returned for different locators with the same role, results will be returned based on score. It is recommended that you use this option if you have a multirole locator and several single role locators or if you have more than one multirole locator. This automatically orders the locators and roles into a recommended, optimal fallback order.
    • Syntax is a comma delimited string of role groupings structured as [LocatorRole1](LocatorName1.LocatorRole1, LocatorName2.LocatorRole1).
    • For a composite locator containing two multirole locators (Atlanta.loc and Memphis.loc, for example) each containing a PointAddress role and a StreetAddress role, the syntax should be "[PointAddress](Atlanta.PointAddress, Memphis.PointAddress),[StreetAddress](Memphis.StreetAddress,Atlanta.StreetAddress)".
    • Roles must be ordered from most precise to least precise.
  • Custom order—A customizable fallback order for participating locators will be used that allows you to insert locators between the roles of a multirole locator.
    • Syntax is a comma delimited string of locator names and roles structured as LocatorName.LocatorRole.
    • For a composite locator containing two multirole locators (Atlanta.loc and Memphis.loc, for example) each containing a PointAddress role and a StreetAddress role, the syntax should be "Atlanta.StreetAddress,Memphis.PointAddress,Memphis.StreetAddres,Atlanta.PointAddress".
    • Locators and roles can be placed in any order, but placing less precise roles before more precise roles may result in unexpected behavior.

To generate the correct Python syntax, first run the tool from the Geoprocessing pane. Then, open the Run menu and select Copy Python Command.

String

Code sample

CreateCompositeAddressLocator example (Python window)

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

# Create a composite address locator using the StreetMap US Streets and Tutorial Atlanta locators.

# Import system modules
import arcpy 

arcpy.env.workspace = "C:/ArcTutor/Geocoding/atlanta/"

# Set local variables:
US_Streets_locator = "C:/dm_stmap_dvd/streetmap_na/data/Street_Addresses_US"
Atlanta_locator = Atlanta
Atlanta_Composite = US_Atlanta_Composite

# Field mapping
address_field_map = "Address 'Street or Intersection' true true false 100 Text 0 0 ,First,#,Atlanta_locator,Address,0,0,US_Streets_locator,Street;"
city_field_map = "City 'City or Placename' true true false 40 Text 0 0 ,First,#,Atlanta_locator,City,0,0,US_Streets_locator,City;"
state_field_map = "State 'State' true true false 20 Text 0 0 ,First,#,Atlanta_locator,State,0,0,US_Streets_locator,State;"
zip_field_map = "Zip 'Zipcode' true true false 10 Text 0 0 ,First,#,Atlanta_locator,Zip,0,0,US_Streets_locator,ZIP"

composite_locator_field_map = address_field_map + city_field_map + state_field_map + zip_field_map

arcpy.geocoding.CreateCompositeAddressLocator("Atlanta_locator Atlanta;US_Streets_locator US_Streets", composite_loactor_field_map,"Atlanta '\"City\" = 'Atlanta'';US_Streets #",Atlanta_Composite)