Geocode File (Geocoding)

Summary

Converts large local tables of addresses or places into points in a feature class or as a CSV or XLS table. This tool uses locators hosted on an ArcGIS Enterprise portal.

Note:

This tool works in ArcGIS AllSource 2.4 or later in conjunction with an ArcGIS Enterprise 10.7 or later portal.

Usage

• This tool supports the following table formats as input:

  • Comma-separated values file (.csv)
  • File geodatabase tables
  • Microsoft Excel worksheets (.xls and .xlsx files)

  For input CSV tables, the first row of the input file is used as the field names for the output table in addition to the fields appended from the locator. Field names cannot contain spaces or special characters such as $ or *.

  Learn more about working with Microsoft Excel files in ArcGIS AllSource

  Note:

  The quickest ways to return the geocode results with an input table in the form of a file geodatabase is to limit the contents of the file geodatabase or provide a file geodatabase that contains a single table.

• You can geocode addresses that are stored in a single field, divided into multiple fields, or stored in a single field and a country field. A single input field stores the complete address, for example, 303 Peachtree St NE, Atlanta, GA 30308. Multiple fields are supported if the input addresses are divided into multiple fields such as Address, City, State, and ZIP for a general United States address. A single input field that stores the complete address, for example, 303 Peachtree St NE, Atlanta, GA 30308, and a field that stores the country associated with the address, for example, USA, is also supported.

• Some locators support multiple input address fields such as Address, Address2, and Address3. In this case, the address component can be separated into multiple fields, and the address fields will be concatenated at the time of geocoding. For example, 100, Main St, and Apt 140 across three fields or 100 Main St and Apt 140 across two fields, both become 100 Main St Apt 140 when geocoding.

• An ArcGIS Enterprise 10.7 or later portal is required to use this tool.

• If there is a portal locator that is not available as a utility service on the portal, ask your portal administrator to add the locator as a portal utility service and configure the locator for batch geocoding.

• Use a locator on the ArcGIS Enterprise portal that has been configured to use multiple threads to improve geocoding performance.

• The geocoding results are saved in the same spatial reference as the locator. You can change the spatial reference of the output by setting a different output coordinate system in the tool's environment settings.

• The geocoding results will contain all relevant geocoding information, such as score, status, and the matched address of each record, as well as the values from the original input table. The geocoding results from this tool contain a static snapshot of the original input table, so adding or updating values in the original table will not update the results in the output file. Rerun the tool to create an output file that contains these changes.

• When the geocoding results are returned as a feature class, the addresses can be rematched using the Rematch Addresses tool or the Rematch Addresses option that opens the Rematch Addresses pane.

  Note:

  The table must be geocoded with a locator on an ArcGIS Enterprise 10.8 portal that has more than one thread for batch geocoding.

  Learn more about rematching geocoding results

• When using an input locator built with z-aware data, the tool will return output that is not z-aware. Only 2D output is supported in this tool.

• The tool does not apply configurations from a locator view created in ArcGIS Pro 3.2 when using it as the Locator parameter value.

Parameters

Dialog

