/batchGeocode

POST

GET

Use dark colors for code blocksCopy
POST https://geocode-beta.arcgis.com/arcgis/rest/services/World/GeocodeServer/batchGeocode/beta/submitJob

The /batchGeocode 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 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.

South Korea address geocoding is not supported by batchGeocode . The geocodeAddresses operation must be used for that.

Parameters

Name	Type	Default	Description
`token`	`string`		An access token with the required privileges.
`item`	`string`		The item id, passed as a string in a JSON object.
`fieldMapping`	`string`		Maps the fields in an address table to the input fields expected by the service.
`category`	`string`		A place or address type that can be used to filter results.
`sourceCountry`	`string`		Sets the country to be geocoded.
`outSr`	`number`	`4326`	The spatial reference of the `x` and `y` coordinates returned in a response.
`matchOutOfRange`	`boolean`	`true`	Returns a match when the input house number is outside the street's house number range.
`locationType`	`string`	`rooftop`	Specifies whether output geometry of `PointAddress` and `Subaddress` matches should be the rooftop point or street entrance.
`searchExtent`	`string \| envelope`		The set of bounding box coordinates that limits the search area.
`langCode`	`string`		The language in which results are returned.
`preferredLabelValues`	`string`		Returns the specified street or city name in output fields.
`outFields`	`string \| *`		The list of fields to be returned within the `attributes` object of a response.

Required parameters

token

stringrequired

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

Use dark colors for code blocksCopy
token=<ACCESS_TOKEN>

To use HTTP headers instead of the token parameter, set the following:

X-Esri-Authorization

Authorization

Use dark colors for code blocksCopy

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

{object}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.

Use dark colors for code blocksCopy
item = {'itemID': 'f507a5ddf4f9485c8f8ac6dc6ad9f25f'}

You can 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. 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 using addItem.

fieldMapping

stringrequired

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

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.

Optional parameters

sourceCountry

stringoptional

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 sourceCountry=USA 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

Use dark colors for code blocksCopy
sourceCountry=USA

Example: Multiple countries

Use dark colors for code blocksCopy
sourceCountry=FRA,DEU,ESP

outSR

numberoptional

Default value: 4326

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 outSR 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)

Use dark colors for code blocksCopy
outSR=102100

matchOutOfRange

booleanoptional

Default value: true

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 =StreetAddressExt . 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 matchOutOfRange is not specified in a request, its value is set to true by default.

With the matchOutOfRange 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 matchOutOfRange=false 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 matchOutOfRange=true , 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.

Use dark colors for code blocksCopy
matchOutOfRange=false

locationType

stringoptional

Values: rooftop, street

The locationType 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 =PointAddress or Subaddress , the X /Y attribute values describe the coordinates of the address along the street, while the DisplayX /DisplayY 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 locationType parameter can be used to specify that the street entrance geometry should be returned.

It is important to note that locationType 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 locationType 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 locationType=street is requested.

Use dark colors for code blocksCopy
locationType=street

searchExtent

stringenvelopeoptional

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 searchExtent 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 searchExtent .

Example without a spatial reference

Use dark colors for code blocksCopy
searchExtent=-104,35.6,-94.32,41

Example with a spatial reference

Use dark colors for code blocksCopy
searchExtent=
{
    "xmin": -13052769,
    "ymin": 3951172,
    "xmax": -13019630,
    "ymax": 3978490,
    "spatialReference": {
        "wkid": 3395
    }
}

langCode

stringoptional

The langCode 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 langCode parameter can be used to specify which language should be used for results returned by the geocodeAddresses 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 langCode parameter value in a geocodeAddresses 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 langCode parameter. Full language names cannot be used with the langCode parameter. Only one language code value can be included for the langCode parameter in a geocodeAddresses request.

