geocodeAddresses

Geocode an entire list of addresses in one request using the geocodeAddresses operation. Geocoding many addresses at once is also known as batch or bulk geocoding.

geocodeAddresses

This operation can be used to find the following types of locations:

  • Street addresses:
    • 27488 Stanford Ave, Bowden, North Dakota
    • 380 New York St, Redlands, CA 92373
  • Administrative place-names, such as city, county, state, province, or country names:
    • Seattle, Washington
    • State of Mahārāshtra
    • Liechtenstein
  • Postal codes
    • 92591
    • TW9 1DN
Note:

Points of interest (POI) can only be batch geocoded by using the category parameter to specify the place types to geocode.

The addresses in your table can be stored in a single field or in multiple fields—one for each address component. Batch geocoding performance is better when the address parts are stored in separate fields.

Tip:

You can also batch geocode address tables using the ArcGIS Online Generate and Publish operations. These are higher-level APIs that simplify the batch geocoding process.

Request URL

http://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer/geocodeAddresses?<PARAMETERS>

Maximum addresses

There is a limit to the maximum number of addresses that can be geocoded in a single batch request with the service. The MaxBatchSize property defines this limit. For instance, if MaxBatchSize=2000, and a record set sent to the service contains 3,000 addresses, only the first 2,000 will be geocoded. The SuggestedBatchSize property is also useful as it specifies the optimal number of addresses to include in a single batch request.

Both of these properties can be determined by querying the service description at http://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer?f=pjson.

The client application must account for the limit by dividing the input address table into record sets of MaxBatchSize or fewer addresses and send each record set to the service as a separate request. Note that Generate and Publish take care of this for you.

For batch geocode operations, the service returns a response when each address in the input record set has been geocoded. If an unhandled error such as a time-out occurs during the process, the server will not return the results for that request, even if most of the addresses in the input record set have already been geocoded. For this reason, the client application should implement logic to detect and handle such errors.

Batch geocode access

An ArcGIS Online organizational account is required to use the batch geocoding functionality provided by the World Geocoding Service. Successfully geocoded addresses that return a status of Matched or Tied cause ArcGIS Online service credits to be consumed for batch geocoding operations.

Each batch geocode request requires a token to be included with the request. Refer to Authenticate a request to the World Geocoding Service for information about how to access secured batch geocoding functionality.

Request parameters

The parameters for geocodeAddresses are listed in the subsections that follow, categorized by required and optional parameters.

Required parameters

addresses

A record set representing the addresses to be geocoded. Each record must include an OBJECTID attribute with a unique value as well as values for the address fields supported by the service.

For passing in the location name as a single line of text—single field batch geocoding—use the SingleLine input field.

For passing in the location name as multiple lines of text—multifield batch geocoding—use the address fields described in findAddressCandidates.

The service info page http://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer?f=pjson provides localized versions of the input field names in all locales supported by the service. See Localized input field names for more information.

Note:

When sending long JSON objects in a request, it is necessary to use the POST method instead of GET. This is due to URL length limitations. When GET is used, the entire request is encoded in the URL; long JSON objects can cause the limit to be exceeded and the URL to be truncated. A typical geocodeAddresses request will include hundreds of street addresses, which are formatted as part of the addresses parameter. Such large numbers of addresses can quickly cause the URL length limit to be reached. For this reason, it is recommended that applications use the POST method to send geocodeAddresses requests.

Example:
addresses=
{
    "records": [
        {
            "attributes": {
                "OBJECTID": 1,
                "Address": "380 New York St",
                "Neighborhood": "",
                "City": "Redlands",
                "Subregion": "",
                "Region": "CA"
            }
        },
        {
            "attributes": {
                "OBJECTID": 2,
                "Address": "1 World Way",
                "Neighborhood": "",
                "City": "Los Angeles",
                "Subregion": "",
                "Region": "CA"
            }
        }
    ]
}

token

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

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

Example (replace <YOUR TOKEN> with a valid token):
token=<YOUR TOKEN>

f

The service supports responses in JSON or PJSON format. You can specify the response format using the f parameter. This is a required parameter.

