/batchGeocode

POSTPOSTGET
Use dark colors for code blocksCopy
1
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.

Parameters

NameRequiredTypeDefaultDescription
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

4326

The spatial reference of the x and y coordinates returned in a response.

boolean

true

Returns a match when the input house number is outside the street's house number range.

string

rooftop

Specifies whether output geometry of PointAddress and Subaddress matches should be the rooftop point or street entrance.

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 attributes object of a response.

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
Use dark colors for code blocksCopy
1
token=<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 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
1
item = {'itemID': 'f507a5ddf4f9485c8f8ac6dc6ad9f25f'}

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>:<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

Optional parameters

category

A place or address type that can be used to filter geocodeAddresses 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

Use dark colors for code blocksCopy
1
category=Address

Example of category filtering with multiple categories

Use dark colors for code blocksCopy
1
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 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
1
sourceCountry=USA

Example: Multiple countries

Use dark colors for code blocksCopy
1
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 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
1
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 =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
1
matchOutOfRange=false

locationType

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
1
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 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
1
searchExtent=-104,35.6,-94.32,41

Example with a spatial reference

Use dark colors for code blocksCopy
1
2
3
4
5
6
7
8
9
10
searchExtent=
{
    "xmin": -13052769,
    "ymin": 3951172,
    "xmax": -13019630,
    "ymax": 3978490,
    "spatialReference": {
        "wkid": 3395
    }
}

langCode

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.

ScenarioResultExample

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

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

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

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

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, Αθήνα

Use dark colors for code blocksCopy
1
langCode=fr

preferredLabelValues

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 valueDescription

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
1
preferredLabelValues=matchedCity

Example: Multiple label values

Use dark colors for code blocksCopy
1
preferredLabelValues=matchedCity,primaryStreet

outFields

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
1
2
outFields=*
outFields=

Example that returns a partial set of output fields

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

Example that returns the minimum set of output fields

Use dark colors for code blocksCopy
1
outFields=none

Response status

StatusMeaningDescriptionSchema
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
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78


{
  "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
1
2
3
4
5
6
7
8
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

Use dark colors for code blocksCopy
1
2
3
4
5
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

Use dark colors for code blocksCopy
1
2
3
4
5
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>

Download the geocoded file

Use dark colors for code blocksCopy
1
2
3
4
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>

Your browser is no longer supported. Please upgrade your browser for the best experience. See our browser deprecation post for more details.