Label	Explanation	Data Type
Input Table	The input table that contains addresses or places to geocode in CSV, XLS, or XLSX format or in a file geodatabase table.	Record Set
Locator	The portal locator that will be used to geocode the table. You can choose a locator from the populated list of locators on the active portal or browse the active portal for other available locators. Locators that have been set as utility services on the active portal will be available by default. Note: The ArcGIS World Geocoding Service is disabled for this tool. Use the Geocode Addresses tool if you want to use the ArcGIS World Geocoding Service.	Address Locator
Address Field Mapping	The address fields used by the locator are mapped to fields in the input table of addresses. Specify Single Field if the complete address is stored in one field in the input table, for example, 303 Peachtree St NE, Atlanta, GA 30308. Specify Multiple Fields if the input addresses are divided into multiple fields such as Address, City, State, and ZIP for a general United States address. Specify Single Field and Country Field if the complete address, for example, 303 Peachtree St NE, Atlanta, GA 30308, and the country, for example, USA, are divided into separate fields such as Address and Country. Some locators support multiple input addresses fields such as Address, Address2, and Address3. In this case, the address component can be separated into multiple fields, and the address fields will be concatenated at the time of geocoding. For example, 100, Main st, and Apt 140 across three fields, or 100 Main st and Apt 140 across two fields, both become 100 Main st Apt 140 when geocoding. If you do not map an optional input address field used by the locator to a field in the input table of addresses, specify that there is no mapping using <None> in place of a field name.	Field Info
Output Type	Specifies the file type to which the geocode results will be written. CSV—A .csv file will be returned. Feature class—A feature class in a file geodatabase will be returned. XLS—An .xls file will be returned.	String
Output Location	The folder where the output geocoding results will be written. If the output is a .csv or .xls file, an output file will be placed in the specified folder. If the output is a feature class, an output file geodatabase will be created and placed in the specified folder, and the new file geodatabase will contain the geocoded feature class. The output file geodatabase and feature class in the file geodatabase will have the same name.	Workspace
Output Name	The name of the output geocoded results.	String
Country (Optional)	The country or countries that will be searched for the geocoded addresses. This parameter is available for locators that support a country parameter and will limit geocoding to the specified countries. Specifying a country will improve the accuracy of geocoding in most cases. When you specify Single Field and Country Field in the Address Field Mapping parameter and map a field representing countries in the Input Table parameter value to the Country field for the Address Field Mapping parameter, the country value from the Input Table parameter will override the Country parameter. This is limited to the specified country or countries. When no country is specified, geocoding is performed using all supported countries of the locator. The Country parameter is not supported for all locators.	String
Preferred Location Type (Optional)	Specifies the preferred output geometry that will be returned for PointAddress matches. The options for this parameter are Routing location, which is the side of street location that can be used for routing and Address location, which is the location that represents the rooftop or parcel centroid for the address. If the preferred location does not exist in the data, the default location will be returned. For geocode results with Addr_type=PointAddress, the x,y attribute values describe the coordinates of the address along the street, and the DisplayX and DisplayY values describe the rooftop or building centroid coordinates. This parameter is not supported for all locators. Address location—Geometry for geocode results that represent an address location such as a rooftop location, parcel centroid, or front door will be returned. Routing location—Geometry for geocode results that represent a location close to the side of the street that can be used for vehicle routing will be returned. This is the default.	String
Category (Optional)	Limits the types of places the locator searches, eliminating false positive matches and potentially speeding up the search process. When no category is used, geocoding is performed using all supported categories. Not all category values are supported for all locations and countries. In general, this parameter can be used for the following: Limit matches to specific place types or address levels Avoid fallback matches to unwanted address levels Disambiguate coordinate searches This parameter is not supported for all locators.	String
Output Fields (Optional)	Specifies the locator output fields that will be returned in the geocode results. All— Includes all available locator output fields in the geocode results. This is the default. Location Only—The Shape field will be stored if the geocode result is a feature class. The Shape X and Shape Y fields will be stored if the result is either a .csv or .xls file. The original field names from the Input Table parameter will be maintained with their original field names. Minimal—Adds the following fields that describe the location and how well it matches information in the locator in the geocode results: Shape, Status, Score, Match_type, Match_addr, and Addr_type. The original field names from the Input Table parameter value will be maintained. Minimal and User Fields—Adds the following fields that describe the location and how well it matches information in the locator, as well as any user-defined custom output fields in the geocode results: Shape, Status, Score, Match_type, Match_addr, and Addr_type. The original field names from the Input Table parameter value will be maintained. Note: This parameter can be used with input locators created with the Create Locator or Create Feature Locator tool published to Enterprise 10.9 or later. Composite locators that contain at least one locator created with the Create Address Locator tool do not support this parameter.	String

Derived Output

Label	Explanation	Data Type
Output Feature Class	The output feature class.	Feature Class
Output Table	The output table in CSV or XLS format, depending on the Output Type value.	Table

Python

arcpy.geocoding.GeocodeFile(in_table, locator, address_fields, output_type, output_location, output_name, {country}, {location_type}, {category}, {output_fields})