Example:
f=json

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 complete 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 locator 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 all the addresses are sent to the USA country locator. Using this parameter can increase batch geocoding performance when all addresses are within a single country.

Acceptable values include the full country name, the ISO 3166-1 2-digit country code, or the ISO 3166-1 3-digit country code.

A list of supported countries and codes is available in Geocode coverage.

Example:
sourceCountry=USA

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

Batch geocoding output fields

When geocoding a table of addresses, the output fields are returned as part of the attributes in the response. See the example JSON response below, which shows all of the output fields that are returned for each record from a batch geocode process. The output fields are described Service output.

With batch geocoding, it is useful to define a unique ID for each record in your input table of addresses. You can pass the ID as the OBJECTID in the batch geocode request, and the ID will be returned as the ResultID in the response. The ResultID can then be used to link the output fields in the response records, including the X/Y location, to the attributes in the original table.

Batch geocoding examples

The following examples illustrate how to format JSON batch geocoding requests for multiline address input (first example) and single line input (second example) scenarios. In both cases, the response contains the exact same information.

Example: Batch geocode two addresses

Input multiline JSON record set:

http://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer/geocodeAddresses?addresses={"records":[{"attributes":{"OBJECTID":1,"Address":"380 New York St.","City":"Redlands","Region":"CA","Postal":"92373"}},{"attributes":{"OBJECTID":2,"Address":"1 World Way","City":"Los Angeles","Region":"CA","Postal":"90045"}}]}&sourceCountry=USA&token=<YOUR TOKEN>&f=pjson

For clarity, here is the addresses parameter in PJSON:

addresses=
{           "records": [
        {
            "attributes": {
                "OBJECTID": 1,
                "Address": "380 New York St.",
                "City": "Redlands",
                "Region": "CA",
                "Postal": "92373"
            }
        },
   {
            "attributes": {
                "OBJECTID": 2,
                "Address": "1 World Way",
                "City": "Los Angeles",
                "Region": "CA",
                "Postal": "90045"
            }
        }
    ]
}

For clarity, here is the input single field JSON record set:

http://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer/geocodeAddresses?addresses={"records":[{"attributes":{"OBJECTID":1,"SingleLine":"380 New York St., Redlands, CA, 92373"}},{"attributes":{"OBJECTID":2,"SingleLine":"1 World Way, Los Angeles, CA, 90045"}}]}&sourceCountry=USA&token=<YOUR TOKEN>&f=pjson

For clarity, here is the addresses parameter in PJSON:

addresses=
{           "records": [
        {
            "attributes": {
                "OBJECTID": 1,
                "SingleLine": "380 New York St., Redlands, CA, 92373"
            }
        },
   {
            "attributes": {
                "OBJECTID": 2,
                "SingleLine": "1 World Way, Los Angeles, CA, 90045"
            }
        }
    ]
}

JSON response

