suggest

The ArcGIS Geocoding service includes a method that allows character-by-character autocomplete suggestions to be generated for user input in a client application. This capability facilitates the interactive search user experience by reducing the number of characters that need to be typed before a suggested match is obtained. The idea is that a client application can provide a list of suggestions that is updated with each character entered by a user until the place they are looking for is returned in the list.

For example, if a user wants to find 27488 Stanford Ave, Bowden, North Dakota, they need to type only 27488 stanfo, and the address they are looking for is returned as an item in the suggestion list. Or if they are looking for a Disney park but don't know the proper name or address, they can find it using suggest.

Most of the search types that can be made with the findAddressCandidates operation can also be made with suggestions. Specifically, the following types of searches are supported by the suggest operation:

Street addresses (including street name)
- 27488 Stanford Ave, Bowden, North Dakota
- 380 New York St, Redlands, CA 92373
Street intersections
- New York St and W Redlands Blvd, Redlands, CA
- Jacques Veltmanstraat & Pieter Calandlaan, Amsterdam, NLD
Points of interest (POI) by name
- Disneyland
- Starbucks
- Mount Everest
POI by type
- amusement park
- coffee
- gas station
Administrative place-names, such as city, county, state, province, or country names
- Seattle
- State of Mahārāshtra
- Liechtenstein
Postal codes
- 92591
- TW9 1DN

Additionally, the suggest operation uses the same proximity algorithm as the findAddressCandidates operation.

Access the services

To access the geocoding service you need the following:

An ArcGIS Location Platform account or ArcGIS Online account.
An access token (API key or OAuth 2.0) with the appropriate privilege.

Note:

If you have an ArcGIS Online account the premium:user:geocode privilege is required for suggest requests.

If you have an ArcGIS Location Platform account the premium:user:geocode:temporary privilege is required for suggest requests.

Tip:

To learn how to get an API key or to use OAuth 2.0, see Security and authentication in the Mapping APIs and location services guide.

Request URL


https://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer/suggest?<PARAMETERS>

For more information about constructing a request, including how to choose which endpoint to use, refer to the Geocoding service overview.

Note:

URL encoding is enforced by ArcGIS Online and the ArcGIS Geocoding service. Ensure the request URLs sent to the service are properly encoded and patterned after the examples in this topic.

Note:

The REST request URL must include HTTPS. Requests with HTTP are not supported.

Request parameters

The parameters for suggest are listed in the subsections that follow, categorized by required and optional parameters.

Required parameters

text

The input text entered by a user, which is used by the suggest operation to generate a list of possible matches.

            Example
            text=starbu

f

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

            Example
            f=pjson

Optional parameters

location

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 in which a user wants to search for places in the vicinity of their current GPS location, or in mapping applications in which 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 WGS84; otherwise, the spatial reference of the point coordinates can be defined in the JSON object.

Note:

The distance parameter is deprecated and no longer recognized by the ArcGIS Geocoding service.

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

searchExtent

A set of bounding box coordinates that limit the search area for suggestions 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 ArcGIS Geocoding service; otherwise, the spatial reference of the coordinates is assumed to be the same as that of the ArcGIS 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
    }
}

maxSuggestions

The maximum number of suggestions returned by a suggest response, up to the maximum number allowed by the service. Currently, the ArcGIS Geocoding service allows up to 15 suggestions to be returned. If maxSuggestions is not included in the suggest request, the default value is 5.

            Example
            maxSuggestions=10

countryCode

Limits the returned suggestions to values in a particular country. Valid two- and three-character country code values for each country are available in Data coverage.

Note:

When the countryCode parameter is specified in a suggest request, the corresponding findAddressCandidates request must also include the countryCode parameter with the same value.

            Example
            countryCode=USA

sourceCountry

Similar to countryCode, the sourceCountry parameter limits the suggestions to the specified country or countries. For example, if sourceCountry=USA is included in the request, it is assumed that the address is in the United States, so only matching U.S. addresses are returned. Using this parameter prevents potential unexpected results in other countries for ambiguous searches.

Acceptable values include two- and three-character country codes. You can specify multiple country codes to limit results to more than one country.

A list of supported countries and codes is available in Data coverage.

Note:

If both countryCode and sourceCountry are included in a suggest 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.

            Example: Single country
            sourceCountry=USA

            Example: Multiple countries
            sourceCountry=FRA,DEU,ESP

preferredLabelValues

The preferredLabelValues parameter allows simple configuration of suggestion labels returned in a response from the ArcGIS Geocoding service by specifying which address component values should be included in the label. If the parameter is blank or excluded from a request, default address formats are 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 where the address is located.

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; the postal city is the name assigned to the postal code of the address.

For addresses in the United States, the ArcGIS Geocoding service includes the primary postal city in suggestion labels by default. As an example, postal code 45420 in Ohio has the primary postal city value Dayton. Addresses in the neighboring city of Kettering are also assigned this postal code. It means that the default suggestion label for addresses with postal code 45420—even those within the city of Kettering—will include Dayton as the city. To illustrate, if a user types 2109 E Dorothy Ln, OH, 45420, the default suggestion returned in the response is 2109 E Dorothy Ln, Dayton, OH, 45420, even though the address is within the Kettering city limits.

Some organizations may prefer to include the local city name in the response instead of the postal city. The preferredLabelValues parameter can be used for this purpose. For the previous example, if preferredLabelValues=localCity is included in the request, the returned suggestion is 2109 E Dorothy Ln, Kettering, Ohio, 45420. As you can see, Kettering is now included in the label instead of Dayton.

See the following table for supported parameter values.


Parameter value	Description
postalCity	Include the primary postal city value in suggestions. This is the primary name assigned to the postal code of the address.
localCity	Include the primary local city name in suggestions. This is the name of the city boundary that the address is within, and may be different than the postal city.

Additional details:

A request can only include one value for the parameter. In other words, a request with preferredLabelValues=matchedCity,postalCity is invalid.
The preferredLabelValues parameter affects the suggestion labels initially returned as you begin typing an address, before any city information is entered. As the city name is entered, the returned suggestion will include the city that matches the input even if it is different than the name corresponding to the preferredLabelValues parameter passed in the request. The idea is for suggestions to reflect the user input as much as possible, and this takes precedence over the preferredLabelValues parameter.

            Example: Include local city name in suggestion
            preferredLabelValues=localCity

Note:

The functionality of the preferredLabelValues parameter is limited by the data sources used to produce the ArcGIS Geocoding service. Not all addresses have postal city and local city values assigned to them. 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.

returnCollections

The returnCollections parameter can be used to prevent collections from being returned in suggest responses. The default value is true, which means that collections are included in suggest responses by default.

            Example: Disable collections in suggest responses
            returnCollections=false

Suggest output

The response returned by a suggest request is composed of an array of suggestions; each suggestion contains the suggestion text, a magicKey value, and the isCollection flag. A maximum of five suggestions are included in the suggestions array.

Output properties

text

The suggestion text can be used in a client application to populate a list of suggestions as a user enters characters in a search text box.

It can also be included with magicKey in a findAddressCandidates request to quickly retrieve a geosearch candidate.

            Example
            "text": Starbucks, 1265 Alabama St, Redlands, California

magicKey

An ID attribute value that, along with the text attribute, links a suggestion to an address or place.

After you make a suggest request, the typical workflow is to pass the text (as the SingleLine parameter value) and magicKey values in a findAddressCandidates request, which retrieves the result in less time than passing in a SingleLine value by itself.

            Example
            "magicKey": JS91CYhQDS5vDPhvSMyGZby0YFbaUDoaM5bHMoFF

