findAddressCandidates

The findAddressCandidates operation geocodes one location per request; the input address can be combined into a single input field or divided among multiple parameters.

findAddressCandidates

Note:

The find operation has been deprecated. Please discontinue using it in your application, and use the findAddressCandidates operation instead.

The findAddressCandidates operation supports finding the following types of locations:

Request URL

http://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer/findAddressCandidates?<PARAMETERS>

There are several options for refining or restricting search results. These include the following:

  • Specify output fields to return in the geocoding response with the outFields parameter.
  • Specify the spatial reference of candidates with the outSR parameter.
  • Limit the number of candidates with the maxLocations parameter.
  • Confine the search results to a specified area with the searchExtent parameter.
  • Use the location and distance parameters to prefer local candidates, which will then be returned higher in the candidates list.
  • Filter search results using the category parameter.

Request parameters

The findAddressCandidates operation supports searching for places and addresses in single-field format (the singleLine parameter) or in multifield format with the address components separated into multiple parameters. Single-field input is easier because the address parsing is done for you; however, multifield input may provide faster responses and more precise results.

In order to provide a way to find addresses in many different countries, which may use different addressing formats, the findAddressCandidates operation uses standardized field names for submitting address components. In the parameters listed below, the neighborhood, city, subregion, and region parameters represent typical administrative divisions within a country. They may have different contexts for different countries, and not all administrative divisions are used in all countries. For instance, with addresses in the United States, only the city (city) and region(state) parameters are used; for addresses in Mexico, the neighborhood parameter is used for districts (colonias) within a city, city for municipalities (municipios), and the region parameter for states (estados); Spain uses all four administrative divisions.

The service info page http://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer?f=pjson provides localized versions of the input field names in all locales supported by the service. See Localized input field names for more information.

Required parameters

The findAddressCandidates operation has only one required parameter: f. However, you also need to pass address or place information, which can be done by passing the name as a single line of text for clarity or passing it as multiple fields of text for accuracy. To access single-line functionality, the singleLine parameter is required. To access multifield functionality instead, any combination of the address, neighborhood, city, region, subregion, countryCode, and postal parameters is required.

Note:

The singleLine parameter can be combined with the countryCode parameter in a request. The singleLine parameter cannot be used with any of the other multifield parameters.

Note:

The category parameter is only functional when used with the singleLine parameter. It does not work with the multifield parameters, specifically, the address, neighborhood, city, region, subregion, countryCode, and postal parameters.

f

The service supports responses in JSON or PJSON format. You can specify the response format using the f parameter. This is a required parameter.

Example:
f=pjson

Optional parameters

singleLine

Specifies the location to be geocoded. This can be a street address, place-name, postal code, or POI. The input address components need to be formatted as a single string.

Note:

The singleLine parameter is not required if the category parameter is included in the request with a valid value.

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

address

The address that commonly represents the house number and street name of a complete address.

Example of a street address in the U.S.:
address=380 New York Street
Example of a street address in Mexico:
address=Avenida Revolucion 8208

neighborhood

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.

Example of a neighborhood in Mexico (colonia):
neighborhood=Herrera

city

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.

Example of a city in the U.S.:
city=Los Angeles
Example of a city in Mexico:
city=Tijuana

subregion

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

Note:

A subregion is not used in Mexico or USA.

Example of a subregion in Russia (oblast):
subregion=Novgorodskaya oblast

region

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

Example of a region in the U.S. (state):
region=Florida
Example of a region in Mexico (estado):
region=Baja California

postal

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

Example:
postal=92373

postalExt

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

Example:
postalExt=1112

countryCode

A value representing the country. Providing this value increases geocoding speed. Acceptable values include the full country name in English or the official language of the country, the ISO 3166-1 2-digit country code, or the ISO 3166-1 3-digit country code. A list of supported countries and codes is available in Geocode coverage.

Example:
countryCode=USA

magicKey

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. 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 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, location, and distance parameters are included in a suggest request, the same values should be included with the searchExtent, location, and distance parameters in the corresponding findAddressCandidates request.

Example:
magicKey=JS91CYhQDS5vDPhvSMyGZby0YFbaUDoaM5bHMoFF

searchExtent

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 coordinates is assumed to be the same as that of the geocoding service.

The input can either be 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.

Example without a spatial reference:
searchExtent=-104,35.6,-94.32,41
Example with a spatial reference:
searchExtent=
{
    "xmin": -13052769,
    "ymin": 3951172,
    "xmax": -13019630,
    "ymax": 3978490,
    "spatialReference": {
        "wkid": 3395
    }
}

