ArcGIS REST API - ArcGIS Services - Find Address Candidates

Description

The findAddressCandidates operation is performed on a geocode service resource. The result of this operation is a resource representing the list of address candidates. This resource provides information about candidates, including the address, location, and match score. Locators published using ArcGIS Server 10 or later support the single line address field for the findAddressCandidates operation.

You can provide arguments to the findAddressCandidates operation as query parameters defined in the following parameters table:

Request parameters

Parameter	Details
f	Description: The response format. The default response format is html. Values: html \| json \| kmz
<addressField1>, <addressField2>, and so on	Description: The various address fields accepted by the corresponding geocode service. These fields are listed in the addressFields property of the JSON representation associated geocode service resource. Example: Suppose that addressFields of a geocode service resource includes fields with the following names: Street, City, State, and Zone. If you want to perform the findAddressCandidates operation by providing values for the Street and Zone fields, you'd set the query parameters as Street=380+New+York+St&Zone=92373.
maxLocations	Description: The maximum number of locations to be returned by a search, up to the maximum number allowed by the geocode service. If not specified, the maximum number of candidates for which the service is configured will be returned. Note: The GeocodeServer parameter maxResultSize defines the maximum number of candidates allowed by the geocode service. Example: maxLocations=10
outFields	Description: The list of fields to be included in the returned result set. This list is a comma-delimited list of field names. If you specify the shape field in the list of return fields, it is ignored. For non-intersection addresses, you can specify the candidate fields from the geocode service resource. For intersection addresses, you can specify the intersection candidate fields from the geocode service resource. Example: outFields=StreetName,StreetType Added at 10.0: outFields = * returns all fields.
outSR	Description: The well-known ID of the spatial reference or a spatial reference json object for the returned address candidates. For a list of valid WKID values, see Projected coordinate systems and Geographic coordinate systems. This parameter was added at 10.0.
searchExtent	This parameter was added at 10.1. Description: The spatial extent (bounding box) to be used in geocoding. The response will return only the candidates that are within this spatial extent. Unless the spatialReference is included in the searchExtent, the coordinates are assumed to be in the spatial reference of the locator. This optional parameter is supported only for services that use locators created using ArcGIS 10.0 or later. Syntax: {<envelope>} Simple syntax: <xmin>, <ymin>, <xmax>, <ymax> Example 1: searchExtent= { "xmin" : -109.55, "ymin" : 25.76, "xmax" : -86.39, "ymax" : 49.94, "spatialReference" : {"wkid" : 4326} } Example 2: searchExtent=-104,35.6,-94.32,41 The searchExtent coordinates should always use a period as the decimal separator even in countries where traditionally a comma is used.

Example usage

Geocode an address (380 New York Street, Redlands, CA 92373):

http://sampleserver1.arcgisonline.com/ArcGIS/rest/services/Locators/ESRI_Geocode_USA/GeocodeServer/findAddressCandidates?Address=380+New+York+Street&City=Redlands&State=CA&Zip=92373

JSON response syntax

            
          
{"spatialReference" : <spatialReference>, //Added in 10 "candidates" : [  {  "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" : 4326},
"candidates" : [
  {
  "address" : "1 MASON ST",
  "location" : { "x" : -122.408951, "y" : 37.783206 },
  "score" : 75,
  "attributes" : {"StreetName" : "MASON", "StreetType" : "ST"}
  },
  {
  "address" : "49 MASON ST",
  "location" : { "x" : -122.408986, "y" : 37.783460 },
  "score" : 27,
  "attributes" : {"StreetName" : "MASON", "StreetType" : "ST"}
  } 	
]
}