If the langCode 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 `langCode` value is specified in the `geocodeAddresses` request.	Candidate is returned in the supported language.	Input (address in Geneva, Switzerland): `Avenue Appia 20 1202 Geneva` `langCode=` Output: `Avenue Appia 20, 1202, Pregny-Chambésy, Genève` Note The candidate is returned in French because it is the only language supported for addresses in Geneva, Switzerland.
Only one language is supported for an address, and an unsupported language is specified for the `langCode` parameter in the `geocodeAddresses` request.	Candidate is returned in the supported language.	Input (address in Geneva, Switzerland): `Avenue Appia 20 1202 Geneva` `langCode=zh` (Chinese) Output: `Avenue Appia 20, 1202, Pregny-Chambésy, Genève` Note The candidate is returned in French because language `zh` (Chinese) is not supported for addresses in Geneva. French is the only language supported for addresses in Geneva.
Multiple languages are supported for an address, and no `langCode` value is specified in the `geocodeAddresses` request.	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): `Wetstraat 175 Brussel` `langCode=` Output: `Wetstraat 175, 1040, Brussel` Note The candidate is returned in Dutch based on the matched street name Wetstraat, which is Dutch. Both Dutch and French languages are supported for addresses in Brussels, Belgium.
Multiple languages are supported for an address, and an unsupported language is specified for the `langCode` parameter in the `geocodeAddresses` request.	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): `Dionysiou Areopagitou 15, 11742, Athens` `langCode=ru` (Russian) Output: `Dionysiou Areopagitou 15, 117 42, Athens` Note The candidate is returned in transliterated Greek based on the matched street name Dionysiou Areopagitou, because language `ru` (Russian) is not supported for addresses in Greece. Only Greek and transliterated Greek are supported for addresses in Greece.
Multiple languages are supported for an address, and a supported language is specified for the `langCode` parameter in the `geocodeAddresses` request.	Candidate is returned in the requested language.	Input (address in Athens, Greece): `Dionysiou Areopagitou 15, 11742, Athens` `langCode=el` (Greek) Output: `Διονυσίου Αρεοπαγίτου 15, 117 42, Αθήνα` Note The candidate is returned in Greek because language `el` (Greek) is supported for addresses in Greece.

Use dark colors for code blocksCopy
langCode=fr

preferredLabelValues

stringoptional

The preferredLabelValues 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, OH, 45420 , 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 preferredLabelValues can be used for this purpose. For the previous example, if preferredLabelValues=localCity 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 preferredLabelValues parameter to accomplish this. In other words, if a user searches for CA-138, Pearblossom, CA , and preferredLabelValues=primaryStreet 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 preferredLabelValues parameter

The preferredLabelValues parameter takes a comma-delimited collection of values as input.
The parameter values correspond to two groups—a City group and a Street group, indicated by the suffix of the value name. The postalCity , localCity , and matchedCity values are part of the City group. The primaryStreet and matchedStreet values are part of the Street group.
A geocode request can include one City value and one Street value—for instance: preferredLabelValues=primaryStreet,postalCity .
A request can only include one value per group. In other words, a request with preferredLabelValues=matchedCity,postalCity is invalid.

Example: Single label value

Use dark colors for code blocksCopy
preferredLabelValues=matchedCity

Example: Multiple label values

Use dark colors for code blocksCopy
preferredLabelValues=matchedCity,primaryStreet

outFields

string*optional

The list of fields to be returned within the attributes object of the geocodeAddresses response. Descriptions for each of these fields are available in the Service output topic.

Unless otherwise specified, all output fields are returned in a geocodeAddresses response (refer to this example to see the full set of output fields). The outFields 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 outFields=none is passed in a geocodeAddresses request, only the minimum set of components is included in the response. This includes the ResultID field, which is always part of the geocodeAddresses response no matter which values are defined for the outFields parameter. The minimum set of objects includes the following:

spatialReference
locations (full address and x,y coordinates of the match location)
score
attributes (including the ResultID output field)

Examples that return all output fields

Use dark colors for code blocksCopy
outFields=*
outFields=

Example that returns a partial set of output fields

Use dark colors for code blocksCopy
outFields=AddNum,StAddr,City

Example that returns the minimum set of output fields

Use dark colors for code blocksCopy
outFields=none

Response status

Status	Meaning	Description	Schema
`200`	OK	A successful response for a `/reverseGeocode` request.	Inline
`403`	Forbidden	The `token` is valid but access is denied. This error is returned when a user with insufficient privileges attempts to geocode a file using the `batchGeocode` operation.	Error
`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 `addItem` request.	Error
`5XX`	Unknown	An error occured on the server.	Error

Response details

Use dark colors for code blocksCopy


{
  "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.

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": "7aaae43b-b47e-43d1-bff1-75f2d2d2d33f",
  "jobStatus": "esriJobSubmitted",
  "messages": []
}

Check the job status

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>

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

Get the result file URL

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 geocoded file

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>

/batchGeocode

Parameters

Required parameters

token

item

fieldMapping

Optional parameters

category

sourceCountry

outSR

matchOutOfRange

locationType

searchExtent

langCode

preferredLabelValues

outFields

Response status

Response details

Examples

Batch geocode a list of addresses

Check the job status

Get the result file URL

Download the geocoded file