location

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 will want to search 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 50,000 meters.

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 WGS84; otherwise, the spatial reference of the point coordinates can be defined in the JSON object.

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

distance

Specifies the radius of an area around a point location used to boost the rank of geocoding candidates so 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.

It is important to note that 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.

Example of searching within 2 miles of the current extent:
distance=3218.69

category

A place or address type that can be used to filter findAddressCandidates results. The parameter supports input of single category values or multiple comma-separated values. The category parameter can be passed in a request with or without the singleLine parameter. See Category filtering for complete details about the category parameter.

Example of category filtering with a single category:
category=Address
Example of category filtering with multiple categories:
category=Address,Postal

outSR

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 as 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. The World Geocoding Service spatial reference is WGS84 (WKID = 4326).

For a list of valid WKID values, see Projected Coordinate Systems and Geographic Coordinate Systems.

Example (102100 is the WKID for the Web Mercator projection):
outSR=102100

outFields

The list of fields to be returned in the response. Descriptions for each of these fields are available in the Output fields section of this document.

The returned address, x/y coordinates of the match location, match score, spatial reference, extent of the output feature, and the addr_type (match level) are returned by default.

Example that returns all output fields:
outFields=*
Example that returns the specified fields only:
outFields=AddrNum,StName,City

maxLocations

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

The World Geocoding Service allows up to 20 candidates to be returned for a single request. Note that up to 50 POI candidates can be returned.

Example:
maxLocations=10

forStorage

Specifies whether the results of the operation will be persisted. The default value is false, which indicates the results of the operation can't be stored, but they can be temporarily displayed on a map for instance. If you store the results, in a database, for example, you need to set this parameter to true.

Applications are contractually prohibited from storing the results of geocoding transactions unless they make the request by passing the forStorage parameter with a value of true and the token parameter with a valid ArcGIS Online token. Instructions for composing a request with a valid token are provided in the authentication topic.

ArcGIS Online service credits are deducted from the organization account for each geocode transaction that includes the forStorage parameter with a value of true and a valid token. Refer to the ArcGIS Online service credits overview page for more information on how credits are charged.

To learn more about free and paid geocoding operations, see Free vs. paid operations.

Example:
forStorage=true

Search for street addresses

You can search for a street address, street name, or street intersection using the findAddressCandidates operation. For best results, you should include as much location information as possible in the search in addition to the street address. See Match accuracy for more information about obtaining optimal results for address searches.

You can pass the address components in a single parameter or separated into multiple parameters. Examples of each are shown. Note that in each case the JSON response is the same for both the single and multiple parameter requests.

Example: Find a street address (380 New York Street, Redlands, CA 92373)

Single-field request URL

Multifield request URL: In this example, the street address component (380 New York St) is passed as the value for the address parameter; the city component (Redlands) as the value for the city parameter; the state component (CA) as the region parameter; and the ZIP Code (92373) as the value for the postal parameter. Also in this example, all possible output fields are returned (outFields=*), even if they don't contain a value.

JSON response

