Geocode Addresses

Description

The geocodeAddresses operation is performed on a Geocode Service resource. The result of this operation is a resource representing the list of geocoded addresses. This resource provides information about the addresses, including the address, location, score, and other geocode service-specific attributes.

NoteNote:

When sending a long JSON object 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, as a long JSON object can cause the limit to be exceeded and the URL to be truncated.

New at 10.7

New at 10.6

New at 10.3

Request parameters

Parameter

Details

addresses

(Required)

A record set representing the addresses to be geocoded. Each record must include an objectID attribute with a unique value, as well as various address fields accepted by the corresponding geocode service. For passing in the location name as a single-field batch geocoding, use the singleLine input field. For passing in the location name as multifield batch geocoding, use the address fields described in findAddressCandidates. For example usage, see Address parameter syntax and examples.

category

(Optional)

A place or address that can be used to filter the operation's results. The parameter supports input of single-category values or multiple, comma-separated (without spaces) values. The category can either be passed in a request with the singleLine or address parameters, or on its own. See Category filtering for complete parameter details.

Example

category=Address,Postal
sourceCountry

(Optional)

Limits the returned candidates to the specified country or countries for either single-field or multifield requests. Acceptable values include the three-character country code. A list of supported countries and codes is available in Geocode coverage. Multiple country codes can be specified (comma-separated with no spaces) to return results for more than one country.

Example

sourceCountry=FRA,DEU,ESP
outSR

(Optional)

The spatial reference of the x,y coordinates returned by a geocode request. The spatial reference can be specified as either a well-known ID (WKID) or a JSON spatial reference object. If outSR is not specified, the spatial reference of the output location is the same as that of the service. For a list of valid WKID values, see Projected coordinate systems and Geographic coordinate systems.

Example

outSR=102100
matchOutOfRange

(Optional)

Provides better spatial accuracy for inexact street addresses by specifying whether matches should be returned when the input number is outside of the house range defined for the input street. Out of range matches will be defined as Addr_type=StreetAddressExt. Input house numbers that exceed the range on a street segment by more than 100 will not result in streetAddressExt matches. For streets with smaller house numbers, the maxOutOfRange tolerance is less than 100. The default value of this parameter is true.

Values: true | false

locationType

(Optional)

Specifies whether the rooftop point or street entrance should be the output geometry of PointAddress matches. By default, street is used, which can be useful for routing scenarios, as the rooftop location of some addresses may be offset from a street by a large distance. However, for map display purposes, it may be desirable to use rooftop instead, especially when large buildings or landmarks are geocoded. The location parameter only affects the location object in the JSON response, and does not change the x,y or DisplayX/DisplayY attribute values.

Values: street | rooftop

searchExtent

(Optional)

A set of bounding box coordinates that limit the search area to a specific region. You can specify the spatial reference of the searchExtent coordinates, which is necessary if the map spatial reference is different than that of the geocoding service; otherwise, the spatial reference of the map coordinates is assumed to be the same as that of the geocoding service. The input can either be a comma-separated list of coordinates defining the bounding box or JSON envelope object. The searchExtent coordinates should always use a period as the decimal separator, even in countries where traditionally a comma is used.

Example

//coordinates defining the bounding box
searchExtent=-104,35.6,-94.32,41

//JSON envelope object
searchExtent= { "xmin" : -109.55, "ymin" : 25.76, "xmax" : -86.39, "ymax" : 49.94, "spatialReference" : {"wkid" : 4326} }
langCode

(Optional)

Sets the language in which geocode results are returned. This is useful for ensuring that results are returned in the expected language. 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, then the resultant match is returned in the language code of the primary matched components from the input search string. See the table of supported countries for more information and valid language code values in each country. Note that full language names cannot be used in the langCode parameter.

Example

langCode=fr
token

(Required)

Specifies a token that provides the identity of a user who has the appropriate permissions to access the service.

f

(Required)

