batchGeocode (beta)

The ArcGIS Geocoding service supports batch geocoding a file of addresses in CSV (comma-separated values) or zipped CSV format utilizing the batchGeocode endpoint.

The capabilities of batchGeocode are the same as the geocodeAddresses operation. These are the primary differences—

With batchGeocode , the input addresses are passed to the service in a file; with geocodeAddresses , the addresses are passed to the service as a collection of JSON objects.
The batchGeocode process is executed as a job whose status can be monitored, and it does not block, nor is blocked by, other geocoding operations running concurrently.

The batchGeocode workflow is recommended for larger geocoding scenarios, where 100,000 or more addresses need to be geocoded.

Access the services

To access the geocoding service you need the following:

An ArcGIS Location Platform account or ArcGIS Online account.
An access token (API key or OAuth 2.0) with the appropriate privilege.

batchGeocode workflow

Using batchGeocode to batch geocode a file of addresses involves a sequence of steps whereby the output from one operation is used as the input for the next operation. The final output is a downloadable file that includes the original address rows with the x and y coordinates of the geocoded locations appended to them, along with additional informational fields describing the geocoding results. These are the same output fields returned in the JSON response by the geocodeAddresses operation. Each step must be completed in order for the file to be geocoded successfully.

Upload the address file. Upload the file of addresses to the server using addItem. The JSON response includes an id value for the item which is used in the next step.
Submit the geocoding job to the service. Pass the item id from the addItem response, map the fields in your file to the input fields supported by the service, and include any additional geocoding parameters using submitJob. This produces an output jobId value which is used in the next step.
Check the job status. Pass the jobId value from the submitJobs response in a jobs request to check the status of the batchGeocode job. When the returned status value is SUCCEEDED proceed to the next step.
Obtain the URL to download the geocoded file. Make a second jobs request to obtain a URL which is used to download the geocoded file. This request must also include the jobId value from the previous steps.
Download the file. Pass the download URL from the previous step in a final step to download the file that includes the batch geocoding results.

Upload the address file

Use the addItem operation to upload the file of addresses to the portal. The result of the addItem request is an item id property in the JSON response that is associated with the uploaded file of addresses. The id value must be used in subsequent steps to complete the batch geocoding process.

The input file must adhere to the following requirements:

The file must be in CSV (.csv) or zipped CSV (.zip) format.
The file must use UTF-8 encoding with a BOM (byte order mark).
The maximum file size supported by the ArcGIS Geocoding service is 2 GB. If you have a CSV file that exceeds 2 GB you must compress it as a zipped file or reduce the number of records in the file before submitting it to the service.
The filename must be unique for the ArcGIS Online user. If the file already exists as an item in the portal, you can get its ID and use it as the id value in subsequent batch geocoding workflow steps. Alternatively you can delete the item using the Delete Items API call and reupload it using addItem.

Request URL

https://www.arcgis.com/sharing/rest/content/users/{USER_NAME}/addItem

Request parameters

Parameter value	Description
token (Required)	Use this parameter to specify an access token that provides the identity of a user who has the needed permissions to access the service. See Security and authentication for more information about how to generate an access token.
file (Required)	The file name of the address file to be geocoded.

Parameter value

Description

token

(Required)

Use this parameter to specify an access token that provides the identity of a user who has the needed permissions to access the service.

See Security and authentication for more information about how to generate an access token.

file

(Required)

The file name of the address file to be geocoded.

Refer to the addItem topic for complete details about adding a file to a portal.

Example

Use dark colors for code blocksCopy
{
  "success": true,
  "id": "dbbf2fed71784aec9815e91190da5239",
  "folder": ""
}

Submit the geocoding job to the service

Use the submitJob operation to start the geocoding job. The id value returned in the response for the addItem request in the previous step, as well as a token , must be passed in the submitJob request.

Additionally, a field mapping definition must be included in the submitJob request, which aligns the fields in your CSV file with the input fields expected by the ArcGIS Geocoding service. The supported input fields are described in the findAddressCandidates topic. Optional geocoding parameters to refine results may also be included in the request. The additional geocoding parameters are documented in the geocodeAddresses topic.

The result of the submitJob operation is a jobId value that is associated with the geocoding job. This jobId value must be used in all subsequent steps to complete the batch geocoding process.

Request URL

https://geocode-beta.arcgis.com/arcgis/rest/services/World/GeocodeServer/batchGeocode/beta/submitJob

