Geocode Addresses
- URL:https://<geocodeservice-url>/geocodeAddresses
- Version Introduced:10.1
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.
Note: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
- The searchExtent parameter specifies a set of bounding box coordinates that limit the search area to a specific region.
- The langCode parameter sets the language in which geocode results are returned.
New at 10.6
- The locationType parameter specifies whether the output geometry of PointAddress matches should be the rooftop point or street entrance location.
- The matchOutOfRange parameter provides better spatial accuracy for inexact street addresses.
New at 10.3
- The category parameter identifies a place or address that can be used to filter the operation's results.
- The sourceCountry parameter limits the candidates returned to the specified country or countries for either single-field or multifield requests.
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 |
| 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 |
| 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 |
| 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 |
| 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 |
| 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:
- Incorrect authentication (token required or invalid token).
- Incorrect syntax in the request. Make sure the request being sent is properly formatted JSON.
- Internet connectivity issues.
- Server time-out.
- Recognize the time-out in the JSON response.
- Split the request into smaller batch sizes and resubmit the request as two, smaller, separate requests. Each request will be half the size of the original request and will contain half the addresses.
- See if each request succeeds. If one of the batches fails due to a time-out, continue the process of splitting the failing batch in two and sending both requests.
- If a request is sent with only one address and it times out, then manually write that record as unmatched and continue processing requests.
- Continue this process until all batch requests have completed successfully.
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.