The response format. The default response format is html.

Values: html | json | kmz

Address parameter syntax and examples

Example syntax for the address parameter:

{ 
  "records"  : [
   {
     "attributes": {
       "<OBJECTID>": "<OID11>", 
       "<field1>" : "<value11>", 
       "<field2>" : "<value12>", 
       "<field3>" : "<value13>"
     }
   },
   {
     "attributes": {
       "<OBJECTID>": "<OID21>", 
       "<field1>" : "<value21>", 
       "<field2>" : "<value22>", 
       "<field3>" : "<value23>"
     }
   }
  ]
}

Example One: The addressField of a geocode service resource includes fields with the names Street and Zone. You can provide the input for addresses as follows:

{       
  "records": [
   {
     "attributes": {
       "OBJECTID": 1, 
       "STREET": "440 Arguello Blvd", 
       "ZONE": "94118"
     }
   },
   {
     "attributes": {
       "OBJECTID": 2, 
       "STREET": "450 Arguello Blvd", 
       "ZONE": "94118"
     }
   }
  ]
}

Example Two: Using a single-line address input, where singleLine is the name of the singleLineAddressField property of the geocode service.

{
  "records": [
   {
     "attributes": {
       "OBJECTID": 1, 
       "SingleLine": "440 Arguello Blvd, San Francisco, CA 94118"
     }
   },
   {
     "attributes": {
       "OBJECTID": 2, 
       "SingleLine": "450 Arguello Blvd, San Francisco, CA 94118"
     }
   }
  ]
}

Example usage

Example URL for batch geocoding a list of addresses:

https://myserver/arcgis/rest/services/SFOStreets/GeocodeServer/geocodeAddresses?addresses={"records":[{"attributes":{"OBJECTID":1,"STREET":"440 Arguello Blvd","ZONE":"94118"}},{"attributes":{"OBJECTID":2,"STREET":"450 Arguello Blvd","ZONE":"94118"}}]}&outSR=&f=pjson

JSON Response syntax

{
  "spatialReference" : <spatialReference>,
  "locations" : [  
   {  
     "address": "<address1>",  
     "location": { <point1> },  
     "score": <score1>,  
     "attributes": {<fieldName1>: <value11>, <fieldName2>: <value12>}  
   },  
   {  
     "address": "<address2>",  
     "location": { <point2> },  
     "score": <score2>,  
     "attributes": {<fieldName1>: <value21>, <fieldName2>: <value22>}  
   } 	
  ]
}

JSON Response example

{
  "spatialReference": {
     "wkid": 4269,"latestWkid": 4269
  },
  "locations": [
   {
     "address": "440 ARGUELLO BLVD, 94118",
     "location": {
       "x": -122.45887187536766, 
       "y": 37.782653319533836
     },
     "score": 94,
     "attributes": {
       "ResultID": 1, 
       "Status": "M", 
       "Score": 94, 
       "Side": "L", 
       "Match_addr": "440 ARGUELLO BLVD, 94118"
     }
   },
   {
     "address": "450 ARGUELLO BLVD, 94118",
     "location": {
       "x": -122.45885341927038, 
       "y": 37.782436661000418
     },
     "score": 94,
     "attributes": {
       "ResultID": 2, 
       "Status": "M", 
       "Score": 94, 
       "Side": "L", 
       "Match_addr": "450 ARGUELLO BLVD, 94118"
     }
   }
  ]
}

Handling JSON Response

The geocodeAddresses operation results in an output JSON. However, with any REST protocol, the REST response is not always a success. A variety of things could cause a REST request to fail:

If there is a time-out in processing the REST request, you can write code to handle these request failures. When a timeout occurs, your code will need to:

The retry logic described above is recommended best practice when using the geocodeAddresses operation. The Geocode Addresses, Geocode File, and Geocode Locations from Table tools in ArcGIS Pro already have this logic built-in to ensure batch geocoding never fails against a locator service.