Find Address Candidates

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.

Description: Specifies the location to be geocoded. The input address components are formatted as a single string. The singleLine parameter and <addressField> parameters should not be passed in the same request.

Example: singleLine=380 New York St, Redlands, California 92373

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.

This parameter was added at 10.3, and is only supported by geocode services published with ArcGIS 10.3 for Server and later versions.

Example: maxLocations=10

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.

Description: The well-known ID (WKID) 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.

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.

Description: Defines an origin point location that is used with the distance parameter to sort geocoding candidates based on their proximity to the location. The distance parameter specifies the radial distance from the location in meters. The priority of candidates within this radius is boosted relative to those outside the radius.

This is useful in mobile applications where a user searches for places in the vicinity of their current GPS location; the location and distance parameters can be used in this scenario.

The location parameter can be specified without specifying a distance. If distance is not specified, it defaults to 2000 meters.

The location can be represented with a simple comma-separated syntax (x,y), or as a JSON point object. If the spatial reference of the location coordinates is different than that of the geocode service, then it must be defined in the JSON object. If the comma-separated syntax is used, or if the spatial reference is not included in the JSON object, then the spatial reference of the location is assumed to be the same as that of the geocode service.

This parameter was added at 10.3 and is only supported by geocode services published with ArcGIS 10.3 for Server and later versions.

Example using simple syntax (WGS84): location=-117.196,34.056

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

Description: Specifies the radius of an area around a point location that is used to boost the rank of geocoding candidates so that candidates closest to the location are returned first. The distance value is in meters.

If the distance parameter is specified, the location parameter must be specified as well.

Unlike the searchExtent parameter, the location and distance parameters allow searches to extend beyond the specified search radius. They are not used to filter results, but rather to rank resulting candidates based on their distance from a location. You must pass a searchExtent value in addition to location and distance if you want to confine the search results to a specific area.

This parameter was added at 10.3 and is only supported by geocode services published with ArcGIS 10.3 for Server and later versions.

Example: distance=3218.69

Description: The findAddressCandidates operation retrieves results more quickly when you pass in valid singleLine and magicKey values than when you don't pass in magicKey. However, to get this advantage, you need to make a prior request to the suggest operation, which provides a magicKey. This may or may not be relevant to your workflow.

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 into 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 find operations.

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

1. Make a request to suggest. The response includes text and magicKey properties.
2. Make a request to findAddressCandidates and pass in the text and magicKey values returned from suggest as the singleLine and magicKey input parameters respectively.

Note:

The magicKey parameter will not function correctly if passed alone. Both magicKey and singleLine must be included in a findAddressCandidates request so that the output matches the selected suggestion.

This parameter was added at 10.3 and is only supported by geocode services published with ArcGIS 10.3 for Server and later versions.

Example: magicKey=JS91CYhQDS5vDPhvSMyGZby0YFbaUDoaM5bHMoFF

The category parameter is only supported by geocode services published using StreetMap Premium locators.

This parameter was added at 10.3 and is only supported by geocode services published with ArcGIS 10.3 for Server and later versions.