{
 "spatialReference": {
  "wkid": 4326,
  "latestWkid": 4326
 },
 "locations": [
  {
   "address": "380 New York St, Redlands, California, 92373",
   "location": {
    "x": -117.19566588299972,
    "y": 34.056490201000486
   },
   "score": 100,
   "attributes": {
    "ResultID": 1,
    "Loc_name": "USA.PointAddress",
    "Status": "M",
    "Score": 100,
    "Match_addr": "380 New York St, Redlands, California, 92373",
    "Addr_type": "PointAddress",
    "Type": "",
    "PlaceName": "",
    "Place_addr": "",
    "Phone": "",
    "URL": "",
    "Rank": "",
    "AddBldg": "",
    "AddNum": "380",
    "AddNumFrom": "",
    "AddNumTo": "",
    "Side": "R",
    "StPreDir": "",
    "StPreType": "",
    "StName": "New York",
    "StType": "St",
    "StDir": "",
    "StAddr": "380 New York St",
    "Nbrhd": "",
    "City": "Redlands",
    "Subregion": "San Bernardino",
    "Region": "California",
    "Postal": "92373",
    "PostalExt": "",
    "Country": "USA",
    "LangCode": "ENG",
    "Distance": 0,
    "X": -117.195667,
    "Y": 34.056489999999997,
    "DisplayX": -117.195311,
    "DisplayY": 34.056109999999997,
    "Xmin": -117.19666700000001,
    "Xmax": -117.194667,
    "Ymin": 34.055489999999999,
    "Ymax": 34.057490000000001
   }
  },
  {
   "address": "1 World Way, Los Angeles, California, 90045",
   "location": {
    "x": -118.39755050499969,
    "y": 33.944139708000478
   },
   "score": 100,
   "attributes": {
    "ResultID": 2,
    "Loc_name": "USA.StreetAddress",
    "Status": "M",
    "Score": 100,
    "Match_addr": "1 World Way, Los Angeles, California, 90045",
    "Addr_type": "StreetAddress",
    "Type": "",
    "PlaceName": "",
    "Place_addr": "",
    "Phone": "",
    "URL": "",
    "Rank": "",
    "AddBldg": "",
    "AddNum": "1",
    "AddNumFrom": "1",
    "AddNumTo": "57",
    "Side": "R",
    "StPreDir": "",
    "StPreType": "",
    "StName": "World",
    "StType": "Way",
    "StDir": "",
    "StAddr": "1 World Way",
    "Nbrhd": "",
    "City": "Los Angeles",
    "Subregion": "Los Angeles",
    "Region": "California",
    "Postal": "90045",
    "PostalExt": "",
    "Country": "USA",
    "LangCode": "ENG",
    "Distance": 0,
    "X": -118.397552,
    "Y": 33.944139999999997,
    "DisplayX": -118.397552,
    "DisplayY": 33.944139999999997,
    "Xmin": -118.398552,
    "Xmax": -118.396552,
    "Ymin": 33.94314,
    "Ymax": 33.945140000000002
   }
  }
 ]
}

Category filtering

The geocodeAddresses operation supports batch geocode filtering by category values, which represent address and place types. By including the category parameter in a geocodeAddresses request you can avoid false positive matches to unexpected place and address types due to ambiguous input.

For example, a user has a table of three-letter airport codes that they want to geocode. There may be city or business names that are the same as an airport code, causing false positive matches to other places. However the user can ensure that only airport matches are returned by specifying category=airport in the request.

Example: Batch geocode airport codes with category

For clarity, here is the input single field JSON record set:

http://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer/geocodeAddresses?addresses={"records":[{"attributes":{"OBJECTID":1,"SingleLine":"LAX",}},{"attributes":{"OBJECTID":2,"SingleLine":"SFO",}}]}&category=airport&token=<YOUR TOKEN>&f=pjson

JSON response

{
 "spatialReference": {
  "wkid": 4326,
  "latestWkid": 4326
 },
 "locations": [
  {
   "address": "Los Angeles International Airport",
   "location": {
    "x": -118.4089657019997,
    "y": 33.942509816000438
   },
   "score": 100,
   "attributes": {
    "ResultID": 1,
    "Loc_name": "Gaz.WorldGazetteer.POI1",
    "Status": "T",
    "Score": 100,
    "Match_addr": "Los Angeles International Airport",
    "Addr_type": "POI",
    "Type": "Airport",
    "PlaceName": "LAX",
    "Place_addr": "Los Angeles, California, United States",
    "Phone": "",
    "URL": "",
    "Rank": "7",
    "AddBldg": "",
    "AddNum": "",
    "AddNumFrom": "",
    "AddNumTo": "",
    "Side": "",
    "StPreDir": "",
    "StPreType": "",
    "StName": "",
    "StType": "",
    "StDir": "",
    "StAddr": "",
    "Nbrhd": "",
    "City": "Los Angeles",
    "Subregion": "Los Angeles County",
    "Region": "California",
    "Postal": "",
    "PostalExt": "",
    "Country": "USA",
    "LangCode": "",
    "Distance": 0,
    "X": -118.408967,
    "Y": 33.942509999999999,
    "DisplayX": -118.408967,
    "DisplayY": 33.942509999999999,
    "Xmin": -118.433967,
    "Xmax": -118.383967,
    "Ymin": 33.91751,
    "Ymax": 33.967509999999997
   }
  },
  {
   "address": "San Francisco International Airport",
   "location": {
    "x": -122.37579569399969,
    "y": 37.618818588000465
   },
   "score": 100,
   "attributes": {
    "ResultID": 2,
    "Loc_name": "Gaz.WorldGazetteer.POI1",
    "Status": "T",
    "Score": 100,
    "Match_addr": "San Francisco International Airport",
    "Addr_type": "POI",
    "Type": "Airport",
    "PlaceName": "SFO",
    "Place_addr": "San Mateo County, California, United States",
    "Phone": "",
    "URL": "",
    "Rank": "7",
    "AddBldg": "",
    "AddNum": "",
    "AddNumFrom": "",
    "AddNumTo": "",
    "Side": "",
    "StPreDir": "",
    "StPreType": "",
    "StName": "",
    "StType": "",
    "StDir": "",
    "StAddr": "",
    "Nbrhd": "",
    "City": "",
    "Subregion": "San Mateo County",
    "Region": "California",
    "Postal": "",
    "PostalExt": "",
    "Country": "USA",
    "LangCode": "",
    "Distance": 0,
    "X": -122.37579700000001,
    "Y": 37.618819000000002,
    "DisplayX": -122.37579700000001,
    "DisplayY": 37.618819000000002,
    "Xmin": -122.400797,
    "Xmax": -122.350797,
    "Ymin": 37.593819000000003,
    "Ymax": 37.643819000000001
   }
  }
 ]
}

