Skip To Content
ArcGIS Developers
Dashboard

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 singleLine address field for the findAddressCandidates operation.

New parameters at 10.6

  • matchOutOfRange—Provides better spatial accuracy for inexact street addresses.
  • locationType—Specifies whether the output geometry of PointAddress matches is the rooftop point or street entrance location.
  • langCode—Specifies the language in which geocode results are returned.

New parameters at 10.3

  • maxLocations—Specifies the maximum number of locations returned by a search.
  • location—Defines an origin point that is used to boost search results for the closest address candidates.
  • distance—Specifies the radius of an area (in meters) around a point location that is used to boost the rank of geocoding candidates so that those closest to the location are returned first.
  • magicKey—A unique ID that links a suggestion to a specific address or place.
  • category—Identifies a place or address that can be used to filter the operation's results.

New parameter at 10.1

  • searchExtent—Defines a set of bounding box coordinates that limit the search area to a specific region.

New parameters at 10.0

  • outSR—Specifies the spatial reference of the x,y coordinates returned by a geocode request.
  • sourceCountry—Limits the candidates returned to the specified country or countries for either single-field or multifield requests.

Request parameters

ParameterDetails

address, address2, address3

(Optional)

The findAddressCandidates operation supports these three address parameters that can be used to represent the different components of a street address, such as a building name, street, and subunit or apartment. For example usage, see Address parameter syntax and examples.

neighborhood

(Optional)

The smallest administrative division associated with an address, typically a neighborhood or a section of a larger populated place.

Note:

The neighborhood parameter is not used in all countries or regions.

Example

neighborhood=Herrera
city

(Optional)

The next largest administrative division associated with an address, typically a city or municipality.

Example

city=Los Angeles
subregion

(Optional)

The next largest administrative division associated with an address. Depending on the country, a subregion can represent a county, state, or province.

Example

subregion=Vienne
region

(Optional)

The largest administrative division associated with an address, typically a state or province.

Example

region=Florida
postal

(Optional)

The standard postal code for an address, typically a 3–6 digit alphanumeric code.

Example

postal=92373
postalExt

(Optional)

A postal code extension, such as the United States Postal Service ZIP+4 code. This provides finer resolution or higher accuracy when also passing the postal parameter.

Example

postalExt=1112
countryCode

(Optional)

A value representing the country for a multifield geocode request. Acceptable values include the full country name in English or the official language of the country, the 2-character country code, or the 3-character country code. A list of supported countries and codes is available in the Geocode coverage topic. If both countryCode and sourceCountry are included in a request, and the country values are different, the countryCode value takes priority over sourceCountry.

Example

countryCode=USA
singleLine

(Optional)

A single string that specifies the location to be geocoded, formatted as a single string. This can be a street address, place-name, postal code, or point-of-interest (POI).

Caution:

The singleLine and address parameters should not be passed in the same request.

Example

singleLine=380 New York St, Redlands, California 92373
category

(Optional)

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

Example

category=Address,Postal
outFields

(Optional)

The list of fields to be returned within the attribute objects of the response. This parameter supports input of single category values or multiple, comma-separated (without spaces) values. To return the default output fields, outField does not need to be passed in the request.

Example

//Multiple values
outFields=PlaceName,Type,City,Country

//Return all fields
outFields=*
maxLocations

(Optional)

The maximum number of locations to be returned by a search, up to the maximum number allowed by the service. If not specified, all matching candidates up to the service maximum are returned.

Example

maxLocations=10
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
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 be either a comma-separated list of coordinates defining the bounding box or a JSON envelope object. When using searchExtent coordinates, 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} }
location

(Optional)

Defines an origin point that is used to boost search results for the closest address candidates based on their proximity to the location. The structure of the point can be represented as a simple comma-separated syntax (x,y) or as a JSON point object. If the comma-separated syntax is used, the spatial reference of the coordinates must be WGS84; otherwise, the spatial reference of the point coordinates can be defined in the JSON object. The location parameter can be used without specifying the distance parameter. If distance is not specified, it defaults to 2000 meters.

Example

//simple syntax (WGS84)
location=-117.196,34.056

//JSON with spatial reference
location= { "x": -13046165.572, "y": 4036389.847, "spatialReference": { "wkid": 102100 } }
distance

(Optional)

Specifies the radius of an area (in meters) around a point location that is used to boost the rank of geocoding candidates so that candidates closest to the location are returned first. If this parameter is not provided, or an invalid value is given, a default value of 0 meters is used. If distance is specified, location must be specified as well. It is important to note that the location and distance parameters allow searches to extend beyond the specified search radius. They do not filter results as searchExtent does; they rank resulting candidates based on their distance from a location.

