The /batch
job request geocodes a file of addresses in CSV (comma-separated values) or zipped CSV format.
To learn more about job requests, go to Service request types.
The capabilities of batch
are the same as the geocodeAddresses operation. These are the primary differences—
- With
batch
, the input addresses are passed to the service in a file; withGeocode geocode
, the addresses are passed to the service as a collection of JSON objects.Addresses - The
batch
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.Geocode
The batch
workflow is recommended for larger geocoding scenarios, where 100,000 or more addresses need to be geocoded.
South Korea address geocoding is not supported by batch
. The geocodeAddresses operation must be used for that.
Parameters
Name | Required | Type | Default | Description |
---|---|---|---|---|
string | An access token with the required privileges. | |||
string | The item id, passed as a string in a JSON object. | |||
string | Maps the fields in an address table to the input fields expected by the service. | |||
string | A place or address type that can be used to filter results. | |||
string | Sets the country to be geocoded. | |||
number |
| The spatial reference of the | ||
boolean |
| Returns a match when the input house number is outside the street's house number range. | ||
string |
| Specifies whether output geometry of | ||
string | envelope | The set of bounding box coordinates that limits the search area. | |||
string | The language in which results are returned. | |||
string | Returns the specified street or city name in output fields. | |||
string | * | The list of fields to be returned within the |
Required parameters
token
An access token with the required privileges.
- ArcGIS Location Platform: premium:user:geocode:temporary or premium:user:geocode:stored
- ArcGIS Online: premium:user:geocode or premium:user:geocode:stored
token=<ACCESS_TOKEN>
To use HTTP headers instead of the token
parameter, set the following:
GET <SERVICE_REQUEST> HTTP/1.1
Host: <SERVICE_DOMAIN>
X-Esri-Authorization: Bearer <ACCESS_TOKEN>
Learn more about access tokens and privileges in the Security and authentication developer guide.
item
The id
value returned in the response from the add
request in the first step of the batch
process. It represents the address file that was uploaded to the portal. It must be passed as a JSON object.
item = {'itemID': 'f507a5ddf4f9485c8f8ac6dc6ad9f25f'}
You can use the add
operation to upload the file of addresses to the portal. The result of the add
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. You may use a third-party application such as Microsoft Excel or Notepad++ to add a UTF-8 BOM to your CSV file.
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 usingadd
.Item
fieldMapping
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
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 field
parameter value should look like this:
SingleLine example
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
(house number + street name)_address municipality
(city name)state
(state name)zip
(postal code)_code
In this case, the field
parameter value should look like this:
Multiline example
fieldMapping=Address:street_address,City:municipality,Region:state,Postal:zip_code
The field
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
, it must be passed this way in the field
parameter: field
. 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 field
- an error will be returned by the service.
Optional parameters
category
A place or address type that can be used to filter geocode
results. The parameter supports input of single-category values or multiple comma-separated values. See Category filtering for details about the category
parameter.
Example of category filtering with a single category
category=Address
Example of category filtering with multiple categories
category=Address,Postal
sourceCountry
A value representing the country. When a value is passed for this parameter, all of the addresses in the input table are sent to the specified country to be geocoded. For example, if source
is passed with a batch request, it is assumed that all of the addresses in the table are in the United States, so only matching addresses in the U.S. are returned. Using this parameter can increase batch geocoding performance when all addresses are within a single country.
Acceptable values include the three-character country code. You can specify multiple country codes to limit results to more than one country.
A list of supported countries and codes is available in Data coverage.
Example: Single country
sourceCountry=USA
Example: Multiple countries
sourceCountry=FRA,DEU,ESP
outSR
The spatial reference of the x,y coordinates returned by a geocode request. This is useful for applications using a map with a spatial reference different than that of the geocode service.
The spatial reference can be specified as either a well-known ID (WKID) or as a JSON spatial reference object. If out
is not specified, the spatial reference of the output locations is the same as that of the service. The ArcGIS Geocoding service spatial reference is WGS84 (WKID = 4326).
For a list of valid WKID values, see Projected coordinate systems and Geographic coordinate systems.
Example (102100 is the WKID for the Web Mercator projection)
outSR=102100
matchOutOfRange
A Boolean that specifies whether StreetAddress matches should be returned even when the input house number is outside of the house number range defined for the input street. Out-of-range matches have =
. The geometry of such matches is a point corresponding to the end of the street segment where the range value is closest to the input house number. If match
is not specified in a request, its value is set to true
by default.
With the match
parameter, better spatial accuracy is provided for inexact street address searches. Most street segments are assigned house number ranges. For example, Main Street may include house numbers from 2–100 on one side of the street and 1–99 on the other. A user may search for a house number that is not within this range, such as 109 Main Street. If match
is passed in this request, the geocode service will return a StreetName-level match to Main Street, with geometry corresponding to the centroid of a street segment that most closely matches the input values. StreetName matches can be ambiguous because there may be multiple street segments with the same name that equally match the input. However, if match
, in this case, a more precise geometry is returned to the specific side of the segment of Main Street with house number range 1–99.
matchOutOfRange=false
locationType
The location
parameter specifies whether the output geometry of PointAddress matches should be the rooftop point or street entrance location. Valid values are rooftop
and street
. The default value is rooftop
.
Geocode results include one geometry object (the location
object) which defines the location of the address, as well as two sets of x,y coordinate values within the attributes
object: X /Y , and DisplayX /DisplayY . In most cases, for geocode results with =
or Subaddress
, the X
/Y
attribute values describe the coordinates of the address along the street, while the Display
/Display
values describe the rooftop, or building centroid, coordinates. By default, the geometry returned for geocode results represents the rooftop location of the address (if the rooftop location is available in the source data). This is useful for most spatial analysis and map display purposes. However, for routing scenarios, it may be desirable to use the street location because the rooftop location of some addresses may be offset from a street by a large distance. For these cases, the location
parameter can be used to specify that the street entrance geometry should be returned.
It is important to note that location
is limited by the address data sources used by the ArcGIS Geocoding service. Not all PointAddress and Subaddress features include rooftop and street location coordinates. For some addresses, only a rooftop location is available; for others, only a street location is provided by the data source. For cases such as this, the location
parameter may not function as expected. For example, if only rooftop location coordinates are available for an address, the rooftop geometry will be returned for the geocoded address even when location
is requested.
locationType=street
searchExtent
A set of bounding box coordinates that limit the search area to a specific region. This is especially useful for applications in which a user will search for places and addresses within the current map extent.
You can specify the spatial reference of the search
coordinates, which is necessary if the map spatial reference is different than that of the ArcGIS Geocoding service; otherwise, the spatial reference of the coordinates is assumed to be the same as that of the ArcGIS Geocoding service.
The input can either be a comma-separated list of coordinates defining the bounding box or a JSON envelope object. The spatial reference of the bounding box coordinates can be included if an envelope object is used.
Refer to the Geocode addresses within an extent section below for more details about using search
.
Example without a spatial reference
searchExtent=-104,35.6,-94.32,41
Example with a spatial reference
searchExtent=
{
"xmin": -13052769,
"ymin": 3951172,
"xmax": -13019630,
"ymax": 3978490,
"spatialReference": {
"wkid": 3395
}
}
langCode
The lang
parameter sets the language in which geocode results are returned. Addresses and places in many countries are available in more than one language; in these cases, the lang
parameter can be used to specify which language should be used for results returned by the geocode
operation. This is useful for ensuring that results are returned in the expected language. For example, a web application could be designed to get the browser language and pass it as the lang
parameter value in a geocode
request.
See the table of supported countries for valid language code values in each country. The Supported Language Codes column provides the valid input values for the lang
parameter. Full language names cannot be used with the lang
parameter. Only one language code value can be included for the lang
parameter in a geocode
request.
If the lang
parameter isn't included in a request, or if it is included but there are no matching features with the input language code, the resultant match is returned in the language code of the primary matched component from the input search string. Typically, this is either place-name or street name, depending on the search string.
Similarly, when there are multiple supported languages for a country, it doesn't mean that every address in the country is available in each of the languages. It may be the case that addresses are available in multiple languages for only one region of the country, or that each language is exclusive to a different region and there is no overlap. The following are some examples:
- Both English and French are listed as supported languages for Canada. However, there is no overlap between the languages for any addresses in most provinces. In the province of Quebec, only French addresses are available, while English is the only language used for addresses in Ontario.
- In Belgium, where three languages are supported (Dutch, French, and German), addresses are available in the city of Brussels in both Dutch and French. However, in the majority of the country, only a single language is used for addresses.
- In Greece, there is complete address coverage in both Greek and transliterated Greek languages (Greek words represented with Latin characters).
Due to variability of language coverage, the following logic is used to handle the different scenarios that may be encountered.
Scenario | Result | Example |
---|---|---|
Only one language is supported for an address, and no | Candidate is returned in the supported language. | Input (address in Geneva, Switzerland):
Output: |
Only one language is supported for an address, and an unsupported language is specified for the | Candidate is returned in the supported language. | Input (address in Geneva, Switzerland):
Output: |
Multiple languages are supported for an address, and no | Candidate is returned in the language of the primary matched component from the input string (street name or place-name). | Input (address in Brussels, Belgium):
Output: |
Multiple languages are supported for an address, and an unsupported language is specified for the | Candidate is returned in the language of the primary matched component from the input string (street name or place-name). | Input (address in Athens, Greece):
Output: |
Multiple languages are supported for an address, and a supported language is specified for the | Candidate is returned in the requested language. | Input (address in Athens, Greece):
Output: |
langCode=fr
preferredLabelValues
The preferred
parameter allows simple configuration of output fields returned in a response from the ArcGIS Geocoding service by specifying which address component values should be included in output fields. The parameter supports a single value or a comma-delimited collection of values as input. If the parameter is blank or excluded from a request, default address label formats will be used.
A particular address may have multiple city names associated with it. In the United States, for example, all addresses have a ZIP Code (postal code) assigned to them. Each ZIP Code has one or more associated locality names, which are known as postal cities. There is always one primary postal city value for each ZIP Code. ZIP Codes typically have no set boundaries, and the primary postal city name for the ZIP Code that is assigned to an address may be different than the name of the local city that the address is within.
For addresses in the United States, the ArcGIS Geocoding service includes the primary postal city in response output fields by default. As an example, postal code 45420 in Ohio has the primary postal city value Dayton. Addresses in the city of Kettering are assigned this postal code. It means that the default output fields for all geocoded addresses with postal code 45420, even those within the city of Kettering, will include Dayton as the city. To illustrate, if a user searches for 2109 E Dorothy Ln, O
, the default match label returned in the response is 2109 E Dorothy Ln, Dayton, Ohio, 45420, even though the address is within the Kettering city limits.
Some organizations may prefer to include the local city name in the response instead of the postal city. The preferred
can be used for this purpose. For the previous example, if preferred
is included in the request, the output match label in the response will be 2109 E Dorothy Ln, Kettering, Ohio, 45420.
Similarly, streets may be known by multiple names. This is especially true with highways. For example, Pearblossom Hwy in California, which is the primary name, is also known as CA-138. The ArcGIS Geocoding service allows matching to addresses using either name as input, and by default will return the name that was matched to in the response.
Some organizations may prefer that the primary street name be returned in the response even if a user searches for an alternate street name, and they can use the preferred
parameter to accomplish this. In other words, if a user searches for C
, and preferred
is included in the request, the match label returned in the response is Pearblossom Hwy, Pearblossom, California, 93553.
See the following table for supported parameter values.
Parameter value | Description |
---|---|
postalCity | Include the primary postal city value in geocoding response output fields, even if it is different than the city name in the geocoding request. This is the primary name assigned to the postal code of the address. |
localCity | Include the primary local city name in geocoding response output fields, even if it is different than the city name in the geocoding request. This is the name of the city that the address is within, and may be different than the postal city. |
matchedCity | If the input city name in a geocoding request matches any of the local city or postal city names associated with an address, include the matched value in geocoding response output fields. If a city name is not included in the input, or is included but doesn't match to anything, default address formats will be used. |
primaryStreet | Include the primary street name in geocoding response output fields, even if it is different than the street name in the geocoding request. |
matchedStreet | If the input street name in a geocoding request matches any of the supported street names assigned to an address, include the matched value in geocoding response output fields. |
Here are additional details about the preferred
parameter
- The
preferred
parameter takes a comma-delimited collection of values as input.Label Values - The parameter values correspond to two groups—a City group and a Street group, indicated by the suffix of the value name. The
postal
,City local
, andCity matched
values are part of the City group. TheCity primary
andStreet matched
values are part of the Street group.Street - A geocode request can include one City value and one Street value—for instance:
preferred
.Label Values=primary Street,postal City - A request can only include one value per group. In other words, a request with
preferred
is invalid.Label Values=matched City,postal City
Example: Single label value
preferredLabelValues=matchedCity
Example: Multiple label values
preferredLabelValues=matchedCity,primaryStreet
outFields
The list of fields to be returned within the attributes
object of the geocode
response. Descriptions for each of these fields are available in the Service output topic.
Unless otherwise specified, all output fields are returned in a geocode
response (refer to this example to see the full set of output fields). The out
parameter can be used to limit the result set by allowing specific fields to be returned, which is useful if not all fields are required for a user workflow.
If out
is passed in a geocode
request, only the minimum set of components is included in the response. This includes the Result
field, which is always part of the geocode
response no matter which values are defined for the out
parameter. The minimum set of objects includes the following:
spatial
Reference locations
(full address and x,y coordinates of the match location)score
attributes
(including theResult
output field)ID
Examples that return all output fields
outFields=*
outFields=
Example that returns a partial set of output fields
outFields=AddNum,StAddr,City
Example that returns the minimum set of output fields
outFields=none
Response status
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK | A successful response for a | Inline |
403 | Forbidden | The | |
409 | Bad request | An item '{item name}' already exists. This error is returned when an item already exists in the portal with the same name as the filename passed in the | |
5 | Unknown | An error occured on the server. |
Response details
{
"jobId": "<jobID>",
"jobStatus": "esriJobSubmitted",
"status": "SUBMITTED",
"messages": []
}
{
"jobId": "<jobID>",
"jobStatus": "esriJobSubmitted",
"status": "RUNNABLE",
"messages": []
}
{
"jobId": "<jobID>",
"jobStatus": "esriJobSubmitted",
"status": "STARTING",
"messages": []
}
Examples
Batch geocode a list of addresses
For the complete workflow, go to Mapping and location services > Batch geocoding.
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>
Check the job status
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>
Get the result file URL
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>