Find Address Candidates

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.

(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.

neighborhood=Herrera

(Optional)

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

city=Los Angeles

(Optional)

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

subregion=Vienne

(Optional)

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

region=Florida

(Optional)

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

postal=92373

(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.

postalExt=1112

(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.

countryCode=USA

(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.

singleLine=380 New York St, Redlands, California 92373

(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.

category=Address,Postal

(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.

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

//Return all fields
outFields=*

(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.

maxLocations=10

(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.

outSR=102100

(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.

//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} }

(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.

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

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

(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.

distance=3218.69

(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.

magicKey=JS91CYhQDS5vDPhvSMyGZby0YFbaUDoaM5bHMoFF

(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

(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

(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.

langCode=fr

(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.

sourceCountry=FRA,DEU,ESP

(Required)

The response format. The default response format is html.

Values: html | json | kmz