{
 "spatialReference": {
  "wkid": 4326,
  "latestWkid": 4326
 },
 "candidates": [
  {
   "address": "380 New York St, Redlands, California, 92373",
   "location": {
    "x": -117.19566588327319,
    "y": 34.056490663914076
   },
   "score": 100,
   "attributes": {
    "Loc_name": "USA.PointAddress",
    "Score": 100,
    "Match_addr": "380 New York St, Redlands, California, 92373",
    "Addr_type": "PointAddress",
    "Type": "",
    "PlaceName": "",
    "Place_addr": "",
    "Phone": "",
    "URL": "",
    "Rank": "",
    "AddBldg": "",
    "AddNum": "380",
    "AddNumFrom": "",
    "AddNumTo": "",
    "Side": "R",
    "StPreDir": "",
    "StPreType": "",
    "StName": "New York",
    "StType": "St",
    "StDir": "",
    "StAddr": "380 New York St",
    "Nbrhd": "",
    "City": "Redlands",
    "Subregion": "",
    "Region": "California",
    "Postal": "92373",
    "PostalExt": "",
    "Country": "USA",
    "LangCode": "ENG",
    "Distance": 0,
    "X": -117.195667,
    "Y": 34.056491000000001,
    "DisplayX": -117.195311,
    "DisplayY": 34.056109999999997,
    "Xmin": -117.19666700000001,
    "Xmax": -117.194667,
    "Ymin": 34.055491000000004,
    "Ymax": 34.057490999999999
   },
   "extent": {
    "xmin": -117.19666700000001,
    "ymin": 34.055491000000004,
    "xmax": -117.194667,
    "ymax": 34.057490999999999
   }
  },

The following example illustrates how to search for a street intersection. An intersection is where two streets cross each other, and hence an intersection search consists of the intersecting street names plus the containing administrative division or postal code. For example, redlands blvd and new york st 92373 is a valid intersection search, as is redlands blvd & new york st redlands ca.

Note:

The valid intersection connectors can be ascertained by looking up the IntersectionConnectors property from the service info URL: http://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer?f=pjson.

Example: Find a street intersection (redlands blvd & new york st redlands ca)

Single-field request URL

Multifield request URL

JSON response

{
 "spatialReference": {
  "wkid": 4326,
  "latestWkid": 4326
 },
 "candidates": [
  {
   "address": "W Redlands Blvd & New York St, Redlands, California, 92373",
   "location": {
    "x": -117.19570839692426,
    "y": 34.059490820246253
   },
   "score": 96.469999999999999,
   "attributes": {
    "Addr_Type": "StreetInt"
   },
   "extent": {
    "xmin": -117.19570899999999,
    "ymin": 34.059491000000001,
    "xmax": -117.19570899999999,
    "ymax": 34.059491000000001
   }
  },

Search for POIs

In the context of the World Geocoding Service, a POI is a point location that can represent a cultural or geographic landmark, business, or administrative division. For example, you can find amusement parks, museums, schools, restaurants, hotels, gas stations, or other types of businesses or landmarks; geographic features, such as mountains, lakes, rivers, or deserts; or administrative places, such as neighborhoods, cities, states, counties, or countries. The findAddressCandidates operation supports geocoding POIs by name or by type.

Note:

The supported types are listed in this table.

As with street addresses, you can search for POIs with findAddressCandidates using the single field or multifield approach.

Single-field POI search

To search for POIs with a single-field search, use the singleLine parameter. In general, valid singleLine POI search strings can be formatted in variations of two basic structures:

  1. <name or type> <optional connector> <optional zone>
  2. <optional zone> <name or type>

Where

  • <name or type> = A place-name, such as Disneyland, Starbucks, Niagra Falls, or Paris; or a type, such as amusement parks, waterfalls, or coffee shops.
  • <optional zone> = A zone—which can be a city, state or region, country, or any combination thereof—provides a spatial boundary to the search; it can be included to limit matching candidates but is not required.
  • <optional connector> = in, at, or near; this is not required for the search.

Examples of valid singleLine search strings include the following:

Business name searches

  • Starbucks San Diego
  • Starbucks San Diego CA
  • Starbucks San Diego USA
  • Starbucks in San Diego
  • San Diego Starbucks
  • San Diego CA Starbucks
  • San Diego USA Starbucks

Type searches

  • coffee shops San Diego
  • coffee shops San Diego CA
  • coffee shops San Diego USA
  • coffee shops in San Diego CA
  • San Diego coffee shops
  • San Diego CA coffee shops
  • San Diego USA coffee shops

Multifield POI search

When searching for POIs using multifield input, the name or type of the POI must be passed as the value for the address parameter. The zone information can be passed in the neighborhood, city, subregion, region, and countryCode parameters.

Note:

The postal and postalExt parameters are not valid input for POI searches.

General information

It is important to note that instead of providing a zone, you can limit searches to a specific area by using the searchExtent parameter. You can also influence the sorting of match candidates according to their proximity to a location with the location and distance parameters.

As with address searches, the quality of POI search results is dependent on the amount and quality of information in the search string. If you just search for hotels without qualifying information, such as zone, search extent, or location, your results will not be meaningful. Adding supplemental information to the search string—the more specific the better—will result in more accurate and relevant matches.

Note:

There may be instances when searches yield unexpected results. For example, a search for New York pizza, where the expected results are pizzerias in New York City, may instead return a match to a restaurant named New York Pizza in Sacramento, California. This is because exact place-name matches are given higher priority to increase performance. If this occurs, you can obtain the desired results by modifying the search string—in this case, a search for pizza in NYC should yield the expected results.

Note:

The address, phone number, and website URL of a POI can be returned by including outFields=Place_addr,Phone,URL in the request. But not all POIs have address, phone, and URL values associated with them. See Service output for more information about these output fields.

Examples

Example: Find a business name (Starbucks Sydney, AUS)

Single-field request URL

Multifield request URL

JSON response

{
 "spatialReference": {
  "wkid": 4326,
  "latestWkid": 4326
 },
 "candidates": [
  {
   "address": "Starbucks-Westfield Mt Druitt",
   "location": {
    "x": 150.81760570500057,
    "y": -33.765816890999588
   },
   "score": 100,
   "attributes": {
    "type": "Coffee Shop",
    "city": "Sydney",
    "region": "New South Wales"
   },
   "extent": {
    "xmin": 150.81260599999999,
    "ymin": -33.770817999999998,
    "xmax": 150.82260600000001,
    "ymax": -33.760818
   }
  }
 ]
}

Example: Find a business type (hotels Miami, FL)

Single-field request URL

Multifield request URL

JSON response

{
 "spatialReference": {
  "wkid": 4326,
  "latestWkid": 4326
 },
 "candidates": [
  {
   "address": "Miccosukee Resort & Gaming",
   "location": {
    "x": -80.481588296999632,
    "y": 25.763788078000459
   },
   "score": 100,
   "attributes": {
    "type": "Hotel",
    "city": "Miami",
    "region": "Florida"
   },
   "extent": {
    "xmin": -80.486588999999995,
    "ymin": 25.758787999999999,
    "xmax": -80.476589000000004,
    "ymax": 25.768788000000001
   }
  },

Search for administrative place-names

The findAddressCandidates operation supports single-field and multifield searches for administrative place-names. This includes searches for neighborhoods, cities, counties, states, provinces, or countries. If a search for a city name results in multiple matches with the same name, the World Geocoding Service will sort the candidates in order of their relative importance to each other (as indicated by the value of the Rank output field), with priority generally based on population and capital status. For example, there are many cities in the world named London, so a search for London results in several equivalent matches; London, UK, will always be the top candidate since it has the greatest population.

Example: Find a city name (London)

Single-field request URL

Multifield request URL

JSON response

{
 "spatialReference": {
  "wkid": 4326,
  "latestWkid": 4326
 },
 "candidates": [
  {
   "address": "London, England, United Kingdom",
   "location": {
    "x": -0.12573890399954735,
    "y": 51.508528044000457
   },
   "score": 100,
   "attributes": {
    
   },
   "extent": {
    "xmin": -0.15373999999999999,
    "ymin": 51.480528,
    "xmax": -0.097739999999999994,
    "ymax": 51.536527999999997
   }
  },
  {
   "address": "London, Ontario, Canada",
   "location": {
    "x": -81.233039613999665,
    "y": 42.983386547000464
   },
   "score": 100,
   "attributes": {
    
   },
   "extent": {
    "xmin": -81.325040999999999,
    "ymin": 42.891387000000002,
    "xmax": -81.141041000000001,
    "ymax": 43.075386999999999
   }
  },

However, rank alone is not always enough to distinguish between administrative places. Also, you may not necessarily want to find the highest-ranked feature for a particular search. It may be necessary to remove ambiguity by refining searches with additional information. For example, a search for Oxford returns Oxford, UK, as the top candidate based on rank. If you instead want to find the town of Oxford, Alabama, it is necessary to add the state information to the search.

Example: Search for city, state (Oxford, AL)

Single-field request URL

Multifield request URL

JSON response

{
 "spatialReference": {
  "wkid": 4326,
  "latestWkid": 4326
 },
 "candidates": [
  {
   "address": "Oxford, Alabama, United States",
   "location": {
    "x": -85.834956749999662,
    "y": 33.614268443000469
   },
   "score": 100,
   "attributes": {
    
   },
   "extent": {
    "xmin": -85.902957999999998,
    "ymin": 33.546267999999998,
    "xmax": -85.766958000000002,
    "ymax": 33.682268000000001
   }
  },

Search for postal codes

The findAddressCandidates operation supports searches for postal codes and postal code extensions. When searching for postal codes, it is important to note that the same code can be valid in more than one country; for best results, it may be necessary to include additional information with the postal code, such as city or country.

Example: Find a postal code (20002 USA)

Single-field request URL

Multifield request URL

JSON response

{
 "spatialReference": {
  "wkid": 4326,
  "latestWkid": 4326
 },
 "candidates": [
  {
   "address": "20002, Washington, District Of Columbia",
   "location": {
    "x": -76.989170693771712,
    "y": 38.907411026698639
   },
   "score": 100,
   "attributes": {
    "addr_type": "Postal"
   },
   "extent": {
    "xmin": -76.994172000000006,
    "ymin": 38.902411000000001,
    "xmax": -76.984172000000001,
    "ymax": 38.912410999999999
   }
  }
 ]
}

Search for x/y coordinates

The World Geocoding Service supports searches for x/y coordinate pairs. The output is a geometry point with a match address that is the same as the input coordinates. This is different than reverse geocoding, in which input x/y coordinates are resolved to a matching street address; see reverseGeocode for more information.

Note:

The only valid input format for coordinate searches is text=<x-coordinate,y-coordinate>, where the spatial reference of the coordinates is WGS84. The x/y coordinate must be passed as the value for the singleLine or Address field in the request.

Example: Find an x/y coordinate pair (-115.172783,36.114789)

Single-field request URL

Multifield request URL

JSON response

{
 "spatialReference": {
  "wkid": 4326,
  "latestWkid": 4326
 },
 "candidates": [
  {
   "address": "-115.172783 36.114789",
   "location": {
    "x": -115.172783,
    "y": 36.114789000000002
   },
   "score": 100,
   "attributes": {
    "addr_type": "LatLong"
   },
   "extent": {
    "xmin": -115.172783,
    "ymin": 36.114789000000002,
    "xmax": -115.172783,
    "ymax": 36.114789000000002
   }
  }
 ]
}

Specify output fields

The findAddressCandidates operation allows you to specify individual output fields or return all output fields. The outFields parameter is used for this. If you want to return all supported output fields, set outFields=*; if you only want to return the default output fields, then outFields does not need to be passed in the request. If you want to return specific fields, pass the desired field names as comma-separated values, such as outFields=PlaceName,Type,City,Country, which returns the name, feature type, city, and country for a POI search.

See Service output for detailed information about the fields returned by a findAddressCandidates request.

Example: Specify individual outfields for a POI search (PlaceName,Type,City,Country)

Single-field request URL

Multifield request URL

JSON response

{
 "spatialReference": {
  "wkid": 4326,
  "latestWkid": 4326
 },
 "candidates": [
  {
   "address": "Starbucks",
   "location": {
    "x": -97.968418052999652,
    "y": 30.34116889100045
   },
   "score": 100,
   "attributes": {
    "PlaceName": "Starbucks",
    "Type": "Coffee Shop",
    "City": "Austin",
    "Country": "USA"
   },
   "extent": {
    "xmin": -97.973419000000007,
    "ymin": 30.336169000000002,
    "xmax": -97.963419000000002,
    "ymax": 30.346169
   }
  },

Specify the output spatial reference

By default, the World Geocoding Service returns candidate geometry in WGS84 coordinates (decimal degrees). You can specify a different spatial reference for output coordinates by using the outSR parameter. This is necessary if you have a mapping application in which you display geocoding candidates and the map spatial reference is not WGS84. For example, the ArcGIS.com basemaps use a Web Mercator spatial reference, with coordinates in meters. In order to display geocoding candidates correctly in such a map you would need to set outSR=102100, which is the well-known ID (WKID) of the Web Mercator spatial reference.

For a list of valid WKID values, see Projected Coordinate Systems and Geographic Coordinate Systems.

Example: Specify output coordinates in Web Mercator spatial reference (380 new york st redlands ca)

Single-field request URL

Multifield request URL:

JSON response

{
 "spatialReference": {
  "wkid": 102100,
  "latestWkid": 3857
 },
 "candidates": [
  {
   "address": "380 New York St, Redlands, California, 92373",
   "location": {
    "x": -13046161.849304594,
    "y": 4036389.8044578899
   },
   "score": 100,
   "attributes": {
    
   },
   "extent": {
    "xmin": -13046273.293108851,
    "ymin": 4036255.4132860568,
    "xmax": -13046050.654127261,
    "ymax": 4036524.1432637926
   }
  },

Specify the maximum number of candidates

The maxLocations parameter allows you to specify the maximum number of candidates to be returned by a search, up to the maximum number of candidates allowed by the World Geocoding Service. By default, the service allows up to 20 candidates to be returned for address searches and 50 for POI searches. As an example, if you set maxLocations=10, findAddressCandidates will return the top 10 candidates for the search, regardless of whether the search matches to an address or a POI. If no value is specified for maxLocations, findAddressCandidates returns all matching candidates.

Example: Specify the maximum number of candidates for a POI search (Starbucks in Paris)

Single-field request URL

Multifield request URL

JSON response

{
 "spatialReference": {
  "wkid": 4326,
  "latestWkid": 4326
 },
 "candidates": [
  {
   "address": "Starbucks",
   "location": {
    "x": 2.2792886790004445,
    "y": 48.856688363000501
   },
   "score": 100,
   "attributes": {
    "PlaceName": "Starbucks",
    "City": "Paris",
    "Country": "FRA"
   },
   "extent": {
    "xmin": 2.274289,
    "ymin": 48.851688000000003,
    "xmax": 2.2842889999999998,
    "ymax": 48.861688000000001
   }
  },
  {
   "address": "Starbucks",
   "location": {
    "x": 2.2839457660004427,
    "y": 48.869138758000474
   },
   "score": 100,
   "attributes": {
    "PlaceName": "Starbucks",
    "City": "Paris",
    "Country": "FRA"
   },
   "extent": {
    "xmin": 2.2789459999999999,
    "ymin": 48.864139000000002,
    "xmax": 2.2889460000000001,
    "ymax": 48.874139
   }
  }
 ]
}

Search within an extent

The findAddressCandidates operation allows spatial filtering of search results by using the searchExtent parameter. If you want to confine a search to a localized area, something that is especially useful in a mobile application, you can define a bounding rectangle to search within. No candidates outside of the rectangle are returned. Bounding rectangle coordinates can be entered as a simple comma-separated string in the format <lower left corner>,<upper right corner>. If the simple format is used, the coordinates must be in the default spatial reference of the geocode service, which is WGS84. The searchExtent parameter can be used with all supported search types (street address, POI, admin place, postal code).

The example URL below illustrates how to find McDonald's in downtown San Diego using the searchExtent format.

Example: Find POIs using searchExtent with default spatial reference (McDonald's)

Single-field request URL

Multifield request URL

JSON response

{
 "spatialReference": {
  "wkid": 4326,
  "latestWkid": 4326
 },
 "candidates": [
  {
   "address": "McDonald's",
   "location": {
    "x": -117.16107793699967,
    "y": 32.714496787000485
   },
   "score": 100,
   "attributes": {
    "city": "San Diego",
    "type": "Burgers"
   },
   "extent": {
    "xmin": -117.166079,
    "ymin": 32.709496999999999,
    "xmax": -117.15607900000001,
    "ymax": 32.719496999999997
   }
  },

You can specify a spatial reference for the searchExtent, which is necessary if your map uses a different spatial reference than the geocode service. For example, the default ArcGIS.com basemaps utilize a Web Mercator spatial reference (WKID = 102100), with coordinates in meters. The searchExtent must be passed as a JSON envelope object if the coordinates are in a spatial reference other than WGS84. The following request URL uses the previous example of McDonald's in downtown San Diego, but specifies the bounding rectangle with Web Mercator coordinates.

Note:

Note that, in this example, the outSR property is set to 102100, so the output coordinates are also in Web Mercator coordinates. If outSR was left blank, the coordinates would be returned in the WGS84 spatial reference.

For a list of supported spatial references and their WKID values, see Projected Coordinate Systems and Geographic Coordinate Systems.

Example: Find POIs using searchExtent with Web Mercator spatial reference (McDonald's)

Single-field request URL

Multifield request URL

JSON response

{
 "spatialReference": {
  "wkid": 102100,
  "latestWkid": 3857
 },
 "candidates": [
  {
   "address": "McDonald's",
   "location": {
    "x": -13042311.536737842,
    "y": 3857469.2138471175
   },
   "score": 100,
   "attributes": {
    "City": "San Diego",
    "Type": "Burgers"
   },
   "extent": {
    "xmin": -13042868.252524463,
    "ymin": 3856807.7266816632,
    "xmax": -13041755.057616532,
    "ymax": 3858130.7944575814
   }
  },

Requests that include searchExtent can also include zone information (that is, city, state, and country). If the extent defined for searchExtent is large enough to encompass multiple cities, it may be necessary to include the city name in the search to achieve optimal results. For example, if the searchExtent covers the Dallas-Fort Worth metropolitan region, and you search for Starbucks, there could be matches returned in Dallas or Fort Worth or any of their suburbs. If you specifically want to find Starbucks in Garland, for example, this needs to be specified in the search.

Example: Find POIs using searchExtent and zone (Starbucks garland)

Single-field request URL

Multifield request URL

JSON response

{
 "spatialReference": {
  "wkid": 4326,
  "latestWkid": 4326
 },
 "candidates": [
  {
   "address": "Starbucks",
   "location": {
    "x": -96.667147024999679,
    "y": 32.959657532000449
   },
   "score": 100,
   "attributes": {
    "type": "Coffee Shop",
    "city": "Garland",
    "region": "Texas"
   },
   "extent": {
    "xmin": -96.672148000000007,
    "ymin": 32.954658000000002,
    "xmax": -96.662148000000002,
    "ymax": 32.964658
   }
  },

You can also search for street addresses within an extent. When the searchExtent parameter is defined for an address search, city and postal code can be omitted from the search and valid matches can still be found. However, if the searchExtent is large, it is possible for a street address to occur multiple times within the extent, and it may be necessary to refine the search by including city, state, postal code, or other distinguishing information. Additionally, if the search includes a city or postal code that is outside the searchExtent, no matches will be returned. See the following example, which illustrates finding a street address using searchExtent.

Example: Find a street address using searchExtent (380 New York St)

Single-field request URL

Multifield request URL

JSON response

{
 "spatialReference": {
  "wkid": 4326,
  "latestWkid": 4326
 },
 "candidates": [
  {
   "address": "380 New York St, Redlands, California, 92373",
   "location": {
    "x": -117.19566588327319,
    "y": 34.056490200763221
   },
   "score": 100,
   "attributes": {
    
   },
   "extent": {
    "xmin": -117.19666700000001,
    "ymin": 34.055489999999999,
    "xmax": -117.194667,
    "ymax": 34.057490000000001
   }
  },

Proximity searches

Geocoding results are typically sorted according to their relevance to the search and their relative importance. However, with some applications, especially mobile apps, users are more concerned with finding features closest to their current location. For this reason, the findAddressCandidates operation supports prioritization of candidates based on their distance from a specified point. By passing in the location and distance parameters, you can define a circular area of influence for your searches. The location parameter represents the center point of the area, and the distance parameter defines the radius in meters. The purpose of this area is to boost the rank of results closest to the specified location so they show up higher in the list of candidates. Results that are within the area receive a greater boost than those outside the area.

It is important to note that proximity search does not filter results that are outside of the location and distance area—it is intended to influence the sort order of results so the most locationally relevant candidates are returned first. For instance, if your location is in Las Vegas, distance=3000, and you search for Golden Nugget, the first candidate is Golden Nugget in Las Vegas. The second is Golden Nugget in Atlantic City, New Jersey. So even though Golden Nugget in Atlantic City is much farther away than the 3,000-meter search distance, it is still returned because it is the second most relevant (closest) candidate. In general, the number of candidates returned by a proximity search is only limited by the maxLocations parameter.

Example: Find a place-name using a proximity search (Golden Nugget)

Single-field request URL

Multifield request URL

JSON response

{
 "spatialReference": {
  "wkid": 4326,
  "latestWkid": 4326
 },
 "candidates": [
  {
   "address": "Golden Nugget",
   "location": {
    "x": -115.1443163999997,
    "y": 36.170797582000489
   },
   "score": 100,
   "attributes": {
    "City": "Las Vegas",
    "Region": "Nevada",
    "Country": "USA"
   },
   "extent": {
    "xmin": -115.149317,
    "ymin": 36.165798000000002,
    "xmax": -115.13931700000001,
    "ymax": 36.175798
   }
  },
  {
   "address": "Golden Nugget",
   "location": {
    "x": -88.860807742999668,
    "y": 30.392297854000446
   },
   "score": 100,
   "attributes": {
    "City": "Biloxi",
    "Region": "Mississippi",
    "Country": "USA"
   },
   "extent": {
    "xmin": -88.865808999999999,
    "ymin": 30.387298000000001,
    "xmax": -88.855808999999994,
    "ymax": 30.397297999999999
   }
  },

If you only want to return candidates within a specific area, and sort the candidates according to their proximity to a location, then you need to define a search extent by passing the searchExtent parameter in the request along with the location and distance parameters. Consider the Golden Nugget example again. If your location is in Las Vegas and you want to confine your search results to places named Golden Nugget that are within the map extent, you would need to construct a request with the following parameters:

  • singleLine (or address): Golden Nugget
  • location: -115.144989,36.167361
  • distance: 4000
  • searchExtent: -115.161912,36.158764,-115.126925,36.179793

The request URL would be similar to the one below. See Searching within an extent for more information about the searchExtent parameter.

Example: Find a place-name using both proximity and searchExtent (Golden Nugget)

Single-field request URL

Multifield request URL

JSON response

{
 "spatialReference": {
  "wkid": 4326,
  "latestWkid": 4326
 },
 "candidates": [
  {
   "address": "Golden Nugget",
   "location": {
    "x": -115.1443163999997,
    "y": 36.170797582000489
   },
   "score": 100,
   "attributes": {
    "City": "Las Vegas",
    "Region": "Nevada",
    "Country": "USA"
   },
   "extent": {
    "xmin": -115.149317,
    "ymin": 36.165798000000002,
    "xmax": -115.13931700000001,
    "ymax": 36.175798
   }
  }
 ]
}

Different logic is applied when the search text matches to many candidates, as opposed to a few. When you search for something like Starbucks or McDonald's, for which there are potentially thousands of results, the search does not extend indefinitely beyond the distance value if exact matches are found within the distance. The results are confined to a slightly larger region than the area defined by the distance value. It is assumed that a user searching for a place like Starbucks only wants to know where the closest Starbucks is and is not interested in finding Starbucks in another city. As an example, if your location is in Fayetteville, North Carolina, and you want to find Starbucks within a 10,000-meter distance with maxLocations=20, five Starbucks are returned. Even though there are many more Starbucks in North Carolina, only the Starbucks nearest to the location are returned. If no exact matches are found within this region, the search is extended globally to find the most relevant match.

Example: Find POI using proximity search (Starbucks)

Single-field request URL

Multifield request URL:

JSON response

{
 "spatialReference": {
  "wkid": 4326,
  "latestWkid": 4326
 },
 "candidates": [
  {
   "address": "Starbucks",
   "location": {
    "x": -78.924658954999643,
    "y": 35.045519437000451
   },
   "score": 100,
   "attributes": {
    "Type": "Coffee Shop",
    "City": "Fayetteville",
    "Region": "North Carolina"
   },
   "extent": {
    "xmin": -78.929659999999998,
    "ymin": 35.040519000000003,
    "xmax": -78.919659999999993,
    "ymax": 35.050519000000001
   }
  },
  {
   "address": "Starbucks",
   "location": {
    "x": -78.935089029999631,
    "y": 35.03874753800045
   },
   "score": 100,
   "attributes": {
    "Type": "Coffee Shop",
    "City": "Fayetteville",
    "Region": "North Carolina"
   },
   "extent": {
    "xmin": -78.940089999999998,
    "ymin": 35.033748000000003,
    "xmax": -78.930090000000007,
    "ymax": 35.043748000000001
   }
  },

Category filtering

The findAddressCandidates operation supports filtering searches by category values, which represent address and place types. By including the category parameter in a findAddressCandidates request, you can avoid false positive matches to unexpected place and address types due to ambiguous searches.

Note:

The category parameter is only functional when used with the singleLine parameter. It does not work with the multifield parameters, specifically, the address, neighborhood, city, region, subregion, countryCode, and postal parameters.

For example, a user may search for Mammoth, expecting the service to match to Mammoth Mountain ski resort. However, there are many places in the world named Mammoth, so the search returns several cities named Mammoth.

Example: Search for Mammoth without a category

Request URL

JSON response

{
 "spatialReference": {
  "wkid": 4326,
  "latestWkid": 4326
 },
 "candidates": [
  {
   "address": "Mammoth, Arizona, United States",
   "location": {
    "x": -110.64064804599968,
    "y": 32.722569071000464
   },
   "score": 100,
   "attributes": {
    "PlaceName": "Mammoth",
    "Type": "City",
    "Place_Addr": "",
    "City": "",
    "Region": "Arizona"
   },
   "extent": {
    "xmin": -110.653649,
    "ymin": 32.709569000000002,
    "xmax": -110.62764900000001,
    "ymax": 32.735568999999998
   }
  },
  {
   "address": "Mammoth, California, United States",
   "location": {
    "x": -121.35498927799972,
    "y": 41.730436732000499
   },
   "score": 100,
   "attributes": {
    "PlaceName": "Mammoth",
    "Type": "City",
    "Place_Addr": "",
    "City": "",
    "Region": "California"
   },
   "extent": {
    "xmin": -121.37499,
    "ymin": 41.710436999999999,
    "xmax": -121.33499,
    "ymax": 41.750436999999998
   }
  },

The solution for this case is to pass the category parameter in the request. By including category=Ski Resort in the request, all places that are not ski resorts are bypassed by the search, and only ski resorts whose names begin with Mammoth are returned.

Example: Search for Mammoth with category=Ski Resort

Request URL

JSON response

{
 "spatialReference": {
  "wkid": 4326,
  "latestWkid": 4326
 },
 "candidates": [
  {
   "address": "Mammoth Mountain",
   "location": {
    "x": -119.03726744799968,
    "y": 37.650986233000481
   },
   "score": 97.75,
   "attributes": {
    "PlaceName": "Mammoth Mountain",
    "Type": "Ski Resort",
    "Place_Addr": "1 Minaret Rd, Mammoth Lakes, California",
    "City": "Mammoth Lakes",
    "Region": "California"
   },
   "extent": {
    "xmin": -119.062268,
    "ymin": 37.625985999999997,
    "xmax": -119.01226800000001,
    "ymax": 37.675986000000002
   }
  },

See Category filtering for complete details.