You can also use category filtering to avoid "low resolution" fallback matches. By default if the World Geocoding Service cannot find a match for an input address it will automatically search for a lower match level, such as a street name, city, or postal code. For batch geocoding a user may prefer that no match is returned in such cases so that they are not charged for the geocode. If a user passes category=Point Address,Street Address in a geocodeAddresses request, no fallback will occur if address matches cannot be found; the user will only be charged for the actual address matches.

Example: Batch geocode with fallback allowed (no category)

For clarity, here is the input single field JSON record set:

http://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer/geocodeAddresses?addresses={"records":[{"attributes":{"OBJECTID":1,"SingleLine":"380 New York St Redlands CA 92373",}},{"attributes":{"OBJECTID":2,"SingleLine":"27488 Stanford Dr Escondido CA",}}]}&token=<YOUR TOKEN>&category=&f=pjson

JSON response

{
 "spatialReference": {
  "wkid": 4326,
  "latestWkid": 4326
 },
 "locations": [
  {
   "address": "380 New York St, Redlands, California, 92373",
   "location": {
    "x": -117.19566588299972,
    "y": 34.056490201000486
   },
   "score": 100,
   "attributes": {
    "ResultID": 1,
    "Loc_name": "USA.PointAddress",
    "Status": "M",
    "Score": 100,
    "Match_addr": "380 New York St, Redlands, California, 92373",
    "Addr_type": "PointAddress",
    "Type": "",
    "PlaceName": "",
    "Place_addr": "",
    "Phone": "",
    "URL": "",
    "Rank": "",
    "AddBldg": "",
    "AddNum": "380",
    "AddNumFrom": "",
    "AddNumTo": "",
    "Side": "R",
    "StPreDir": "",
    "StPreType": "",
    "StName": "New York",
    "StType": "St",
    "StDir": "",
    "StAddr": "380 New York St",
    "Nbrhd": "",
    "City": "Redlands",
    "Subregion": "San Bernardino",
    "Region": "California",
    "Postal": "92373",
    "PostalExt": "",
    "Country": "USA",
    "LangCode": "ENG",
    "Distance": 0,
    "X": -117.195667,
    "Y": 34.056489999999997,
    "DisplayX": -117.195311,
    "DisplayY": 34.056109999999997,
    "Xmin": -117.19666700000001,
    "Xmax": -117.194667,
    "Ymin": 34.055489999999999,
    "Ymax": 34.057490000000001
   }
  },
  {
   "address": "Escondido, California",
   "location": {
    "x": -117.08216632399967,
    "y": 33.123161652000476
   },
   "score": 100,
   "attributes": {
    "ResultID": 2,
    "Loc_name": "USA.AdminPlaces",
    "Status": "M",
    "Score": 100,
    "Match_addr": "Escondido, California",
    "Addr_type": "Locality",
    "Type": "",
    "PlaceName": "",
    "Place_addr": "",
    "Phone": "",
    "URL": "",
    "Rank": "1",
    "AddBldg": "",
    "AddNum": "",
    "AddNumFrom": "",
    "AddNumTo": "",
    "Side": "",
    "StPreDir": "",
    "StPreType": "",
    "StName": "",
    "StType": "",
    "StDir": "",
    "StAddr": "",
    "Nbrhd": "",
    "City": "Escondido",
    "Subregion": "San Diego",
    "Region": "California",
    "Postal": "",
    "PostalExt": "",
    "Country": "USA",
    "LangCode": "ENG",
    "Distance": 0,
    "X": -117.082167,
    "Y": 33.123162000000001,
    "DisplayX": -117.082167,
    "DisplayY": 33.123162000000001,
    "Xmin": -117.132167,
    "Xmax": -117.032167,
    "Ymin": 33.073162000000004,
    "Ymax": 33.173161999999998
   }
  }
 ]
}

