Skip To Content

Geocode File

Summary

Converts large local tables of addresses or places into points in a feature class or as a stand-alone .csv or .xls table. This tool uses locators hosted on an ArcGIS Enterprise portal.

Note:

This tool is designed to work in ArcGIS Pro 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 Pro

    Note:

    The quickest way 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 or multiple fields. 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.

  • 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 would both become 100 Main St Apt 140 when geocoding.

  • This tool requires an ArcGIS Enterprise 10.7 or later portal.

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

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

  • The geocoding results are saved in the same spatial reference as the locator. Changing the spatial reference of the output is possible 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 any values in the original table will not update the results in the output file. Rerun the tool to create a new output file that contains these changes.

Syntax

GeocodeFile(in_table, locator, address_fields, output_type, output_location, output_name, {country}, {location_type}, {category})
ParameterExplanationData Type
in_table

The input table that contains addresses or places to geocode in CSV, XLS, or XLSX format, or a file geodatabase table.

Record Set
locator

The portal locator that will be used to geocode the table.

A populated list of locators is on the active portal. You can select a locator from this list 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 where 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.

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, Apt 140 across three fields or 100 Main St and Apt 140 across two fields would both become 100 Main St Apt 140 when geocoding.

If you choose not to 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

The file type to which the geocode results will be written.

  • CSVReturns a comma-separated values file.
  • FEATURE_CLASSReturns a feature class in a file geodatabase.
  • XLSReturns a Microsoft Excel file (.xls).
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 to search for the geocoded addresses. This parameter is available for locators that support a country parameter and will limit geocoding to the selected countries. Making a country selection will improve the accuracy of geocoding in most cases. If a field representing countries in the Input Table parameter is mapped to the Country Role: Field Name, the country value from the Input Table parameter will override the Country parameter.

If no country is specified, geocoding is performed on all supported countries of the locator. The input value should be specified as an ISO 3166-1 3-character country code.

The Country parameter is not supported for all locators.

String
location_type
(Optional)

Specifies the preferred output geometry for POINT_ADDRESS matches. The options for this parameter are ROUTING_LOCATION, the side of street location that can be used for routing, or ADDRESS_LOCATION, 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 instead. For geocode results with Addr_type=PointAddress, the x,y attribute values describe the coordinates of the address along the street, while the DisplayX and DisplayY values describe the rooftop or building centroid coordinates. See the REST API web help for details about the locationType parameter for reverseGeocode.

This parameter is not supported for all locators.

  • ADDRESS_LOCATIONReturns geometry for geocode results that represent an address location such as a rooftop location, parcel centroid, or front door.
  • ROUTING_LOCATIONReturns geometry for geocode results that represent a location close to the side of the street that can be used for vehicle routing. 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 on all supported categories. Not all category values are supported for all locations and countries. In general, the Category 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 REST API web help for details about category filtering.

String

Derived Output

NameExplanationData 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 chosen.

Table

Code sample

GeocodeFile example (stand-alone script)

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

import arcpy

arcpy.SignInToPortal("https://<machine_name>/<portal_web_adaptor_name>", 
                     '<username>', '<password>')

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

# this tool works with locators on your Portal
in_locator = "https://<machine_name>/server/rest/services/<service_name>/GeocodeServer/<service_name>"

# The easiest way to generate a field mapping is by running the tool in ArcGIS 
# Pro and 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 user selects 
# FEATURE_CLASS output_type, then 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)

Licensing information

  • Basic: Requires your account in ArcGIS Enterprise to have the Perform Analysis privilege
  • Standard: Requires your account in ArcGIS Enterprise to have the Perform Analysis privilege
  • Advanced: Requires your account in ArcGIS Enterprise to have the Perform Analysis privilege

Related topics