Request parameters

Parameter value Description

Parameter value	Description
token (Required)	Use this parameter to specify an access token that provides the identity of a user who has the needed permissions to access the service. See Security and authentication for more information on how to generate an access token.
item (Required)	The `id` value returned in the response from the `addItem` request in the first step of the `batchGeocode` process. It represents the address file that was uploaded to the portal. It must be passed as a JSON object in the format `item = {'itemID': '<id>'}`.
fieldMapping (Required)	Use this parameter to map the fields in your address table to the input fields expected by the service. The mapping should follow this general format: `<service input field>:<field in address file>` If the entire address is stored in a single field in your file, map it to the SingleLine input field. For instance, if the address field in your file is named "full_address", the `fieldMapping` parameter value should look like this: SingleLine example Use dark colors for code blocksCopy `1 fieldMapping=SingleLine:full_address` If the addresses are split up into individual components, such as street address, city, state, and postal code, map them to the multiline input fields supported by the service. This is referred to as multiline or multifield geocoding. The fields should be separated by commas. As an example, your address file may include the following fields: `street_address` (house number + street name) `municipality` (city name) `state` (state name) `zip_code` (postal code) In this case, the `fieldMapping` parameter value should look like this: Multiline example Use dark colors for code blocksCopy `1 fieldMapping=Address:street_address,City:municipality,Region:state,Postal:zip_code` Tip The `fieldMapping` parameter is case-sensitive. This means that the address file field names must be entered exactly as they appear in the CSV file. For example, if the CSV file includes field name `street_address` , it must be passed this way in the `fieldMapping` parameter: `fieldMapping=Address:street_address` . If the field name is passed in all capital letters, or with any other casing which is different than that in the CSV file - such as `fieldMapping=Address:Street_Address` - an error will be returned by the service.
Additional geocoding parameters (Optional)	There are many optional parameters that can be used to refine or adjust the geocoding results. These are described in detail in the geocodeAddresses topic.

token

(Required)

Use this parameter to specify an access token that provides the identity of a user who has the needed permissions to access the service.

See Security and authentication for more information on how to generate an access token.

item

(Required)

The id value returned in the response from the addItem request in the first step of the batchGeocode process. It represents the address file that was uploaded to the portal. It must be passed as a JSON object in the format item = {'itemID': '<id>'}.

fieldMapping

(Required)

Use this parameter to map the fields in your address table to the input fields expected by the service. The mapping should follow this general format:

<service input field>:<field in address file>

If the entire address is stored in a single field in your file, map it to the SingleLine input field. For instance, if the address field in your file is named "full_address", the fieldMapping parameter value should look like this:

SingleLine example

Use dark colors for code blocksCopy
fieldMapping=SingleLine:full_address

If the addresses are split up into individual components, such as street address, city, state, and postal code, map them to the multiline input fields supported by the service. This is referred to as multiline or multifield geocoding. The fields should be separated by commas.

As an example, your address file may include the following fields:

street_address (house number + street name)
municipality (city name)
state (state name)
zip_code (postal code)

In this case, the fieldMapping parameter value should look like this:

Multiline example

Use dark colors for code blocksCopy
fieldMapping=Address:street_address,City:municipality,Region:state,Postal:zip_code

Additional geocoding parameters

(Optional)

There are many optional parameters that can be used to refine or adjust the geocoding results. These are described in detail in the geocodeAddresses topic.

Example

Use dark colors for code blocksCopy
POST https://geocode-beta.arcgis.com/arcgis/rest/services/World/GeocodeServer/batchGeocode/beta/submitJob HTTP/1.1
content-type: application/x-www-form-urlencoded
User-Agent: <USER AGENT>

item = {'itemID': 'f507a5ddf4f9485c8f8ac6dc6ad9f25f'}
&token=<ACCESS_TOKEN>
&fieldMapping=Address:street_address,City:municipality,Region:state,Postal:zip_code
&<PARAMETERS>

Use dark colors for code blocksCopy
{
  "jobId": "eb3e116d-5e12-44d6-84cc-5647c483f2f5",
  "jobStatus": "esriJobSubmitted",
  "messages": []
}

Check the job status

Use the jobs operation to check the status of the geocoding job. The jobId value returned in the submitJob response must be passed in the jobs request. Additionally, a token must be included in the jobs request.