Name	Explanation	Data Type
in_table	The input table that contains addresses or places to geocode in CSV, XLS, or XLSX format or in a file geodatabase table.	Record Set
locator	The portal locator that will be used to geocode the table. You can choose a locator from the populated list of locators on the active portal or browse the active portal for other available locators. Locators that have been set as utility services on the active portal will be available by default. Note: The ArcGIS World Geocoding Service is disabled for this tool. Use the Geocode Addresses tool if you want to use the ArcGIS World Geocoding Service.	Address Locator
address_fields	Each field mapping in this parameter is in the format input_locator_field, table_field_name in which input_locator_field is the name of the input address field specified by the locator, and table_field_name is the name of the corresponding field in the table of addresses you want to geocode. You can specify a single input field that stores the complete address, for example, 303 Peachtree St NE, Atlanta, GA 30308. Alternatively, you can specify multiple fields if the input addresses are divided into multiple fields such as Address, City, State, and ZIP for a general United States address. You can also specify a single input field that stores the complete address, for example, 303 Peachtree St NE, Atlanta, GA 30308, and a field that stores the country associated with the address, for example, USA. Some locators support multiple input addresses fields such as Address, Address2, and Address3. In this case, the address component can be separated into multiple fields and the address fields will be concatenated at the time of geocoding. For example, 100, Main st, and Apt 140 across three fields or 100 Main st and Apt 140 across two fields, both become 100 Main st Apt 140 when geocoding. If you do not map an optional input address field used by the locator to a field in the input table of addresses, specify that there is no mapping using <None> in place of a field name.	Field Info
output_type	Specifies the file type to which the geocode results will be written. CSV—A .csv file will be returned. FEATURE_CLASS—A feature class in a file geodatabase will be returned. XLS—An .xls file will be returned.	String
output_location	The folder where the output geocoding results will be written. If the output is a .csv or .xls file, an output file will be placed in the specified folder. If the output is a feature class, an output file geodatabase will be created and placed in the specified folder, and the new file geodatabase will contain the geocoded feature class. The output file geodatabase and feature class in the file geodatabase will have the same name.	Workspace
output_name	The name of the output geocoded results.	String
country [country,...] (Optional)	The country or countries that will be searched for the geocoded addresses. This parameter is available for locators that support a country parameter and will limit geocoding to the specified countries. Specifying a country will improve the accuracy of geocoding in most cases. If a field representing countries in the in_table parameter is mapped to the Country field in address_fields, the country value from the in_table parameter will override the country parameter. This is limited to the specified country or countries. If no country is specified, geocoding is performed on all supported countries of the locator. Specify the value as either two-character or three-character country codes in a comma-separated list. See the Supported Country Codes column for the input value to use. The country parameter is not supported for all locators.	String
location_type (Optional)	Specifies the preferred output geometry that will be returned for POINT_ADDRESS matches. The options for this parameter are ROUTING_LOCATION, which is the side of street location that can be used for routing and ADDRESS_LOCATION, which is the location that represents the rooftop, parcel centroid for the address, or front door. If the preferred location does not exist in the data, the default location of ROUTING_LOCATION will be returned. For geocode results with Addr_type=PointAddress, the x,y attribute values describe the coordinates of the address along the street, and the DisplayX and DisplayY values describe the rooftop or building centroid coordinates. See the ArcGIS REST API web help for details about the locationType parameter for geocodeAddresses. This parameter is not supported for all locators. ADDRESS_LOCATION—Geometry for geocode results that represent an address location such as a rooftop location, parcel centroid, or front door will be returned. ROUTING_LOCATION—Geometry for geocode results that represent a location close to the side of the street that can be used for vehicle routing will be returned. This is the default.	String
category [category,...] (Optional)	Limits the types of places the locator searches, eliminating false positive matches and potentially speeding up the search process. When no category is used, geocoding is performed using all supported categories. Not all category values are supported for all locations and countries. In general, this parameter can be used for the following: Limit matches to specific place types or address levels Avoid fallback matches to unwanted address levels Disambiguate coordinate searches This parameter is not supported for all locators. See the ArcGIS REST API web help for details about category filtering.	String
output_fields (Optional)	Specifies the locator output fields that will be returned in the geocode results. Note: This parameter can be used with input locators created with the Create Locator or Create Feature Locator tool published to Enterprise 10.9 or later. Composite locators that contain at least one locator created with the Create Address Locator tool do not support this parameter. ALL— Includes all available locator output fields in the geocode results. This is the default. LOCATION_ONLY—The Shape field will be stored if the geocode result is a feature class. The Shape X and Shape Y fields will be stored if the result is either a .csv or .xls file. The original field names from the in_table parameter will be maintained with their original field names. MINIMAL—Adds the following fields that describe the location and how well it matches information in the locator in the geocode results: Shape, Status, Score, Match_type, Match_addr, and Addr_type. The original field names from the in_table parameter value will be maintained. MINIMAL_AND_USER—Adds the following fields that describe the location and how well it matches information in the locator in the geocode results, as well as any user-defined custom output fields: Shape, Status, Score, Match_type, Match_addr, and Addr_type. The original field names from the in_table parameter value will be maintained.	String

Derived Output

Name	Explanation	Data Type
out_feature_class	The output feature class.	Feature Class
out_table	The output table in CSV or XLS format, depending on the Output Type value.	Table

Code sample

GeocodeFile example (stand-alone script)

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

Note:

If you are working with locators on your portal, ensure that you are signed in and set it as the active portal in ArcGIS AllSource. To access a locator that is on a portal other than the active portal, authenticate using the SignInToPortal function.

import arcpy

# Input is a local table
input_table = r"C:\data\customers.csv"

# This tool works with locators on a portal
in_locator = "https://<machine_name>/server/rest/services/<service_name>/GeocodeServer/<service_name>"

# The best way to generate a field mapping is to run the tool in ArcGIS 
# Pro, right-click the green success ribbon, and click "Copy Python command"

field_mapping = "'Address or Place' Address VISIBLE NONE;Address2 <None> VISIBLE NONE;Address3 <None> VISIBLE NONE;Neighborhood <None> VISIBLE NONE;
City <None> VISIBLE NONE;County <None> VISIBLE NONE;State <None> VISIBLE NONE;ZIP ZIP VISIBLE NONE;ZIP4 <None> VISIBLE NONE;Country <None> VISIBLE NONE"
output_type = "FEATURE_CLASS"

# Output folder for the output CSV, Excel, or GDB table. If you select 
# FEATURE_CLASS output_type, a new GDB will be created in the 
# output_folder with the geocoding results
output_folder = r"C:\data\outputs"
output_name = "Geocoding_output"

# Optional geocoding parameters. Only some are supported depending on the 
# in_locator that you use.
country = None
location_type = "ROUTING_LOCATION"
category = "'Street Address'"

arcpy.geocoding.GeocodeFile(input_table, in_locator, field_mapping, output_type, 
                            output_folder, output_name, country, location_type, 
                            category)

Environments

Current Workspace, Output Coordinate System