Batch Geocode (Geocoding Tools)

Summary

Geocodes a large table or .csv file of addresses or places asynchronously using the batchGeocode REST API. The geocoded results are returned as a feature class and do not require ArcGIS Pro to chunk the request into smaller batches.

When using this tool, geocoding can be isolated and scaled on the server independent of other processes. For example, when submitting a job to the ArcGIS World Geocoding Service, dedicated hardware will be assigned to process the file, resulting in a faster response. You can select either the ArcGIS World Geocoding Service or a service hosted in ArcGIS Enterprise on Kubernetes 11.5 or later with your configured Kubernetes cluster.

Note:

Performing geocoding operations using the ArcGIS World Geocoding Service requires an ArcGIS organizational account, and consumes credits. The organizational account must have enough credits to complete the entire geocoding request.

Credit estimation is shown at the top of the tool in the Geoprocessing pane when the active portal is ArcGIS Online.

Usage

When using the ArcGIS World Geocoding Service as the Input Batch Service parameter value, the input table or file must have at least 100,000 records.
When using the ArcGIS World Geocoding Service as the Input Batch Service parameter value, the Input Table parameter value is temporarily stored in your ArcGIS Online portal until the job has completed. After the job has finished, the temporary file will be deleted from the portal.
The maximum number of records supported by this tool is 50 million. If the table exceeds 50 million records, split the table into multiple tables with 50 million or less records. If the input is a .csv file, it must use UTF-8 encoding with a byte order mark (BOM).

Note:

You can use a third-party application such as Microsoft Excel or Notepad++ to add a UTF-8 BOM to the .csv file.
The first row of the input .csv file is used as the field names for the output feature class in addition to the fields appended from the locator. Field names cannot contain spaces or special characters other than an underscore.

Note:

When using the tool in Python, the fields of the table_field_name parameter value must be in the same case as the fields for the input_address_field parameter value for field mapping using the address_fields parameter.
When the locator is published to ArcGIS Enterprise on Kubernetes with the Batch Geocode capability enabled, two services are created: a GeocodeServer service and a GPServer service. When using the tool in Python, the in_batch_service parameter value must be the GPServer, for example, https://machinename.domain.com/server/rest/services/service_name/GPServer .
The geocoding results are saved in the same spatial reference as the service. You can change the spatial reference of the output by setting the Output Coordinate System environment.
The geocoding results will contain all relevant geocoding information, including score, status, and the matched address of each record, as well as the values from the original input table or file. 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 feature class. Rerun the tool to create an output feature class that contains these changes.
The following parameters are not supported for all batch services used for the Input Batch Service parameter value: Country or Region, Preferred Location Type, and Category.
This tool does not support selections. To geocode a portion of a table, export the part of the table you want to geocode and run the tool on the new, smaller table.

