PUT https://geocode-beta.arcgis.com/arcgis/rest/services/World/GeocodeServer/batchGeocode/beta/upload HTTP/1.1
Content-Type: application/binary
User-Agent: <USER AGENT>
Content-Disposition: attachment; filename=<USER_FILENAME>
token: <ACCESS TOKEN>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.
Note:
batchGeocode usage will be billed during the beta period.
Note:
South Korea address geocoding is not supported by batchGeocode. The geocodeAddresses operation must be used for that.
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.
Note:
If you have an ArcGIS Online account or an ArcGIS Location Platform account the premium:user:geocode:stored privilege is always required for batchGeocode requests.
Tip:
To learn how to get an access token, see Security and authentication.
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 upload. This produces an output item JSON object which is used in the next step.
Submit the geocoding job to the service. Pass the item object, 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 item object from the upload response and 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 item object and 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.
Tip:
The same User-Agent value should be included in the header for all of the requests in the batchGeocode workflow.
Note:
An access token is required for each step.
Note:
URL encoding is enforced by ArcGIS Online and the ArcGIS Geocoding service. Ensure the request URLs sent to the service are properly encoded and patterned after the examples in this topic.Note:
The REST request URL must include HTTPS. Requests with HTTP are not supported.
Upload the address file
Use the upload operation to upload the file of addresses to the server. The upload request must use PUT because this operation sends data to the server. The result of the upload operation is an item JSON object that is associated with the uploaded file of addresses. This item object must be used in all 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.
Note:
You may use a third-party application such as Microsoft Excel or Notepad++ to add a UTF-8 BOM to your CSV file.
Request URL
| https://geocode-beta.arcgis.com/arcgis/rest/services/World/GeocodeServer/batchGeocode/beta/upload |
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. |
filename (Required) | The file name of the address file to be geocoded. |
The parameters must be included in the header of the PUT request when using the upload operation.
- The filename value must be specified in the “Content-Disposition” element of the header: "Content-Disposition": "attachment; filename=myFileName.zip".
- The token value header must also be specified in the request header: "token": "myToken".
- Additionally, the "Content-Type" element should be set to application/binary in the request header: "Content-Type": "application/binary".
Example
{
"success": true,
"item": {
"itemID": "dbbf2fed71784aec9815e91190da5239",
"itemName": "<user_filename>",
"description": "",
"date": 0,
"committed": true,
"serviceName": "batchGeocode",
"contentType": "application/binary"
}
}Submit the geocoding job to the service
Use the submitJob operation to start the geocoding job. The item JSON object returned in the response for the upload 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.
Note:
The submitJob request may use either the GET or POST methods.
Request URL
| https://geocode-beta.arcgis.com/arcgis/rest/services/World/GeocodeServer/batchGeocode/beta/submitJob |
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. |
item (Required) | The item JSON object returned in the response from the upload request in the first step of the batchGeocode process. It represents the address file that was uploaded to the server. |
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: 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:
In this case, the fieldMapping parameter value should look like this:
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. |
Example
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": "dbbf2fed71784aec9815e91190da5239",
"itemName": "<user_filename>",
"description": "",
"date": 0,
"committed": true,
"serviceName": "batchGeocode",
"contentType": "application/binary"
}
&token=<ACCESS_TOKEN>
&fieldMapping=Address:street_address,City:municipality,Region:state,Postal:zip_code
&<PARAMETERS>
{
"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 item JSON object returned in the response for the upload request in the first step, as well as 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.
Note:
The jobs request may use either the GET or POST methods.
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. |
item (Required) | The item JSON object returned in the response from the upload request in the first step of the batchGeocode process. It represents the address file that was uploaded to the server. |
Example
This is an example jobs request which can be submitted periodically to get the current state of the geocoding job.
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>
"item": {
"itemID": "dbbf2fed71784aec9815e91190da5239",
"itemName": "<user_filename>",
"description": "",
"date": 0,
"committed": true,
"serviceName": "batchGeocode",
"contentType": "application/binary"
}
&token=<ACCESS_TOKEN>As the geocoding job progresses, the jobStatus and status values in the response change according to the status of the job.
{
"jobId": "7aaae43b-b47e-43d1-bff1-75f2d2d2d33f",
"jobStatus": "esriJobSubmitted",
"status": "SUBMITTED",
"messages": []
}{
"jobId": "7aaae43b-b47e-43d1-bff1-75f2d2d2d33f",
"jobStatus": "esriJobSubmitted",
"status": "RUNNABLE",
"messages": []
}{
"jobId": "7aaae43b-b47e-43d1-bff1-75f2d2d2d33f",
"jobStatus": "esriJobSubmitted",
"status": "STARTING",
"messages": []
}{
"jobId": "7aaae43b-b47e-43d1-bff1-75f2d2d2d33f",
"jobStatus": "esriJobExecuting",
"status": "RUNNING",
"messages": []
}{
"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.
{
"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 item JSON object returned in the response for the upload request in the first step, as well as 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.
Note:
The jobs request may use either the GET or POST methods.
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. |
item (Required) | The item JSON object returned in the response from the upload request in the first step of the batchGeocode process. It represents the address file that was uploaded to the server. |
Example
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>
"item": {
"itemID": "dbbf2fed71784aec9815e91190da5239",
"itemName": "<user_filename>",
"description": "",
"date": 0,
"committed": true,
"serviceName": "batchGeocode",
"contentType": "application/binary"
}
token: <ACCESS TOKEN>
{
"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.
Note:
Downloading the file requires the GET method to be used. The token value must be included in the request header.
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. |
Example
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 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.
{
"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.
{
"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.
{
"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.
{
"status": "FAILED",
"logs": "Can't read csv header"
}