Example: Batch geocode with no fallback allowed (category=Point Address)

For clarity, here is the input single field JSON record set:

http://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer/geocodeAddresses?addresses={"records":[{"attributes":{"OBJECTID":1,"SingleLine":"380 New York St Redlands CA 92373",}},{"attributes":{"OBJECTID":2,"SingleLine":"27488 Stanford Dr Escondido CA",}}]}&token=<YOUR TOKEN>&category=Point Address&f=pjson

JSON response

{
 "spatialReference": {
  "wkid": 4326,
  "latestWkid": 4326
 },
 "locations": [
  {
   "address": "380 New York St, Redlands, California, 92373",
   "location": {
    "x": -117.19566588299972,
    "y": 34.056490201000486
   },
   "score": 100,
   "attributes": {
    "ResultID": 1,
    "Loc_name": "USA.PointAddress",
    "Status": "M",
    "Score": 100,
    "Match_addr": "380 New York St, Redlands, California, 92373",
    "Addr_type": "PointAddress",
    "Type": "",
    "PlaceName": "",
    "Place_addr": "",
    "Phone": "",
    "URL": "",
    "Rank": "",
    "AddBldg": "",
    "AddNum": "380",
    "AddNumFrom": "",
    "AddNumTo": "",
    "Side": "R",
    "StPreDir": "",
    "StPreType": "",
    "StName": "New York",
    "StType": "St",
    "StDir": "",
    "StAddr": "380 New York St",
    "Nbrhd": "",
    "City": "Redlands",
    "Subregion": "San Bernardino",
    "Region": "California",
    "Postal": "92373",
    "PostalExt": "",
    "Country": "USA",
    "LangCode": "ENG",
    "Distance": 0,
    "X": -117.195667,
    "Y": 34.056489999999997,
    "DisplayX": -117.195311,
    "DisplayY": 34.056109999999997,
    "Xmin": -117.19666700000001,
    "Xmax": -117.194667,
    "Ymin": 34.055489999999999,
    "Ymax": 34.057490000000001
   }
  },
  {
   "address": "",
   "score": 0,
   "attributes": {
    "ResultID": 2,
    "Loc_name": "",
    "Status": "U",
    "Score": 0,
    "Match_addr": "",
    "Addr_type": "",
    "Type": "",
    "PlaceName": "",
    "Place_addr": "",
    "Phone": "",
    "URL": "",
    "Rank": "",
    "AddBldg": "",
    "AddNum": "",
    "AddNumFrom": "",
    "AddNumTo": "",
    "Side": "",
    "StPreDir": "",
    "StPreType": "",
    "StName": "",
    "StType": "",
    "StDir": "",
    "StAddr": "",
    "Nbrhd": "",
    "City": "",
    "Subregion": "",
    "Region": "",
    "Postal": "",
    "PostalExt": "",
    "Country": "",
    "LangCode": "",
    "Distance": 0,
    "X": 0,
    "Y": 0,
    "DisplayX": 0,
    "DisplayY": 0,
    "Xmin": 0,
    "Xmax": 0,
    "Ymin": 0,
    "Ymax": 0
   }
  }
 ]
}

See the topic Category filtering for complete details.