Note:

The magicKey value is not permanent across versions of the ArcGIS Geocoding service and should not be stored by a client application. It is only intended to be used in geosearch operations as input for the findAddressCandidates magicKey parameter.

isCollection

A Boolean parameter that indicates whether the suggestion item represents a collection of places, as opposed to a specific place.

If isCollection = true for a suggestion item, it means the item represents a search term for a common place-name or POI category; suggestion items such as Starbucks, McDonald's, Gas Station, and Airport will have isCollection = true.

If isCollection = false, the suggestion item represents a specific place-name or address; suggestion items such as Disneyland or 380 New York St, Redlands, CA will have isCollection = false.

This flag can be used by application developers to apply different behavior to cases in which isCollection is true versus cases in which isCollection is false.

            Example (for POI categories and common place-names)
            "isCollection": true

            Example (for street addresses, postal codes, admin places, and POI's)
            "isCollection": false

Working with suggestions

In broad terms, the suggestions engine compares tokens in the input text with indexed terms for each address and place in the service, and returns the closest matches. The input parameters included in the request affect the results. For instance, including the location parameter in the request influences the results to favor places near the defined location.

The suggestions functionality is accessed through the following URL:

https://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer/suggest?<parameters>

In this URL, <parameters> can be any of the request parameters.

The suggest method is intended to be used by a client application to provide a list of suggested matches as a user enters text in a search box. With each character that the user enters in the search box, the list of suggestions will update, until one of the suggestions matches what the user is looking for.

When the user selects a suggestion, the text and magicKey values for that suggestion can be passed with a findAddressCandidates request as the values for the SingleLine and magicKey input parameters, respectively:

https://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer/findAddressCandidates?SingleLine="<text1>"&magicKey="<magicKey1>"&f=json

Note:

The same parameters and values used in the suggest request should also be included in the corresponding findAddressCandidates request. This includes location, searchExtent, category, and countryCode.

Using proximity with suggestions

As with the findAddressCandidates method, suggest allows location values to be passed with the request to prioritize places that are closest to the specified location.

By using the location parameter, you can define an area of influence for your searches. The location value represents the center point of the area, which spans a radius of 50,000 meters. Features closest to the input location show up higher in the list of suggestions. Results that are within the area of influence receive a greater boost than those outside the area.

To see how the use of proximity influences suggest results, consider the following example. If the map location is in Las Vegas, and a user types Treas in a search box, the returned suggestions are all related to Treasure Island Hotel and Casino in Las Vegas.

Example

Get suggestions using location

Request URL

https://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer/suggest?text=treas&location=-115.172783,36.114789&f=pjson&token=<ACCESS_TOKEN>

https://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer/suggest?text=treas&location=-115.172783%2C36.114789&f=pjson&token=<ACCESS_TOKEN>

JSON response

{
 "suggestions": [
  {
   "text": "Treasure Island, 3300 Las Vegas Blvd S, Las Vegas, NV, 89109, USA",
   "magicKey": "dHA9MCN0dj01MzQ0YjFhMiNsb2M9MTAxOTYyNjYjbG5nPTQzI3BsPTEwMTczOTQ5I2ZhPTMyNzY4MCNsYnM9MTQ6NzAxNjg2ODcjbG49V29ybGQ=",
   "isCollection": false
  },
  {
   "text": "Treasure Island Wedding Chapels, 3300 Las Vegas Blvd S, Las Vegas, NV, 89109, USA",
   "magicKey": "dHA9MCN0dj01MzQ0YjFhMiNsb2M9MTAyNDA1MjQjbG5nPTQzI3BsPTEwMjIwMTY1I2ZhPTIwOTcxNTIjbGJzPTE0OjcwMTY4ODY2I2xuPVdvcmxk",
   "isCollection": false
  },
  {
   "text": "Treasure Island Pool, 3300 Las Vegas Blvd S, Las Vegas, NV, 89109, USA",
   "magicKey": "dHA9MCN0dj01MzQ0YjFhMiNsb2M9MTAyNDA1MjQjbG5nPTQzI3BsPTEwMjIwMTYzI2ZhPTIwOTcxNTIjbGJzPTE0OjcwMTY4ODE5I2xuPVdvcmxk",
   "isCollection": false
  },
  {
   "text": "Treasure Island Wedding Chapel, 3300 Las Vegas Blvd S, Las Vegas, NV, 89109, USA",
   "magicKey": "dHA9MCN0dj01MzQ0YjFhMiNsb2M9MTAxOTYyNjgjbG5nPTQzI3BsPTEwMTc0MjAyI2ZhPTEzMTA3MiNsYnM9MTQ6NzAxNjg4NjUjbG49V29ybGQ=",
   "isCollection": false
  },
  {
   "text": "Treasure Island At The Mirage, 3300 Las Vegas Blvd S, Las Vegas, NV, 89109, USA",
   "magicKey": "dHA9MCN0dj01MzQ0YjFhMiNsb2M9MTAyNDA1MjQjbG5nPTQzI3BsPTEwMjE5NjMzI2ZhPTIwOTcxNTIjbGJzPTE0OjcwMTY4NzAyI2xuPVdvcmxk",
   "isCollection": false
  }
 ]
}

It is important to note that proximity search does not filter out results that are far from the input location—it is intended to influence the sort order of results so the most locationally relevant matches are returned first. For instance, if your location is in Seattle and you type Mount Ver, the first suggestion in the list is Mount Vernon, Washington, United States. The second is Mount Vernon, Westchester County, New York, United States. So even though Mount Vernon in New York is far from Seattle, it is still returned because it is the second most relevant candidate based on its distance from the location and its rank. To limit suggestions to a specific area, use the searchExtent parameter.

If the user enters the same text in the search box but is zoomed out to an extent for which proximity search is not used, and the location parameter is not passed in the suggest request, only admin places whose names begin with Treas are returned in the suggestions list.

Example

Get suggestions without location

Request URL

https://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer/suggest?text=treas&f=pjson&token=<ACCESS_TOKEN>

https://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer/suggest?text=treas&f=pjson&token=<ACCESS_TOKEN>

JSON response

{
 "suggestions": [
  {
   "text": "Treasure County, MT, USA",
   "magicKey": "dHA9MCN0dj01MzQ0YjFhMiNsb2M9OTg5ODQ1OSNsbmc9NDMjcGw9OTg5OTQ0MiNsYnM9MTQ6NzAxNjgzNDkjbG49V29ybGQ=",
   "isCollection": false
  },
  {
   "text": "Treas, Banteay Meanchey, KHM",
   "magicKey": "dHA9MCN0dj01MzQ0YjFhMiNsb2M9NTgzMTk2MDUjbG5nPTQzI3BsPTc3MTYzMjQ1I2xicz0xNDo3MDE2NzY4OSNsbj1Xb3JsZA==",
   "isCollection": false
  },
  {
   "text": "Treasure Island, FL, USA",
   "magicKey": "dHA9NCN0dj01MzQ0YjFhMiNubT1UcmVhc3VyZSBJc2xhbmQsIEZMLCBVU0EjbG5nPTQzI2xuPVdvcmxk",
   "isCollection": false
  },
  {
   "text": "Treascon, Portarlington, Laois, IRL",
   "magicKey": "dHA9MCN0dj01MzQ0YjFhMiNsb2M9NTY3OTUzMjYjbG5nPTQzI3BsPTczODA4NDkxI2xicz0xNDo3MDE2NzcyMSNsbj1Xb3JsZA==",
   "isCollection": false
  },
  {
   "text": "Treascon, Portarlington, Offaly, IRL",
   "magicKey": "dHA9MCN0dj01MzQ0YjFhMiNsb2M9NTY4NTEyNjMjbG5nPTQzI3BsPTczODQzNTk1I2xicz0xNDo3MDE2NzcyMSNsbj1Xb3JsZA==",
   "isCollection": false
  }
 ]
}

Limiting suggestions to a specified area

Unlike the location parameter, the searchExtent parameter filters out suggestions for places that are outside of the specified area. To confine suggestions to a localized area, such as the current map extent, you can use searchExtent to define a bounding rectangle to search within. Bounding rectangle coordinates can be entered as a simple comma-separated string in the format <lower left corner>,<upper right corner>. If this simple format is used, the coordinates must be in the default spatial reference of the geocode service, which is WGS84.

To see how searchExtent affects suggestions, consider the following example. Assume that a user of your application has zoomed the map to the extent of Kansas City, Missouri, and enters Main St in the search box. If the map extent is passed as the searchExtent parameter in a suggest request, only suggestions beginning with Main St in Kansas City are returned.

Example

Get suggestions using searchExtent

Request URL

https://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer/suggest?text=main st&category=&searchExtent=-94.602026,39.083630,-94.570151,39.109774&location=&f=pjson&token=<ACCESS_TOKEN>

https://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer/suggest?text=main%20st&category=&searchExtent=-94.602026%2C39.083630%2C-94.570151%2C39.109774&location=&f=pjson&token=<ACCESS_TOKEN>

JSON response

{
 "suggestions": [
  {
   "text": "Main St, Kansas City, MO, 64108, USA",
   "magicKey": "dHA9MCN0dj01MzQ0YjFhMiNsb2M9OTQxMzUzOCNsbmc9NDMjbGJzPTEwOTo4ODU4ODc0NCNsbj1Xb3JsZA==",
   "isCollection": false
  },
  {
   "text": "Main St, Kansas City, MO, 64106, USA",
   "magicKey": "dHA9NCN0dj01MzQ0YjFhMiNubT1NYWluIFN0LCBLYW5zYXMgQ2l0eSwgTU8sIDY0MTA2LCBVU0Ejc3o9LTk0LjU4NjA4ODQ5OTk5OTk4ODozOS4wOTY3MDIwMDAwMDAwMDE7LTk0LjYwMjAyNTk5OTk5OTk5NTozOS4wODM2Mjk5OTk5OTk5OTk6LTk0LjU3MDE1MDk5OTk5OTk5NjozOS4xMDk3NzQwMDAwMDAwMDIjbG5nPTQzI2xuPVdvcmxk",
   "isCollection": false
  },
  {
   "text": "Main St, Kansas City, MO, 64105, USA",
   "magicKey": "dHA9NCN0dj01MzQ0YjFhMiNubT1NYWluIFN0LCBLYW5zYXMgQ2l0eSwgTU8sIDY0MTA1LCBVU0Ejc3o9LTk0LjU4NjA4ODQ5OTk5OTk4ODozOS4wOTY3MDIwMDAwMDAwMDE7LTk0LjYwMjAyNTk5OTk5OTk5NTozOS4wODM2Mjk5OTk5OTk5OTk6LTk0LjU3MDE1MDk5OTk5OTk5NjozOS4xMDk3NzQwMDAwMDAwMDIjbG5nPTQzI2xuPVdvcmxk",
   "isCollection": false
  },
  {
   "text": "Main-Walnut Via, Kansas City, MO, 64108, USA",
   "magicKey": "dHA9MCN0dj01MzQ0YjFhMiNsb2M9OTQxMzU4NCNsbmc9NDMjbGJzPTEwOTo4ODU4NjgxNzswOjY1ODM2NjkwI2xuPVdvcmxk",
   "isCollection": false
  },
  {
   "text": "Main Gift Shop, 2401 Gillham Rd, Kansas City, MO, 64108, USA",
   "magicKey": "dHA9MCN0dj01MzQ0YjFhMiNsb2M9OTYzMDI1OCNsbmc9NDMjcGw9OTcyNTczNCNmYT02NTUzNiNsYnM9MTQ6NDM3NjA0ODU7MDo2NTgzNjY5MCNsbj1Xb3JsZA==",
   "isCollection": false
  }
 ]
}

You can specify a spatial reference for searchExtent, which is necessary if your map uses a different spatial reference than the geocode service. For example, the default ArcGIS.com basemaps use 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 Main St in Kansas City, but specifies the bounding rectangle with Web Mercator coordinates.

Example

Get suggestions using searchExtent with a JSON envelope object

Request URL

https://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer/suggest?text=main st&searchExtent={"xmin":-10531043,"ymin":4733652,"xmax":-10527501,"ymax":4737408,"spatialReference":{"wkid":102100}}&outSR=102100&f=pjson&token=<ACCESS_TOKEN>

https://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer/suggest?text=main%20st&searchExtent=%7B%22xmin%22%3A-10531043%2C%22ymin%22%3A4733652%2C%22xmax%22%3A-10527501%2C%22ymax%22%3A4737408%2C%22spatialReference%22%3A%7B%22wkid%22%3A102100%7D%7D&outSR=102100&f=pjson&token=<ACCESS_TOKEN>

JSON response

{
 "suggestions": [
  {
   "text": "Main St, Kansas City, MO, 64108, USA",
   "magicKey": "dHA9MCN0dj01MzQ0YjFhMiNsb2M9OTQxMzUzOCNsbmc9NDMjbGJzPTEwOTo4ODU4ODc0NCNsbj1Xb3JsZA==",
   "isCollection": false
  },
  {
   "text": "Main St, Kansas City, MO, 64106, USA",
   "magicKey": "dHA9NCN0dj01MzQ0YjFhMiNubT1NYWluIFN0LCBLYW5zYXMgQ2l0eSwgTU8sIDY0MTA2LCBVU0Ejc3o9LTk0LjU4NjA4ODQ5OTk5OTk4ODozOS4wOTY3MDIwMDAwMDAwMDE7LTk0LjYwMjAyNTk5OTk5OTk5NTozOS4wODM2Mjk5OTk5OTk5OTk6LTk0LjU3MDE1MDk5OTk5OTk5NjozOS4xMDk3NzQwMDAwMDAwMDIjbG5nPTQzI2xuPVdvcmxk",
   "isCollection": false
  },
  {
   "text": "Main St, Kansas City, MO, 64105, USA",
   "magicKey": "dHA9NCN0dj01MzQ0YjFhMiNubT1NYWluIFN0LCBLYW5zYXMgQ2l0eSwgTU8sIDY0MTA1LCBVU0Ejc3o9LTk0LjU4NjA4ODQ5OTk5OTk4ODozOS4wOTY3MDIwMDAwMDAwMDE7LTk0LjYwMjAyNTk5OTk5OTk5NTozOS4wODM2Mjk5OTk5OTk5OTk6LTk0LjU3MDE1MDk5OTk5OTk5NjozOS4xMDk3NzQwMDAwMDAwMDIjbG5nPTQzI2xuPVdvcmxk",
   "isCollection": false
  },
  {
   "text": "Main-Walnut Via, Kansas City, MO, 64108, USA",
   "magicKey": "dHA9MCN0dj01MzQ0YjFhMiNsb2M9OTQxMzU4NCNsbmc9NDMjbGJzPTEwOTo4ODU4NjgxNzswOjY1ODM2NjkwI2xuPVdvcmxk",
   "isCollection": false
  },
  {
   "text": "Main Gift Shop, 2401 Gillham Rd, Kansas City, MO, 64108, USA",
   "magicKey": "dHA9MCN0dj01MzQ0YjFhMiNsb2M9OTYzMDI1OCNsbmc9NDMjcGw9OTcyNTczNCNmYT02NTUzNiNsYnM9MTQ6NDM3NjA0ODU7MDo2NTgzNjY5MCNsbj1Xb3JsZA==",
   "isCollection": false
  }
 ]
}

Utilizing the isCollection property

The isCollection property is a Boolean flag that indicates the type of suggestion item returned by a suggest request. When isCollection = true, the suggestion item represents a general search term for a POI type or a common place-name corresponding to multiple locations, such as Hotel, Clothing Store, or McDonald's. When isCollection = false, the suggestion item represents the name of a discrete address or place, such as Paris, France, Disneyland, or 380 New York St, Redlands, CA.

In general, when a suggestion text and magicKey pair for which isCollection = true is sent in a findAddressCandidates request, multiple candidates are returned with the same name (Starbucks) or category (Coffee Shop); typically, all of the candidates are equally relevant to the user's search. When isCollection = false, there may be one or more candidates returned; if there are multiple candidates, the first one is usually the best match and the most relevant to the search.

Consider the following example. A user of a mapping application is zoomed in to the extent of Sydney, Australia, and types coffee in a search box.

Example

Using the isCollection property

Request URL

https://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer/suggest?text=coffee&location=151.229129,-33.879741&f=pjson&token=<ACCESS_TOKEN>

https://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer/suggest?text=coffee&location=151.229129%2C-33.879741&f=pjson&token=<ACCESS_TOKEN>

Suggest JSON response

{
 "suggestions": [
  {
   "text": "Coffee Shop",
   "magicKey": "dHA9MiN0dj01MzQ0YjFhMiNubT1Db2ZmZWUgU2hvcCNzej0xNTEuMjI5MTI5Oi0zMy44Nzk3NDEwMDAwMDAwMDMjY3M9NzAjbG49V29ybGQ=",
   "isCollection": true
  },
  {
   "text": "Coffee Tea & Me, 87C Macleay Street, Elizabeth Bay, Sydney, New South Wales, 2011, AUS",
   "magicKey": "dHA9MCN0dj01MzQ0YjFhMiNsb2M9MzUwMDg1NTUjbG5nPTQzI3BsPTM2NjQ0NjUzI2ZhPTkxNzUwNCNsYnM9MTQ6MTg5MTcxOTYjbG49V29ybGQ=",
   "isCollection": false
  },
  {
   "text": "Coffee Pros, 144-150 Liverpool Street, East Sydney, Sydney, New South Wales, 2010, AUS",
   "magicKey": "dHA9MCN0dj01MzQ0YjFhMiNsb2M9MzUwMDUwMjcjbG5nPTQzI3BsPTM2NjM2NTk3I2ZhPTE1MDczMjgjbGJzPTE0OjE4OTE1NDc1I2xuPVdvcmxk",
   "isCollection": false
  },
  {
   "text": "Coffee Tea & Me, 224 Oxford Street, Bondi Junction, Sydney, New South Wales, 2022, AUS",
   "magicKey": "dHA9MCN0dj01MzQ0YjFhMiNsb2M9MzQ5OTQ0NzQjbG5nPTQzI3BsPTM2NjA2MjAxI2ZhPTM2MDQ0ODAjbGJzPTE0OjE4OTE3MTk2I2xuPVdvcmxk",
   "isCollection": false
  },
  {
   "text": "Coffee In A Cone Food, 481 Crown Street, Surry Hills, Sydney, New South Wales, 2010, AUS",
   "magicKey": "dHA9MCN0dj01MzQ0YjFhMiNsb2M9MzUwNDgwOTMjbG5nPTQzI3BsPTM2NzQ3OTIyI2ZhPTI3NTI1MTIjbGJzPTE0OjE4OTEyOTM3I2xuPVdvcmxk",
   "isCollection": false
  }
 ]
}

In this example, note that isCollection = true for the first suggestion item Coffee Shop. The text and magicKey for this item correspond to a search for places of POI category Coffee Shop within approximately 5,000 meters of a location in Sydney, Australia. The text and magicKey combinations of the rest of the items, for which isCollection = false, represent the names of coffee shops that are within 5,000 meters of the location.

When the text and magicKey combination of the item for which isCollection = true is sent to the ArcGIS Geocoding service in a findAddressCandidates request, with maxLocations = 10, several coffee shops are returned.

Example

Using a suggest result in a findAddressCandidates request when isCollection=true

Request URL

https://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer/findAddressCandidates?singleLine=Coffee Shop&magicKey=dHA9MiN0dj01MzQ0YjFhMiNubT1Db2ZmZWUgU2hvcCNzej0xNTEuMjI5MTI5Oi0zMy44Nzk3NDEwMDAwMDAwMDMjY3M9NzAjbG49V29ybGQ=&maxLocations=10&outFields=Match_addr,Place_addr,Type&f=pjson&token=<ACCESS_TOKEN>

https://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer/findAddressCandidates?singleLine=Coffee%20Shop&magicKey=dHA9MiN0dj01MzQ0YjFhMiNubT1Db2ZmZWUgU2hvcCNzej0xNTEuMjI5MTI5Oi0zMy44Nzk3NDEwMDAwMDAwMDMjY3M9NzAjbG49V29ybGQ=&maxLocations=10&outFields=Match_addr%2CPlace_addr%2CType&f=pjson&token=<ACCESS_TOKEN>

findAddressCandidates JSON response

{
 "spatialReference": {
  "wkid": 4326,
  "latestWkid": 4326
 },
 "candidates": [
  {
   "address": "Scramble & Bean",
   "location": {
    "x": 151.2284146,
    "y": -33.8752326
   },
   "score": 100,
   "attributes": {
    "Match_addr": "Scramble & Bean",
    "Type": "Coffee Shop",
    "Place_addr": "13-19 Waratah Street, Rushcutters Bay, Sydney, New South Wales, 2011"
   },
   "extent": {
    "xmin": 151.2234146,
    "ymin": -33.8802326,
    "xmax": 151.2334146,
    "ymax": -33.8702326
   }
  },
  {
   "address": "Bayswater Bru",
   "location": {
    "x": 151.22344,
    "y": -33.87525
   },
   "score": 100,
   "attributes": {
    "Match_addr": "Bayswater Bru",
    "Type": "Coffee Shop",
    "Place_addr": "17 Bayswater Road, Kings Cross, Sydney, New South Wales, 2011"
   },
   "extent": {
    "xmin": 151.21844,
    "ymin": -33.88025,
    "xmax": 151.22844,
    "ymax": -33.87025
   }
  }

A developer can use the isCollection property to properly handle cases such as this in their application. Specifically, for cases in which isCollection = true, the maxLocations parameter should be included in the corresponding findAddressCandidates request and set to 5 or greater. Often, there are more than 5 or even 10 matches for such cases, so consider implementing pagination in the application to show the user more results. For cases in which isCollection = false, the maxLocations parameter should be set to 1.

It is important to note that if maxLocations=10 had not been explicitly passed in the findAddressCandidates request, up to 50 candidates would have been returned, because the findAddressCandidates operation returns all matching candidates (up to the maximum allowed by the service) in the absence of the maxLocations parameter. Also note that the JSON response shown here has been truncated to preserve space.

If the text and magicKey combination of any of the items for which isCollection = false are passed in a findAddressCandidates request, in most cases only a single candidate is returned.

Example

Using a suggest result in a findAddressCandidates request when isCollection=false

Request URL

https://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer/findAddressCandidates?singleLine=Coffee Tea & Me, 87 Macleay St, Elizabeth Bay, Sydney, New South Wales, 2011, AUS&magicKey=dHA9MCN0dj01MzQ0YjFhMiNsb2M9MzUwMDg1NTUjbG5nPTQzI3BsPTM2NjQ0NjUzI2ZhPTkxNzUwNCNsYnM9MTQ6MTg5MTcxOTYjbG49V29ybGQ=&f=pjson&token=<ACCESS_TOKEN>

https://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer/findAddressCandidates?singleLine=Coffee%20Tea%20%26%20Me%2C%2087%20Macleay%20St%2C%20Elizabeth%20Bay%2C%20Sydney%2C%20New%20South%20Wales%2C%202011%2C%20AUS&magicKey=dHA9MCN0dj01MzQ0YjFhMiNsb2M9MzUwMDg1NTUjbG5nPTQzI3BsPTM2NjQ0NjUzI2ZhPTkxNzUwNCNsYnM9MTQ6MTg5MTcxOTYjbG49V29ybGQ=&f=pjson&token=<ACCESS_TOKEN>

findAddressCandidates JSON response

{
 "spatialReference": {
  "wkid": 4326,
  "latestWkid": 4326
 },
 "candidates": [
  {
   "address": "Coffee Tea & Me",
   "location": {
    "x": 151.2253078,
    "y": -33.8711299
   },
   "score": 100,
   "attributes": {
    
   },
   "extent": {
    "xmin": 151.2203078,
    "ymin": -33.8761299,
    "xmax": 151.2303078,
    "ymax": -33.8661299
   }
  }
 ]
}

Disabling collections

If collections are not needed for your application, you can use the returnCollections parameter to prevent them from being returned in suggest responses. Specifically, if returnCollections=false is included in a suggest request, only suggestion items with isCollection = false are returned in the response. Collections are returned by default for suggest, so returnCollections=false must be included in the suggest request to disable this feature.

Example

Disable collections by using returnCollections=false with input text w and location in Washington, DC (location=-77.043,38.91)

Request URL

https://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer/suggest?text=w&location=-77.043,38.91&returnCollections=false&f=pjson&token=<ACCESS_TOKEN>

https://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer/suggest?text=w&location=-77.043,38.91&returnCollections=false&f=pjson&token=<ACCESS_TOKEN>

JSON response

{
 "suggestions": [
  {
   "text": "Washington Monument, 2 15th St NW, Washington, DC, 20006, USA",
   "magicKey": "dHA9MCN0dj01MzQ0YjFhMiNsb2M9Mjk5MDYzMCNsbmc9NDMjcGw9MzY2MTIxOSNmYT02NTUzNiNsYnM9MTQ6NzM2OTU4ODEjbG49V29ybGQ=",
   "isCollection": false
  },
  {
   "text": "Washington, DC, USA",
   "magicKey": "dHA9MCN0dj01MzQ0YjFhMiNsb2M9Mjk4NDYwMCNsbmc9NDMjcGw9MzY1MDgxNiNsYnM9MTQ6NzM2OTI2NDgjbG49V29ybGQ=",
   "isCollection": false
  },
  {
   "text": "Walt Disney World, Disneys Hollywood Studios Access Rd, Kissimmee, FL, 34747, USA",
   "magicKey": "dHA9MCN0dj01MzQ0YjFhMiNsb2M9MzMzNjQ5MCNsbmc9NDMjcGw9MzgzNTI4OCNsYnM9MTQ6NzMzNDE5MzIjbG49V29ybGQ=",
   "isCollection": false
  },
  {
   "text": "Winter Park Resort, Winter Park Dr, Winter Park, CO, 80482, USA",
   "magicKey": "dHA9MCN0dj01MzQ0YjFhMiNsb2M9MjUzMzEyMyNsbmc9NDMjcGw9MzA0MDAzNiNsYnM9MTQ6NzQzMjc2MjUjbG49V29ybGQ=",
   "isCollection": false
  },
  {
   "text": "Wrocław, Dolnośląskie, POL",
   "magicKey": "dHA9MCN0dj01MzQ0YjFhMiNsb2M9NjY0MzQ0OTUjbG5nPTEzNSNwbD04NjYzOTI5OSNsYnM9MTQ6NzQ1MTkyMDgjbG49V29ybGQ=",
   "isCollection": false
  }
 ]
}

As you can see, the suggestions returned for this request (with returnCollections=false) all represent specific, individual places.

By contrast, when returnCollections=true for the same request, the top suggestion is collection "Whole Foods", which is a supermarket chain.

Example

Enable collections by using returnCollections=true with input text w and location in Washington, DC (location=-77.043,38.91)

Request URL

https://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer/suggest?text=w&location=-77.043,38.91&returnCollections=true&f=pjson&token=<ACCESS_TOKEN>

https://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer/suggest?text=w&location=-77.043,38.91&returnCollections=true&f=pjson&token=<ACCESS_TOKEN>

JSON response

{
 "suggestions": [
  {
   "text": "Whole Foods",
   "magicKey": "dHA9MSN0dj01MzQ0YjFhMiNubT1XaG9sZSBGb29kcyNzej0tNzcuMDQzMDAwMDAwMDAwMDA2OjM4LjkwOTk5OTk5OTk5OTk5NyNjcz0xMjYjbG49V29ybGQ=",
   "isCollection": true
  },
  {
   "text": "Washington Monument, 2 15th St NW, Washington, DC, 20006, USA",
   "magicKey": "dHA9MCN0dj01MzQ0YjFhMiNsb2M9Mjk5MDYzMCNsbmc9NDMjcGw9MzY2MTIxOSNmYT02NTUzNiNsYnM9MTQ6NzM2OTU4ODEjbG49V29ybGQ=",
   "isCollection": false
  },
  {
   "text": "Washington, DC, USA",
   "magicKey": "dHA9MCN0dj01MzQ0YjFhMiNsb2M9Mjk4NDYwMCNsbmc9NDMjcGw9MzY1MDgxNiNsYnM9MTQ6NzM2OTI2NDgjbG49V29ybGQ=",
   "isCollection": false
  },
  {
   "text": "Waterfall",
   "magicKey": "dHA9MiN0dj01MzQ0YjFhMiNubT1XYXRlcmZhbGwjc3o9LTc3LjA0MzAwMDAwMDAwMDAwNjozOC45MDk5OTk5OTk5OTk5OTcjY3M9MzE5I2xuPVdvcmxk",
   "isCollection": true
  },
  {
   "text": "Wine and liquor",
   "magicKey": "dHA9MiN0dj01MzQ0YjFhMiNubT1XaW5lIGFuZCBsaXF1b3Ijc3o9LTc3LjA0MzAwMDAwMDAwMDAwNjozOC45MDk5OTk5OTk5OTk5OTcjY3M9MzY2I2xuPVdvcmxk",
   "isCollection": true
  }
 ]
}

Specifying the number of suggestions

Depending on the use cases of your application, the default number of suggestions returned by a suggest request (5) may be too few, or too many. You can use the maxSuggestions parameter to choose the amount of suggestions that works for you.

Example

Choosing the number of suggestions to return with maxSuggestions (with input text esri)

Request URL

https://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer/suggest?text=esri&maxSuggestions=8&f=pjson&token=<ACCESS_TOKEN>

https://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer/suggest?text=esri&maxSuggestions=8&f=pjson&token=<ACCESS_TOKEN>

JSON response

{
 "suggestions": [
  {
   "text": "Esri, 380 New York St, Redlands, CA, 92373, USA",
   "magicKey": "dHA9MCN0dj01MzQ0YjFhMiNsb2M9MjAxMTMyOSNsbmc9NDMjcGw9MzAwNDQxOCNmYT02NTUzNiNsYnM9MTQ6MjU5NzQ2MTMjbG49V29ybGQ=",
   "isCollection": false
  },
  {
   "text": "Esri Australia Pty. Ltd. – Brisbane Office, 111 Elizabeth Street, Level 3, Brisbane, Queensland, 4000, AUS",
   "magicKey": "dHA9MCN0dj01MzQ0YjFhMiNsb2M9MzU0MDYzMDEjbG5nPTQzI3BsPTM3MTE4OTgzI2ZhPTY1NTM3I2xicz0xNDoyNTk3NDYxOSNsbj1Xb3JsZA==",
   "isCollection": false
  },
  {
   "text": "Esri Canada Ltd., 12 Concorde Place, Suite 900, Toronto, ON, M3C 3R8, CAN",
   "magicKey": "dHA9MCN0dj01MzQ0YjFhMiNsb2M9MTk5ODEwODkjbG5nPTQzI3BsPTE5NDc4ODYwI2ZhPTY1NTM3I2xicz0xNDoyNTk3NDY1NCNsbj1Xb3JsZA==",
   "isCollection": false
  },
  {
   "text": "Esri Chile S.A., Apoquindo 6550, Las Condes, Santiago, 7560903, CHL",
   "magicKey": "dHA9MCN0dj01MzQ0YjFhMiNsb2M9NDAwNDE2NjAjbG5nPTE2MCNwbD00MjgwODI5MyNmYT02NTUzNyNsYnM9MTQ6MjU5NzQ2NTgjbG49V29ybGQ=",
   "isCollection": false
  },
  {
   "text": "Esri Deutschland GmbH, Ring Straße 7, 85402, Kranzberg, Bayern, DEU",
   "magicKey": "dHA9MCN0dj01MzQ0YjFhMiNsb2M9MjI4MDAzOTcjbG5nPTU4I3BsPTIzMzEzODY4I2ZhPTY1NTM2I2xicz0xNDoyNTk3NDY2OCNsbj1Xb3JsZA==",
   "isCollection": false
  },
  {
   "text": "Esri España Soluciones Geoespaciales S.L., Paseo de la Castellana 91, 28046, Madrid, ESP",
   "magicKey": "dHA9MCN0dj01MzQ0YjFhMiNsb2M9NDY5MDU2NzcjbG5nPTE2MCNwbD00ODY0NTEzOCNmYT02NTUzNiNsYnM9MTQ6MjU5NzQ2NzIjbG49V29ybGQ=",
   "isCollection": false
  },
  {
   "text": "Esri Finland Oy, Bertel Jungin Aukio 3, 02600, Espoo, FIN",
   "magicKey": "dHA9MCN0dj01MzQ0YjFhMiNsb2M9NDcyNjg5MzMjbG5nPTUxI3BsPTQ5MDAzMzYwI2ZhPTY1NTM2I2xicz0xNDoyNTk3NDY3NCNsbj1Xb3JsZA==",
   "isCollection": false
  },
  {
   "text": "Esri Indonesia, Jalan TB Simatupang 1, Pasar Minggu, DKI Jakarta, 12560, IDN",
   "magicKey": "dHA9MCN0dj01MzQ0YjFhMiNsb2M9NDg5OTI5MzgjbG5nPTgyI3BsPTUxMTY1NDc0I2ZhPTY1NTM3I2xicz0xNDoyNTk3NDY4OCNsbj1Xb3JsZA==",
   "isCollection": false
  }
 ]
}

Limiting suggestions by country

By default, the ArcGIS Geocoding service returns suggestions from any relevant country based on the input text, unless the location or searchExtent parameters are used. These parameters do not strictly filter by country, however. To do so, the countryCode parameter should be used. It allows you to limit the suggestions to one or more specific countries.

Example

Return suggestions for Indonesia only using countryCode (with input text esri)

Request URL

https://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer/suggest?text=esri&countryCode=IDN&f=pjson&token=<ACCESS_TOKEN>

https://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer/suggest?text=esri&countryCode=IDN&f=pjson&token=<ACCESS_TOKEN>

JSON response

{
 "suggestions": [
  {
   "text": "Esri Indonesia, Jalan TB Simatupang 1, Pasar Minggu, DKI Jakarta, 12560, IDN",
   "magicKey": "dHA9MCN0dj01MzQ0YjFhMiNsb2M9NDg5OTI5MzgjbG5nPTgyI3BsPTUxMTY1NDc0I2ZhPTY1NTM3I2xicz0xNDoyNTk3NDY4OCNsbj1Xb3JsZA==",
   "isCollection": false
  },
  {
   "text": "Esri Rejeki, Jalan Kendalisodo, Bandungan, Jawa Tengah, 50651, IDN",
   "magicKey": "dHA9MCN0dj01MzQ0YjFhMiNsb2M9NDkzMDY4NTcjbG5nPTgyI3BsPTUyNDU3NDc5I2xicz0xNDoyNTk3NDczNyNsbj1Xb3JsZA==",
   "isCollection": false
  },
  {
   "text": "Esri Villa's, Kasihan, Yogyakarta, 55184, IDN",
   "magicKey": "dHA9MCN0dj01MzQ0YjFhMiNsb2M9NDk4ODM5MDkjbG5nPTgyI3BsPTU0NDQ5MDEyI2xicz0xNDoyNTk3NDc4NSNsbj1Xb3JsZA==",
   "isCollection": false
  },
  {
   "text": "Esri Indonesia Branch Balikpapan, Jalan Jendral Sudirman 7, Balikpapan, East Kalimantan, 76114, IDN",
   "magicKey": "dHA9MCN0dj01MzQ0YjFhMiNsb2M9NDg5OTI5NDAjbG5nPTgyI3BsPTUxMTY1NDc2I2ZhPTY1NTM3I2xicz0xNDoyNTk3NDY4OSNsbj1Xb3JsZA==",
   "isCollection": false
  },
  {
   "text": "Esri Indonesia Branch Pekanbaru, Jalan Todak 18, Marpoyan Damai, Riau, 28124, IDN",
   "magicKey": "dHA9MCN0dj01MzQ0YjFhMiNsb2M9NDk3MDk1MjUjbG5nPTgyI3BsPTUzODM2MzIyI2ZhPTY1NTM2I2xicz0xNDoyNTk3NDY5MCNsbj1Xb3JsZA==",
   "isCollection": false
  }
 ]
}

Category filtering

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

For example, a user may type Bear in a search box, expecting the service to return Bear Mountain ski resort as a suggestion. However, there are many populated places in the world with Bear in their name, and this is reflected in the suggestions.

Example

Get suggestions for "Bear" without category

Request URL

https://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer/suggest?text=bear&category=&f=pjson&token=<ACCESS_TOKEN>

https://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer/suggest?text=bear&category=&f=pjson&token=<ACCESS_TOKEN>

JSON response

{
 "suggestions": [
  {
   "text": "Bearsden, Dunbartonshire, Scotland, GBR",
   "magicKey": "dHA9MCN0dj01MzQ0YjFhMiNsb2M9MjE5ODQ5MDEjbG5nPTQzI3BsPTIyMzg0NjgzI2xicz0xNDoxMjM5MTI0NiNsbj1Xb3JsZA==",
   "isCollection": false
  },
  {
   "text": "Bear Lake County, ID, USA",
   "magicKey": "dHA9MCN0dj01MzQ0YjFhMiNsb2M9NDcxODg4NyNsbmc9NDMjcGw9NTUyMDEwMyNsYnM9MTQ6MTIzODU5ODgjbG49V29ybGQ=",
   "isCollection": false
  },
  {
   "text": "Bear, DE, USA",
   "magicKey": "dHA9MCN0dj01MzQ0YjFhMiNsb2M9MjkyNjkyNyNsbmc9NDMjcGw9MzU5NjQxMyNsYnM9MTQ6MTIzODM3ODMjbG49V29ybGQ=",
   "isCollection": false
  },
  {
   "text": "Bear Valley Springs, CA, USA",
   "magicKey": "dHA9MCN0dj01MzQ0YjFhMiNsb2M9MTI0Nzk3MiNsbmc9NDMjcGw9OTc2MjcxI2xicz0xNDoxMjM4NzcwNiNsbj1Xb3JsZA==",
   "isCollection": false
  },
  {
   "text": "Bear Creek, AL, USA",
   "magicKey": "dHA9MCN0dj01MzQ0YjFhMiNsb2M9MTQzODczI2xuZz00MyNwbD00MTgzNSNsYnM9MTQ6MTIzODQ0OTMjbG49V29ybGQ=",
   "isCollection": false
  }
 ]
}

See Category filtering for details.

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 Bear are returned.

Example

Get suggestions for "Bear" with category=Ski Resort

Request URL

https://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer/suggest?text=bear&category=Ski Resort&f=pjson&token=<ACCESS_TOKEN>

https://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer/suggest?text=bear&category=Ski%20Resort&f=pjson&token=<ACCESS_TOKEN>

JSON response

{
 "suggestions": [
  {
   "text": "Bear Mountain, 43101 Goldmine Dr, Big Bear Lake, CA, 92315, USA",
   "magicKey": "dHA9MCN0dj01MzQ0YjFhMiNsb2M9MTU1NDYzOCNsbmc9NDMjcGw9MTEyMDcyMCNmYT02NTUzNiNsYnM9MTQ6MTIzODYyODQjbG49V29ybGQ=",
   "isCollection": false
  },
  {
   "text": "Bear Valley Alpine Ski Company Main Office, Arnold, CA, 95223, USA",
   "magicKey": "dHA9MCN0dj01MzQ0YjFhMiNsb2M9MTE3NTM3MiNsbmc9NDMjcGw9OTUyODA2I2xicz0xNDoxMjM4NzU0MSNsbj1Xb3JsZA==",
   "isCollection": false
  },
  {
   "text": "Bearsden Ski & Board Club, Milngavie, Lanarkshire, Scotland, G61 3, GBR",
   "magicKey": "dHA9MCN0dj01MzQ0YjFhMiNsb2M9MjE5MjU5NzQjbG5nPTQzI3BsPTIyMjU5OTQ5I2xicz0xNDoxMjM5MTI3NCNsbj1Xb3JsZA==",
   "isCollection": false
  },
  {
   "text": "Beartooth Basin Summer Ski Area, US Highway 212, Cody, WY, USA",
   "magicKey": "dHA9MCN0dj01MzQ0YjFhMiNsb2M9MTkwODQwMjMjbG5nPTQzI3BsPTE4NDYzODg1I2xicz0xNDoxMjM5MTUxMSNsbj1Xb3JsZA==",
   "isCollection": false
  },
  {
   "text": "Beartown Ski Area, 285 Beartown Rd, West Chazy, NY, 12992, USA",
   "magicKey": "dHA9MCN0dj01MzQ0YjFhMiNsb2M9MTA5ODc5MzUjbG5nPTQzI3BsPTExMDg5ODQ5I2ZhPTY1NTM2I2xicz0xNDoxMjM5MTY1MCNsbj1Xb3JsZA==",
   "isCollection": false
  }
 ]
}

See Category filtering for details.

Using the preferredLabelValues parameter with suggest

The preferredLabelValues parameter allows limited customization of output values in suggestions. Refer to the parameter overview for details about its functionality; this section includes examples showing how it can be used.

The preferredLabelValues parameter can be used to override the default city name returned in address labels for a suggest transaction. The default values are based on country addressing conventions and data availability. United States addresses returned by the ArcGIS Geocoding service include the primary city name assigned to the postal code that is associated with the address; this is known as the postal city name. Sometimes the postal city name is different than the name of the city whose boundaries the address is within. For instance, one of the postal codes used in the city of Merriam, Kansas is 66202. The primary name assigned to postal code 66202 is Mission, which is a separate city adjacent to the city of Merriam. When addresses with postal code 66202 are returned in suggestions by the ArcGIS Geocoding service, the suggestion labels include Mission as the city name by default.

The following examples illustrate how to use the preferredLabelValues parameter to modify the city name used in suggestions for address 9001 W 62nd St in Merriam, Kansas.

Without the parameter, Mission is included in suggestions as the city name (refer to the top suggestion in the response for this example):

Example

Return suggestions without using preferredLabelValues (text = 9001 W 62nd St)

Request URL

https://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer/suggest?text=9001 W 62nd St&preferredLabelValues=&f=pjson&token=<ACCESS_TOKEN>

https://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer/suggest?text=9001%20W%2062nd%20St&preferredLabelValues=&f=pjson&token=<ACCESS_TOKEN>

JSON response

{
 "suggestions": [
  {
   "text": "9001 W 62nd St, Mission, KS, 66202, USA",
   "magicKey": "dHA9MCN0dj01MzQ0YjFhMiNsb2M9NjUzNzI3MCNsbmc9NDMjZmE9NjU1MzYjaG49OTAwMSNsYnM9MTA5OjcyOTE3Mjc3I2xuPVdvcmxk",
   "isCollection": false
  },
  {
   "text": "9001 W 62nd St S, Monroe, IA, 50170, USA",
   "magicKey": "dHA9MCN0dj01MzQ0YjFhMiNsb2M9NjA4NTEyNyNsbmc9NDMjaG49OTAwMSNsYnM9MTA5OjcyOTE3Mjc5I2xuPVdvcmxk",
   "isCollection": false
  },
  {
   "text": "9001 W 62nd St, Indianapolis, IN, 46278, USA",
   "magicKey": "dHA9MCN0dj01MzQ0YjFhMiNsb2M9NTY4MzQ5NyNsbmc9NDMjaG49OTAwMSNsYnM9MTA5OjcyOTE3Mjc3I2xuPVdvcmxk",
   "isCollection": false
  },
  {
   "text": "W 62nd St, Anniston, AL, 36206, USA",
   "magicKey": "dHA9MCN0dj01MzQ0YjFhMiNsb2M9MjQ3NDAjbG5nPTQzI2xicz0xMDk6NzI5MTcyNzcjbG49V29ybGQ=",
   "isCollection": false
  },
  {
   "text": "W 62nd St, Chicago, IL, 60621, USA",
   "magicKey": "dHA9NCN0dj01MzQ0YjFhMiNubT1XIDYybmQgU3QsIENoaWNhZ28sIElMLCA2MDYyMSwgVVNBI2xuZz00MyNsbj1Xb3JsZA==",
   "isCollection": false
  }
 ]
}

The preferredLabelValues parameter can be used to return a more suitable city name for this address in suggestions. Pass preferredLabelValues=localCity in the suggest request to return Merriam as the city name in suggestions (refer to the top suggestion in the response for this example):

Example

Return suggestions using preferredLabelValues=localCity (text = 9001 W 62nd St)

Request URL

https://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer/suggest?text=9001 W 62nd St&preferredLabelValues=localCity&f=pjson&token=<ACCESS_TOKEN>

https://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer/suggest?text=9001%20W%2062nd%20St&preferredLabelValues=localCity&f=pjson&token=<ACCESS_TOKEN>

JSON response

{
 "suggestions": [
  {
   "text": "9001 W 62nd St, Merriam, KS, 66202, USA",
   "magicKey": "dHA9MCN0dj01MzQ0YjFhMiNsb2M9NjUzNzI3MCNsbmc9NDMjZmE9NjU1MzYjaG49OTAwMSNsYnM9MTA5OjcyOTE3Mjc3I2xuPVdvcmxk",
   "isCollection": false
  },
  {
   "text": "9001 W 62nd St S, Fairview, IA, 50170, USA",
   "magicKey": "dHA9MCN0dj01MzQ0YjFhMiNsb2M9NjA4NTEyNyNsbmc9NDMjaG49OTAwMSNsYnM9MTA5OjcyOTE3Mjc5I2xuPVdvcmxk",
   "isCollection": false
  },
  {
   "text": "9001 W 62nd St, Indianapolis, IN, 46278, USA",
   "magicKey": "dHA9MCN0dj01MzQ0YjFhMiNsb2M9NTY4MzQ5NyNsbmc9NDMjaG49OTAwMSNsYnM9MTA5OjcyOTE3Mjc3I2xuPVdvcmxk",
   "isCollection": false
  },
  {
   "text": "W 62nd St, Chicago, IL, 60621, USA",
   "magicKey": "dHA9NCN0dj01MzQ0YjFhMiNubT1XIDYybmQgU3QsIENoaWNhZ28sIElMLCA2MDYyMSwgVVNBI2xuZz00MyNsbj1Xb3JsZA==",
   "isCollection": false
  },
  {
   "text": "W 62nd St, Chicago, IL, 60629, USA",
   "magicKey": "dHA9NCN0dj01MzQ0YjFhMiNubT1XIDYybmQgU3QsIENoaWNhZ28sIElMLCA2MDYyOSwgVVNBI2xuZz00MyNsbj1Xb3JsZA==",
   "isCollection": false
  }
 ]
}

However, if you start typing Mission as the city name for the same input, like this—9001 W 62nd St Mi—also with preferredLabelValues=localCity, postal city name Mission is used in suggestions instead of local city name Merriam, even though localCity is specified in the request. This is because suggest is designed to return suggestions that reflect the user's input as closely as possible. In this case, the user input may override the preferredLabelValues parameter (refer to the top suggestion in the response for this example):

Example

Return suggestions using preferredLabelValues=localCity; the parameter is overridden by input city (text = 9001 W 62nd St Mi)

Request URL

https://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer/suggest?f=pjson&text=9001 W 62nd St Mi&preferredLabelValues=localCity&f=pjson&token=<ACCESS_TOKEN>

https://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer/suggest?f=pjson&text=9001%20W%2062nd%20St%20Mi&preferredLabelValues=localCity&f=pjson&token=<ACCESS_TOKEN>

JSON response

{
 "suggestions": [
  {
   "text": "9001 W 62nd St, Mission, KS, 66202, USA",
   "magicKey": "dHA9NCN0dj01MzQ0YjFhMiNubT05MDAxIFcgNjJuZCBTdCwgTWlzc2lvbiwgS1MsIDY2MjAyLCBVU0EjbG5nPTQzI2xuPVdvcmxk",
   "isCollection": false
  },
  {
   "text": "9001 62nd St, Croton, MI, 49337, USA",
   "magicKey": "dHA9MCN0dj01MzQ0YjFhMiNsb2M9ODIzODU4MCNsbmc9NDMjaG49OTAwMSNsYnM9MTA5OjgzMDQ3MDk2OzI6NDI5NjEzODUjbG49V29ybGQ=",
   "isCollection": false
  },
  {
   "text": "9001 62nd St, Geneva, MI, 49090, USA",
   "magicKey": "dHA9MCN0dj01MzQ0YjFhMiNsb2M9ODMxMDg1MyNsbmc9NDMjaG49OTAwMSNsYnM9MTA5OjgzMDQ3MDk2OzI6NDI5NjEzODUjbG49V29ybGQ=",
   "isCollection": false
  },
  {
   "text": "9001 62nd St S, Cottage Grove, MN, 55016, USA",
   "magicKey": "dHA9NCN0dj01MzQ0YjFhMiNubT05MDAxIDYybmQgU3QgUywgQ290dGFnZSBHcm92ZSwgTU4sIDU1MDE2LCBVU0EjbG5nPTQzI2xuPVdvcmxk",
   "isCollection": false
  },
  {
   "text": "9001 62nd St NW, Minot, ND, 58703, USA",
   "magicKey": "dHA9MCN0dj01MzQ0YjFhMiNsb2M9MTI1NTE0ODcjbG5nPTQzI2huPTkwMDEjbGJzPTEwOTo4MzA0NzEwMDs5OjQ2NDgzNzk0I2xuPVdvcmxk",
   "isCollection": false
  }
 ]
}

When the preferredLabelValues parameter is used for suggest, it should also be used in the corresponding findAddressCandidates request when the user selects a suggestion. If you take the top suggestion from the previous example—with city name Mission in the label—and pass it to findAddressCandidates with preferredLabelValues=localCity included in the request, the resulting response will include Merriam as the city name in labels instead of Mission. This is because findAddressCandidates always honors the preferredLabelValues parameter, unlike suggest, for which matching the user input is prioritized:

Example

Use findAddressCandidates with magicKey when preferredLabelValues=localCity; the parameter is overridden by input city (text = 9001 W 62nd St Mi)

Request URL

https://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer/findAddressCandidates?outFields=Match_addr,City&f=pjson&singleline=9001 W 62nd St, Mission, KS, 66202, USA&magicKey=dHA9NCN0dj01MzQ0YjFhMiNubT05MDAxIFcgNjJuZCBTdCwgTWlzc2lvbiwgS1MsIDY2MjAyLCBVU0EjbG5nPTQzI2xuPVdvcmxk&preferredLabelValues=localCity&token=<ACCESS_TOKEN>

https://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer/findAddressCandidates?outFields=Match_addr,City&f=pjson&singleline=9001%20W%2062nd%20St%2C%20Mission%2C%20KS%2C%2066202%2C%20USA&magicKey=dHA9NCN0dj01MzQ0YjFhMiNubT05MDAxIFcgNjJuZCBTdCwgTWlzc2lvbiwgS1MsIDY2MjAyLCBVU0EjbG5nPTQzI2xuPVdvcmxk&preferredLabelValues=localCity&token=<ACCESS_TOKEN>

findAddressCandidates JSON response

{
 "spatialReference": {
  "wkid": 4326,
  "latestWkid": 4326
 },
 "candidates": [
  {
   "address": "9001 W 62nd St, Merriam, Kansas, 66202",
   "location": {
    "x": -94.689890032024,
    "y": 39.016895987567
   },
   "score": 100,
   "attributes": {
    "Match_addr": "9001 W 62nd St, Merriam, Kansas, 66202",
    "City": "Merriam"
   },
   "extent": {
    "xmin": -94.690890032024,
    "ymin": 39.015895987567,
    "xmax": -94.688890032024,
    "ymax": 39.017895987567
   }
  }
 ]
}

Refer to the findAddressCandidates topic for more information about how the preferredLabelValues parameter can be used with that operation.

In this topic

Access the services
Request URL
Request parameters
Suggest output
Working with suggestions
Using proximity with suggestions
Limiting suggestions to a specified area
Utilizing the isCollection property
Disabling collections
Specifying the number of suggestions
Limiting suggestions by country
Category filtering
Using the preferredLabelValues parameter with suggest