Label	Explanation	Data type
Input Table	The table or `.csv` file of addresses or places that will be geocoded.	Table View
Input Batch Service	The geocode service on the portal with batch geocode support that will be used to geocode the table of addresses and places. Note: If the service is a custom locator or an ArcGIS StreetMap Premium locator, it must be published to ArcGIS Enterprise on Kubernetes 11.5 or later with the Batch Geocode capability enabled.	String
Address Field Mapping	The mapping of address fields used by the locator to fields in the input table or file of addresses. Specify Single Field if the complete address is stored in one field in the input table or file, 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 and the country are divided into separate fields such as `Address` (303 Peachtree St NE, Atlanta, GA 30308) and `Country` (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 address locator to a field in the input table or file of addresses, specify that there is no mapping using <None> in place of the field name.	Field Info
Output Feature Class	The output geocoded feature class. Note: Saving the output to shapefile format is not supported due to shapefile limitations.	Feature Class
Country or Region	The country or countries that the search will be limited to for the geocoded addresses. Specifying a country will improve the accuracy of geocoding in most cases. When no country is specified, geocoding is performed using all supported countries of the locator. This parameter value will be overridden when you specify Single Field and Country Field for the Address Field Mapping parameter.	String
Preferred Location Type (Optional)	Specifies the preferred output geometry that will be returned for `PointAddress` matches. If the preferred location does not exist in the data, the default location will be returned. See the ArcGIS REST API web help for details about the `locationType` parameter for `geocodeAddresses`. Address location—Geometry for geocode results that represent an address location such as a rooftop location, parcel centroid, or front door will be returned. This is the default. 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.	String
Category (Optional)	Limits the types of places the locator searches, which eliminates false positive matches, unwanted address level matches, or disambiguates coordinate searches. This parameter can help speed 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. 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. The original field names from the Input Table parameter value will be maintained if the Location Only, Minimal, or Minimal and User Fields option is specified. All—Includes all available locator output fields in the geocode results. This is the default. Location Only—Stores the `Shape` field in the geocode results. 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`. Minimal and User Fields—The `MINIMAL` fields, as well as any user-defined custom output fields, will be added and returned in the geocode results.	String
Match Narrative (Optional)	Specifies how the match narrative will be returned in the output geocoded feature class. If no parameter value is specified, the Include match narrative locator property setting will be used. This parameter can help better understand how addresses were matched in the geocoded feature class. Add match narrative to output—A field named `MatchNarrative` will be added to the geocoded feature class. This field contains the match narrative text for each matched address. Split match narrative into fields—The single field match narrative text will be pulled from the JSON object. The match narrative text will be parsed, split into individual fields, and appended to the geocoded feature class.	String

arcpy.geocoding.BatchGeocode(in_table, in_batch_service, address_fields, out_feature_class, country, {location_type}, {category}, {output_fields}, {match_narrative})

Name	Explanation	Data type
in_table	The table or `.csv` file of addresses or places that will be geocoded.	Table View
in_batch_service	The geocode service on the portal with batch geocode support that will be used to geocode the table of addresses and places. Note: If the service is a custom locator or an ArcGIS StreetMap Premium locator, it must be published to ArcGIS Enterprise on Kubernetes 11.5 or later with the Batch Geocode capability enabled.	String
address_fields	Each field mapping in this parameter is in the format `input_address_field, table_field_name` in which `input_address_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 or file of addresses you want to geocode. Specify a single input field if the complete address is stored in one field in the `in_table` value, 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 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. If you do not map an optional input address field used by the address locator to a field in the input table or file of addresses, specify that there is no mapping using `<None>` in place of the field name.	Field Info
out_feature_class	The output geocoded feature class. Note: Saving the output to shapefile format is not supported due to shapefile limitations.	Feature Class
country [country,...]	The country or countries that the search will be limited to for the geocoded addresses. Specifying a country will improve the accuracy of geocoding in most cases. If no country is specified, geocoding is performed using all supported countries of the locator. This parameter value will be overridden when a field in the `in_table` parameter value is mapped to the `Country` field in the `address_fields` parameter. 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.	String
location_type (Optional)	Specifies the preferred output geometry that will be returned for `PointAddress` matches. If the preferred location does not exist in the data, the default location of `ADDRESS_LOCATION` will be returned. See the ArcGIS REST API web help for details about the `locationType` parameter for `geocodeAddresses`. `ADDRESS_LOCATION`—Geometry for geocode results that represent an address location such as a rooftop location, parcel centroid, or front door will be returned. This is the default. `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.	String
category [category,...] (Optional)	Limits the types of places the locator searches, which eliminates false positive matches, unwanted address level matches, or disambiguates coordinate searches. This parameter can help speed 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. 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. The original field names from the `in_table` parameter value will be maintained if the `LOCATION_ONLY`, `MINIMAL`, or `MINIMAL_AND_USER` option is specified. `ALL`—Includes all available locator output fields in the geocode results. This is the default. `LOCATION_ONLY`—Stores the `Shape` field in the geocode results. `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`. `MINIMAL_AND_USER`—The `MINIMAL` fields, as well as any user-defined custom output fields, will be added and returned in the geocode results.	String
match_narrative [match_narrative,...] (Optional)	Specifies how the match narrative will be returned in the output geocoded feature class. If no parameter value is specified, the Include match narrative locator property setting will be used. This parameter can help better understand how addresses were matched in the geocoded feature class. `ADD_MATCH_NARRATIVE`—A field named `MatchNarrative` will be added to the geocoded feature class. This field contains the match narrative text for each matched address. `SPLIT_MATCH_NARRATIVE`—The single field match narrative text will be pulled from the JSON object. The match narrative text will be parsed, split into individual fields, and appended to the geocoded feature class.	String

Code sample

BatchGeocode example 1 (stand-alone script)

The following script demonstrates how to use the BatchGeocode function to geocode a .csv file with the ArcGIS World Geocoding Service and return MINIMAL output_fields in the geocode result.

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 Pro. To access a locator that is on a portal other than the active portal, authenticate using the SignInToPortal function.

Note:

When using the ArcGIS World Geocoding Service, this operation may consume credits.

import arcpy

# Set local variables

# Input is a local file
in_table = r"C:\data\customers.csv"

# Sign in to Portal
#arcpy.SignInToPortal("https://www.arcgis.com.", "MyUsername", "MyPassword")

in_batch_service = "https://geocode.arcgis.com/arcgis/rest/services/World/GPServer/BatchGeocode/"

# One way to generate the value for the field mapping parameter is to first run the tool in ArcGIS
# Pro and right-click the green success ribbon and click "Copy Python command"
# The table_field_name fields must be in the same case as the input_address_field fields.

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

geocode_result = r"C:\Mydata\results.gdb\geocode_results"

# Optional geocoding parameters. Only some are supported depending on the in_batch_service that you use.
country = USA
location_type = "ADDRESS_LOCATION"
category = "'Point Address'"
output_fields = "MINIMAL"

arcpy.geocoding.BatchGeocode(in_table, in_batch_service, address_fields, geocode_result,
                             country, location_type, category, output_fields)

BatchGeocode example 2 (stand-alone script)

The following script demonstrates how to use the BatchGeocode function to geocode a table with a portal batch service with the default output_fields in the geocode result.

Note:

import arcpy

# Set local variables

# Input is a local file
in_table = r"C:\data\mytables.gdb\restaurants"

in_batch_service = "https://machinename.domain.com/server/rest/services/service_name/GPServer/"

# One way to generate the value for the field mapping parameter is to first run the tool in ArcGIS
# Pro and right-click the green success ribbon and click "Copy Python command"
# The table_field_name fields must be in the same case as the input_address_field fields.

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

geocode_result = r"C:\My_Output.gdb\geocode_result"

# Optional geocoding parameters. Only some are supported depending on the in_batch_service that you use.
country = USA
location_type = "ROUTING_LOCATION"
category = "'Point Address'"
output_fields = "ALL"

arcpy.geocoding.BatchGeocode(in_table, in_batch_service, address_fields, geocode_result,
                             country, location_type, category, output_fields)

Environments

Output Coordinate System

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

Batch Geocode (Geocoding Tools)

Summary

Note:

Usage

Note:

Note:

Parameters

Note:

Note:

Environments

Licensing information

Related topics