Find Address Candidates

address, address2, address3

(Optional)

The full street address of a place (excluding administrative divisions and postal codes) may consist of multiple components, such as building name, street, and subunit (apartment). Web forms and written correspondence typically use multiple fields or lines to designate these components. The findAddressCandidates operation supports three address parameters which can be used to represent the different components of a street address: address, address2, and address3. If you want to geocode the address Beetham Tower, 301 Deansgate, Suite 4208, Manchester, England using multiple input fields, you can set address=Beetham Tower, address2=301 Deansgate, and address3=Suite 4208.

The address parameter is 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.

The address2 parameter is a string that represents the second line or a street address. This can include street name/house number, building name, place-name, or subunit.

The address3 parameter is a string that represents the third line of a street address. This can include street name/house number, building name, place-name, or subunit.

For additional 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. A neighborhood is a subdivision of a city.

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. A city is a subdivision of a subregion or a region.

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 three- to six-digit alphanumeric code.

postal=92373

(Optional)

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

postalExt=1112

(Optional)

A value representing the country in a multifield geocoding request. Providing this value increases geocoding speed. Acceptable values include the full country name in English or the official language of the country, the two-character country code, or the three-character country code. A list of supported countries and codes is available in the Geocode coverage topic.

Note:

The sourceCountry and countryCode parameters are similar but serve different purposes. The countryCode parameter defines the country value for a multifield geocode request. The sourceCountry parameter defines the country value for a request regardless of whether it is a single-field or multifield request. If both countryCode and sourceCountry are included in a findAddressCandidates request, and the country values are different, the countryCode value takes priority over sourceCountry.

countryCode=USA

(Optional)

Specifies the location to be geocoded. This can be a street address, place-name, postal code, or point of interest (POI). The input address components must be formatted as a single string.

Caution:

The singleLine parameter should not be passed in the same request as any of the above multiline address parameters, which allow for address components to be separated into multiple parameters.

singleLine=380 New York St, Redlands, California 92373

(Optional)

A place or address type that can be used to filter findAddressCandidate results. This parameter supports input of single category values or multiple, comma-separated values. The category parameter can be passed either in a request with the singleLine or multilineaddress parameters. It can also be passed in a request on its own without the singleLine or multiline address parameters. See Category filtering for complete parameter details.

Note:

If more than one value is specified for the parameter, the values must be separated by a comma, with no spaces after the comma.

category=Address,Postal

(Optional)

The list of fields to be returned within the attributes object of the response. 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.

Note:

If more than one value is specified for the parameter, the values must be separated by a comma, with no spaces after the comma.

//Return specified fields
outFields=AddNum,StName,City

//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. This is useful for applications using a map with a spatial reference different than that of the geocode service.

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 locations 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. This is especially useful for applications in which a user will search for places and addresses within the current map extent.

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. The spatial reference of the bounding box coordinates can be included if an envelope object is used.

Note:

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 prefer or boost geocoding candidates based on their proximity to the location. Candidates near the location are prioritized relative to those farther away. This is useful in mobile applications where a user wants to search for places in the vicinity of their current GPS location, or in mapping applications where users want to search for places near the center of the map.

The location can be represented with 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 the same as the spatial reference of the locator on which the geocode service is based; otherwise, the spatial reference of the point coordinates can be defined in the JSON object.

//Simple syntax (default SR)
location=-117.196,34.056

(Optional)

The findAddressCandidates operation retrieves results quicker when you pass in valid singleLine and magicKey values than when you don't pass in magicKey. However, to get these advantages, you need to make a prior request to suggest, which provides a magicKey.

The suggest operation is often called on to improve the user experience of search boxes by analyzing partial text and providing complete names of places, addresses, points of interest, and so on. For instance, typing Mbu in a search box offers Mbuji-Mayi, Democratic Republic of the Congo as a suggestion, so the user doesn't need to type the complete name.

Looking at the suggestion process from another perspective, as the user types, the suggest operation performs a text search, which is a redundant part of the overall search that the findAddressCandidates operation can also perform. The user chooses a place-name or type, narrowing the results to a specific record. The results from suggest include text and magicKey values that contain the information the user chose; passing these values from suggest into findAddressCandidates results in faster and more accurate operations.

In summary, using the magicKey parameter in findAddressCandidates is a two-step process:

• Make a request to suggest. The response includes text and magicKey properties.
• Make a request to findAddressCandidates and pass in the text and magicKey values returned from suggest as the SingleLine and magicKey input parameters, respectively. The magicKey parameter will not function correctly if passed alone. Both magicKey and SingleLine must be included in a findAddressCandidates request so the output matches the selected suggestion.

Note:

For best results, when the searchExtent and location parameters are included in a suggest request, the same parameters should be included in the corresponding findAddressCandidates request.

magicKey=JS91CYhQDS5vDPhvSMyGZby0YFbaUDoaM5bHMoFF

(Optional)

A Boolean that specifies whether StreetAddress matches should be returned even when the input house number is outside of the house number range defined for the input street. Out of range matches have Addr_type=StreetAddressExt. The geometry of such matches is a point corresponding to the end of the street segment where the range value is closest to the input house number. If matchOutOfRange is not specified in a request, its value is set to true by default.