The jobs operation allows you to monitor the progress of the geocoding job. As you periodically send jobs requests to the service, informational responses are returned which describe the current state of the job. When the geocoding job is complete, the jobs response indicates that the job was successful and provides a URL to the geocoded file. The URL will be used in the next step to download the file.

The jobId value in the response from the submitJob request must be appended to end of the jobs request URL.

Request URL

https://geocode-beta.arcgis.com/arcgis/rest/services/World/GeocodeServer/batchGeocode/beta/jobs/{jobId}

Request parameters

Parameter value	Description
token (Required)	Use this parameter to specify an access token that provides the identity of a user who has the needed permissions to access the service. See Security and authentication for more information on how to generate an access token.

Parameter value

Description

token

(Required)

Use this parameter to specify an access token that provides the identity of a user who has the needed permissions to access the service.

See Security and authentication for more information on how to generate an access token.

Example

This is an example jobs request which can be submitted periodically to get the current state of the geocoding job.

Request

Use dark colors for code blocksCopy
POST https://geocode-beta.arcgis.com/arcgis/rest/services/World/GeocodeServer/batchGeocode/beta/jobs/7aaae43b-b47e-43d1-bff1-75f2d2d2d33f HTTP/1.1
content-type: application/x-www-form-urlencoded
User-Agent: <USER AGENT>

&token=<ACCESS_TOKEN>

As the geocoding job progresses, the jobStatus and status values in the response change according to the status of the job.

Sample response 1

Use dark colors for code blocksCopy
{
  "jobId": "7aaae43b-b47e-43d1-bff1-75f2d2d2d33f",
  "jobStatus": "esriJobSubmitted",
  "status": "SUBMITTED",
  "messages": []
}

Sample response 2

Use dark colors for code blocksCopy
{
  "jobId": "7aaae43b-b47e-43d1-bff1-75f2d2d2d33f",
  "jobStatus": "esriJobSubmitted",
  "status": "RUNNABLE",
  "messages": []
}

Sample response 3

Use dark colors for code blocksCopy
{
  "jobId": "7aaae43b-b47e-43d1-bff1-75f2d2d2d33f",
  "jobStatus": "esriJobSubmitted",
  "status": "STARTING",
  "messages": []
}

Sample response 4

Use dark colors for code blocksCopy
{
  "jobId": "7aaae43b-b47e-43d1-bff1-75f2d2d2d33f",
  "jobStatus": "esriJobExecuting",
  "status": "RUNNING",
  "messages": []
}

Sample response 5

Use dark colors for code blocksCopy
{
  "jobId": "7aaae43b-b47e-43d1-bff1-75f2d2d2d33f",
  "jobStatus": "esriJobExecuting",
  "status": "RUNNING",
  "messages": [
    {
      "description": "Job is 50% complete geocoding...",
      "type": "esriJobMessageTypeInformative"
    }
  ]
}

When the geocoding job is complete, the jobStatus value in the response is esriJobSucceeded . Additional information describing the geocoding results is also in the response. Most importantly, the results object in the response includes the value for the paramUrl object. This information will be used in the next step to access the URL for downloading the geocoded file.

Final response

Use dark colors for code blocksCopy
{
  "jobId": "7aaae43b-b47e-43d1-bff1-75f2d2d2d33f",
  "jobStatus": "esriJobSucceeded",
  "status": "SUCCEEDED",
  "messages": [
    {
      "description": "Total Matched/Tied/Unmatched: 469/26/5",
      "type": "esriJobMessageTypeInformative"
    }
   ],
  "results": {
    "geocodeResult": {
      "paramUrl": "results/geocodeResult"
    }
  }
}

Obtain the download URL

The jobs operation is also used to obtain the URL for downloading the output file that contains the batch geocoding results. As with the previous step for checking the status of the geocoding job, the jobId value returned in the submitJob response must be passed in the jobs request. Additionally, a token must be included in the jobs request.

When jobStatus value in the jobs response from the previous step is esriJobSucceeded , send a second jobs request by appending the value of the paramURL object to the end of the jobs request URL.

Request URL

https://geocode-beta.arcgis.com/arcgis/rest/services/World/GeocodeServer/batchGeocode/beta/jobs/<jobId>/results/geocodeResult

Request parameters

Parameter value	Description
token (Required)	Use this parameter to specify an access token that provides the identity of a user who has the needed permissions to access the service. See Security and authentication for more information on how to generate an access token.