Example

distance=3218.69
magicKey

(Optional)

The findAddressCandidates operation retrieves results quicker when you pass valid singleLine and magicKey values. To get these advantages, you need to make a prior request to suggest . While this operation is redundant overall for the findAddressCandidates operation, the results from suggest includes a magicKey value that—when passed through this operation—results in faster and more accurate results. To function properly, both the magicKey and singleLine parameters must be included in the request.

Example

magicKey=JS91CYhQDS5vDPhvSMyGZby0YFbaUDoaM5bHMoFF
matchOutOfRange

(Optional)

Provides better spatial accuracy for inexact street addresses by specifying whether matches will 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 is used as the output geometry of PointAddress matches. By default, street is used, which is useful in routing scenarios, as the rooftop location of some addresses may be offset from a street by a large distance. However, for map display purposes, you may want to use rooftop instead, especially when large buildings or landmarks are geocoded. The locationType 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

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, 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 valid language code values in each country. Full language names cannot be used in the langCode parameter.

Example

langCode=fr
sourceCountry

(Optional)

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

Example

sourceCountry=FRA,DEU,ESP
f

(Required)

The response format. The default response format is html.

Values: html | json | kmz

Address parameter syntax and examples

address

A string that represents the first line of a street address. In most cases, this field will be used for street name and house number input, but it can also be used to input building name or place name.

address=380 New York Street

address2

A string that represents the second line of a street address. This can include street name and house number, building name, place name, or subunit.

address2=Beetham Tower

address3

A string that represents the third line of a street address. This can include street name and house number, building name, place name, or subunit.

address3=Suite 4208

Multiple input field example

The following example geocodes the address Beetham Tower, 301 Deansgate, Suite 4208, Manchester England:

address=Beetham Tower,
address2=301 Deansgate,
address3=Suite 4208

Example usage

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

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

Note:

The address location (x,y coordinates of the match location), score, extent, and spatialReference objects are returned in the response by default. If the outFields parameter is excluded from the request, or if it is included but no fields are specified, the attributes object in the corresponding response is blank.

{
 "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": "380 NEW YORK ST, REDLANDS, CA, 92373",
      "location": {
        "x": -117.19568138599993,
        "y": 34.05751709700013
      },
      "score": 100,
      "attributes": {
        
      }
    },
    {
      "address": "458 NEW YORK ST, REDLANDS, CA, 92373",
      "location": {
        "x": -117.1956968799999,
        "y": 34.058514920000164
      },
      "score": 60,
      "attributes": {
        
      }
    },
    {
      "address": "298 NEW YORK ST, REDLANDS, CA, 92373",
      "location": {
        "x": -117.19565024999986,
        "y": 34.055553690000124
      },
      "score": 60,
      "attributes": {
        
      }
    },
    {
      "address": "474 NEW YORK ST, REDLANDS, CA, 92373",
      "location": {
        "x": -117.19569395999991,
        "y": 34.058597130000066
      },
      "score": 60,
      "attributes": {
        
      }
    },
    {
      "address": "500 NEW YORK ST, REDLANDS, CA, 92373",
      "location": {
        "x": -117.19572502999989,
        "y": 34.059255410000162
      },
      "score": 59,
      "attributes": {
        
      }
    },
    {
      "address": "198 NEW YORK ST, REDLANDS, CA, 92373",
      "location": {
        "x": -117.19562530999991,
        "y": 34.053680830000076
      },
      "score": 58,
      "attributes": {
        
      }
    },
    {
      "address": "98 NEW YORK ST, REDLANDS, CA, 92373",
      "location": {
        "x": -117.19560230999997,
        "y": 34.051971620000018
      },
      "score": 55,
      "attributes": {
        
      }
    },
    {
      "address": "NEW YORK ST",
      "location": {
        "x": -117.19572987999987,
        "y": 34.059561930000143
      },
      "score": 49,
      "attributes": {
        
      }
    },
    {
      "address": "92373",
      "location": {
        "x": -117.18653499999999,
        "y": 34.03855800000008
      },
      "score": 100,
      "attributes": {
        
      }
    },
    {
      "address": "REDLANDS, CA",
      "location": {
        "x": -117.17131599999993,
        "y": 34.050274000000059
      },
      "score": 100,
      "attributes": {
        
      }
    }
  ]
}