With matchOutOfRange, better spatial accuracy is provided for inexact street address searches. Most street segments are assigned house number ranges. For example, Main Street may include house numbers from 2-100 on one side of the street and 1-99 on the other. A user may search for a house number that is not within this range, such as 109 Main Street. If matchOutOfRange=false is passed in this request, the geocode service will return a StreetName-level match to Main Street, with geometry corresponding to the centerline of a street segment that most closely matches the input values. StreetName matches can be ambiguous because there may be multiple street segments with the same name that equally match the input. However, if matchOutOfRange=true in this case, a more precise geometry is returned to the specific side of the segment of Main Street with house number range 1-99.

Note:

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 number ranges, the maxOutOfRange tolerance is less than 100.

Values: true | false

(Optional)

Specifies whether the output geometry of PointAddress and Subaddress matches should be the rooftop point or street entrance location. Valid values are rooftop and street. The default value is rooftop.

Geocode results include one geometry object (the location object) that defines the location of the address, as well as two sets of X/Y coordinate values within the attributes object: X/Y, and DisplayX/DisplayY. In most cases, for geocode results with Addr_type=PointAddress or Subaddress, the X/Y attribute values describe the coordinates of the address along the street, while the DisplayX/DisplayY values describe the rooftop, or building centroid, coordinates. By default, the geometry returned for geocode results represents the rooftop location of the address (if the rooftop location is available in the source data). This is useful for most spatial analysis and map display purposes. However, for routing scenarios, it may be desirable to use the street location because the rooftop location of some addresses may be offset from a street by a large distance. For these cases, the locationType parameter can be used to specify that the street entrance geometry should be returned.

It is important to note that locationType is limited by the address data sources used to build the locator for the geocoding service. Not all PointAddress and Subaddress features include rooftop and street location coordinates. For some addresses, only a rooftop location is available; for others, only a street location is provided by the data source. For cases such as this, the locationType parameter may not function as expected. For example, if only rooftop location coordinates are available for an address, the rooftop geometry will be returned for the geocoded address even when locationType=street

is requested.

Note:

The locationType parameter only affects the location object in the geocode JSON response. It does not change the X/Y or DisplayX/DisplayY attribute values.

Values: street | rooftop

(Optional)

Sets the language in which geocode results are returned. Addresses and places in many countries are available in more than one language; in these cases, the langCode parameter can be used to specify which language should be used for results returned by the findAddressCandidates operation. This is useful for ensuring that results are returned in the expected language. For example, a web application could be designed to get the browser language and pass it as the langCode parameter value in a findAddressCandidates request.

See the table of supported countries for valid language code values in each country. Full language names cannot be used in the langCode parameter. Only one language code value can be included for the langCode parameter in a findAddressCandidates request.

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 component from the input search string. Typically, this is either place-name or street name, depending on the search string.

It is important to note that langCode is limited by the address data sources used to build the locator for the geocoding service. This parameter will be ignored when not supported by the data.

langCode=fr

(Optional)

Limits the candidates returned by the findAddressCandidates operation to the specified country or countries for either single-field or multifield requests. For example, if sourceCountry=USA is included in the request, it is assumed that the address is in the United States, so only matching addresses in USA are returned. Using this parameter prevents potential unexpected results in other countries for ambiguous searches.

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 to limit results to more than one country.

Note:

The sourceCountry and countryCode parameters are similar but serve different purposes. The countryCode parameter defines the country value for a multifield geocode request. The sourceCountry parameter defines the country value for a request regardless of whether it is a single-field or multifield request. If both countryCode and sourceCountry are included in a findAddressCandidates request, and the country values are different, the countryCode value takes priority over sourceCountry.

Note:

If more than one value is specified for the parameter, the values must be separated by a comma, with no spaces after the comma.

sourceCountry=FRA,DEU,ESP

(Optional)

Allows simple configuration of output fields returned in a response from the geocoding service by specifying which address component values should be included in output fields. Supports a single value or a comma-delimited collection of values as input. If the parameter is blank or excluded from a request, default address label formats will be used.

A particular address may have multiple city names associated with it. In the United States for example, all addresses have a ZIP code (postal code) assigned to them. Each ZIP code has one or more associated locality names, which are known as postal cities. There is always one primary postal city value for each ZIP code. ZIP codes typically have no set boundaries, and the primary postal city name for the ZIP code that is assigned to an address may be different than the name of the local city that the address is within.

Note:

In the context of the preferredLabelValues parameter, the name of the city whose boundary an address is within is referred to as the "local" city, as opposed to the "postal" city name assigned to the address's postal code.

Additional details:

• The preferredLabelValues parameter takes a comma-delimited collection of values as input.
• The parameter values correspond to two groups: a City group and a Street group, indicated by the suffix of the value name. The postalCity, localCity, and matchedCity values are part of the City group. The primaryStreet and matchedStreet values are part of the Street group.
• A geocode request can include one City value and one Street value, for instance: preferredLabelValues=primaryStreet,postalCity.
• A request can only include one value per group. In other words, a request with preferredLabelValues=matchedCity,postalCity is invalid.

Note:

The functionality of the preferredLabelValues parameter is limited by the data sources used to produce the locator on which the geocoding service is based. Not all addresses have postal city and local city values assigned to them. Likewise, only certain streets may include primary and alternate names. If the preferredLabelValues parameter is used and the output labels don't correspond to expectations in some cases, it is likely because the expected values aren't included in the source data for the addresses.

preferredLabelValues=matchedCity,primaryStreet

(Required)

The response format. The default response format is html.

Values: html | json |pjson| kmz