Parameter value

Description

token

(Required)

Use this parameter to specify an access token that provides the identity of a user who has the needed permissions to access the service.

See Security and authentication for more information on how to generate an access token.

Example

Use dark colors for code blocksCopy
POST https://geocode-beta.arcgis.com/arcgis/rest/services/World/GeocodeServer/batchGeocode/beta/jobs/7aaae43b-b47e-43d1-bff1-75f2d2d2d33f/results/geocodeResult HTTP/1.1
content-type: application/x-www-form-urlencoded
User-Agent: <USER AGENT>User-Agent: <USER AGENT>

token: <ACCESS TOKEN>

Use dark colors for code blocksCopy
{
  "paramName": "geocodeResult",
  "dataType": "GPDataFile",
  "value": {
    "url": "https://geocode-beta.arcgis.com/rest/services/World/GeocodeServer/batchGeocode/beta/download/7aaae43b-b47e-43d1-bff1-75f2d2d2d33f.zip"
  }
}

Download the file

The final step in the batchGeocode process is to download the zipped CSV file that contains the batch geocoding results. The URL for the download is included in the response for the previous jobs request in the url object.

Request parameters

Parameter value	Description
token (Required)	Use this parameter to specify an access token that provides the identity of a user who has the needed permissions to access the service. See Security and authentication for more information on how to generate an access token.

Parameter value

Description

token

(Required)

Use this parameter to specify an access token that provides the identity of a user who has the needed permissions to access the service.

See Security and authentication for more information on how to generate an access token.

Example

Use dark colors for code blocksCopy
GET https://geocode-beta.arcgis.com/rest/services/World/GeocodeServer/batchGeocode/beta/download/7aaae43b-b47e-43d1-bff1-75f2d2d2d33f.zip HTTP/1.1
User-Agent: <USER AGENT>
Accept-Encoding: br,gzip
token: <ACCESS TOKEN>

Failed requests

When requests cannot be completed, messages describing the problem are returned by the service. This can be due to invalid parameters included in the request or insufficient user permissions. Some potential errors that may be encountered with the service are described below.

Error messages

Error code 403

Message	Details	Cause	ExtendedCode
Token is valid but access is denied.	User does not have permissions to store geocoding results.	This error is returned when a user with insufficient privileges attempts to geocode a file using the `batchGeocode` operation.	none

Error code 409

Message	Details	Cause	ExtendedCode
Item '{item name}' already exists.	none	This error is returned when an item already exists in the portal with the same name as the filename passed in the `addItem` request.	none

Error code 500

Message	Details	Cause	ExtendedCode
Invalid token.	none	This error is returned when an expired or otherwise invalid access token is included in a `batchGeocode` request.	none

Failed jobs

The batchGeocode process may fail if there is a problem with the input CSV file or if the field mapping is incorrect. In these situations, the status returned by the jobs request will indicate the issue.

Invalid input file format

If the uploaded file is not in the required format, the response for the subsequent jobs request will indicate that the job failed.

Use dark colors for code blocksCopy
{
  "status": "FAILED",
  "logs": "Failed to process input file. Please check that the file is a valid CSV or ZIP file."
}

Invalid service input field

If the field mapping passed in the submitJob request includes a reference to a service input field name which does not exist, the response for the subsequent jobs request will indicate that the job failed and identify the invalid field name.

Use dark colors for code blocksCopy
{
  "status": "FAILED",
  "logs": "Wrong field mapping. Locator has no input field <invalid field>"
}

Invalid CSV field

If the field mapping passed in the submitJob request includes a reference to a nonexistent field name in the input CSV file, the response for the subsequent jobs request will indicate that the job failed and identify the invalid field name. The error is also returned if a field name passed in the fieldMapping parameter of the submitJobs request uses different casing than the corresponding field name in the CSV file. For example, if the field name in the CSV file is CITY , but the name specified in the fieldMapping is City , this error is returned.

Use dark colors for code blocksCopy
{
  "status": "FAILED",
  "logs": "Wrong field mapping. CSV file has no column <invalid field>"
}

Bad CSV header

If there is a problem with the input CSV file's header, the response for the subsequent jobs request will indicate that the job failed and return the following message.

Use dark colors for code blocksCopy
{
  "status": "FAILED",
  "logs": "Can't read csv header"
}