suggest

The World 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.

Suggest an address

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:

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

Request URL

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

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 location that is used to sort geocoding candidates based on their proximity to the location. The priority of candidates within a default radial distance from the location are boosted relative to those outside the radius. The default distance is 50,000 meters; this value is not configurable.

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 parameter can be used in this scenario.

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.

NoteNote:

The distance parameter is deprecated and no longer recognized by the service. A default distance of 50,000 meters is now used internally by the service to boost suggestion priority for all requests with location.

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

category

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

NoteNote:

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 of category filtering with a single category:
category=Address
Example of category filtering with multiple categories:
category=Address,Postal

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

maxSuggestions

The maximum number of suggestions returned by a suggest operation, up to the maximum number allowed by the service. Currently, the World 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. Supported values include the ISO 3166-1 2-digit country code or the ISO 3166-1 3-digit country code. Valid 2- and 3-digit country code values for each country are available in Geocode coverage.

NoteNote:

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

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

A unique ID that, along with text, links a suggestion to a specific 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

isCollection

A Boolean parameter that indicates if 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 where isCollection is true versus cases where 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:

http://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:

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

NoteNote:

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 in order to prioritize places that are closest to the specified location.

By utilizing 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 area 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

Suggest JSON response

{
 "suggestions": [
  {
   "text": "Treasure Island, 3300 Las Vegas Blvd S, Las Vegas, NV, 89109, USA",
   "magicKey": "dHA9MCNsb2M9NjE5Mjg0MiNsbmc9MzMjcGw9MTk5MDY5NSNsYnM9MTQ6MjUyODM0Mzc=",
   "isCollection": false
  },
  {
   "text": "Treasure Island-Parking Entrance, Mel Torme Way, Las Vegas, NV, 89109, USA",
   "magicKey": "dHA9MCNsb2M9NjE5Mjg0NyNsbmc9MzMjcGw9MTk5MDg1OSNsYnM9MTQ6MjUyODM1MDc=",
   "isCollection": false
  },
  {
   "text": "Treasure Island, Mel Torme Way, Las Vegas, NV, 89109, USA",
   "magicKey": "dHA9MCNsb2M9NjE5Mjg0NyNsbmc9MzMjcGw9MTk5MDg2MCNsYnM9MTQ6MjUyODM0Mzc=",
   "isCollection": false
  },
  {
   "text": "Treasure Island, Las Vegas, NV, 89109, USA",
   "magicKey": "dHA9MCNsb2M9NjE5MjgwNSNsbmc9MzMjcGw9MTk5MDE3MiNsYnM9MTQ6MjUyODM0Mzc=",
   "isCollection": false
  },
  {
   "text": "Treasure Island, Industrial Rd, Las Vegas, NV, 89109, USA",
   "magicKey": "dHA9MCNsb2M9NjE5MjgyMyNsbmc9MzMjcGw9MTk5MDU3NiNsYnM9MTQ6MjUyODM0Mzc=",
   "isCollection": false
  }
 ]
}

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

Suggest JSON response

{
 "suggestions": [
  {
   "text": "Treasure Bay, Islands, HKG",
   "magicKey": "dHA9MCNsb2M9MjkzMzgwOTUjbG5nPTMzI3BsPTE3MTMxMTUxI2xicz0xNDoyNTI4MzIxNQ==",
   "isCollection": false
  },
  {
   "text": "Treasure Court, Yuen Long, HKG",
   "magicKey": "dHA9MCNsb2M9MjkzMzY0MTMjbG5nPTMzI3BsPTE3MTMwMzU5I2xicz0xNDoyNTI4MzMyMw==",
   "isCollection": false
  },
  {
   "text": "Treasure Garden, Sha Tin, HKG",
   "magicKey": "dHA9MCNsb2M9MjkzNDE1MTAjbG5nPTMzI3BsPTE3MTMzMTEyI2xicz0xNDoyNTI4MzM2Mw==",
   "isCollection": false
  },
  {
   "text": "Treasure Spot Garden Ii, Sha Tin, HKG",
   "magicKey": "dHA9MCNsb2M9MjkzNDE1NTMjbG5nPTMzI3BsPTE3MTMzMTU1I2xicz0xNDoyNTI4MzU4Ng==",
   "isCollection": false
  },
  {
   "text": "Treasure Spot Palace, Sha Tin, HKG",
   "magicKey": "dHA9MCNsb2M9MjkzNDE2MzYjbG5nPTMzI3BsPTE3MTMzMjM4I2xicz0xNDoyNTI4MzU4Nw==",
   "isCollection": false
  }
 ]
}

It is important to note that proximity search does not filter results that are beyond 50,000 meters 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 much farther away than 50,000 meters, it is still returned because it is the second most relevant candidate based on its distance from the location and its rank. In order to limit suggestions to a specific area, use the searchExtent parameter.

NoteNote:

For best results, it is recommended that applications implementing suggestions apply the location parameter at map scales of 1:300,000 and larger (1:200,000, 1:50,000, and so on).

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. If you want 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

Suggest JSON response

{
 "suggestions": [
  {
   "text": "Main St, Kansas City, MO, 64105, USA",
   "magicKey": "dHA9MCNsb2M9MzI4NTQxI2xuZz0zMyNsYnM9MTA5OjM1NDk3MDk2",
   "isCollection": false
  },
  {
   "text": "Main St, Kansas City, MO, 64106, USA",
   "magicKey": "dHA9MCNsb2M9MzI4NTUxI2xuZz0zMyNsYnM9MTA5OjM1NDk3MDk2",
   "isCollection": false
  },
  {
   "text": "Main Street Parking Garage, 1026 Main St, Kansas City, MO, 64105, USA",
   "magicKey": "dHA9MCNsb2M9MzI2MjUzI2xuZz0zMyNwbD0xMDQzMjYjbGJzPTE0OjE1NDczMjAz",
   "isCollection": false
  },
  {
   "text": "Main St, Kansas City, MO, 64108, USA",
   "magicKey": "dHA9MCNsb2M9MzI3NTUxI2xuZz0zMyNsYnM9MTA5OjM1NDk3MDk2",
   "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 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 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

Suggest JSON response

{
 "suggestions": [
  {
   "text": "Main St, Kansas City, MO, 64105, USA",
   "magicKey": "dHA9MCNsb2M9MzI4NTQxI2xuZz0zMyNsYnM9MTA5OjM1NDk3MDk2",
   "isCollection": false
  },
  {
   "text": "Main St, Kansas City, MO, 64106, USA",
   "magicKey": "dHA9MCNsb2M9MzI4NTUxI2xuZz0zMyNsYnM9MTA5OjM1NDk3MDk2",
   "isCollection": false
  },
  {
   "text": "Main Street Parking Garage, 1026 Main St, Kansas City, MO, 64105, USA",
   "magicKey": "dHA9MCNsb2M9MzI2MjUzI2xuZz0zMyNwbD0xMDQzMjYjbGJzPTE0OjE1NDczMjAz",
   "isCollection": false
  },
  {
   "text": "Main St, Kansas City, MO, 64108, USA",
   "magicKey": "dHA9MCNsb2M9MzI3NTUxI2xuZz0zMyNsYnM9MTA5OjM1NDk3MDk2",
   "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

Suggest JSON response

{
 "suggestions": [
  {
   "text": "Coffee",
   "magicKey": "dHA9MiNubT1Db2ZmZWUjc3o9MTUxLjIyOTEyOTotMzMuODc5NzQxMDAwMDAwMDAzI2NzPTcw",
   "isCollection": true
  },
  {
   "text": "Coffee Tea & Me, Macleay St, Elizabeth Bay, New South Wales, 2011, AUS",
   "magicKey": "dHA9MCNsb2M9MjA5OTg1OTkjbG5nPTMzI3BsPTExMDg1NDM3I2xicz0xNDo2OTk4NDkz",
   "isCollection": false
  },
  {
   "text": "Coffee Garam, 29 Bellevue St, Surry Hills, New South Wales, 2010, AUS",
   "magicKey": "dHA9MCNsb2M9MjA5ODg2MDIjbG5nPTMzI3BsPTExMDcxNjA0I2xicz0xNDo2OTk1MDk0",
   "isCollection": false
  },
  {
   "text": "Coffee Dan's Gourmet, 51 Holt St, Surry Hills, New South Wales, 2010, AUS",
   "magicKey": "dHA9MCNsb2M9MjA5ODg2MDAjbG5nPTMzI3BsPTExMDcxNTc1I2xicz0xNDo2OTk0Njc4",
   "isCollection": false
  },
  {
   "text": "Coffee Pitt, 365 Pitt St, Sydney South, New South Wales, 2000, AUS",
   "magicKey": "dHA9MCNsb2M9MjA5ODg4NDYjbG5nPTMzI3BsPTExMDcyNDU5I2xicz0xNDo2OTk3NTEy",
   "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 geocoding service in a findAddressCandidates request, with maxLocations = 10, several different coffee shops are returned.

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

Request URL

findAddressCandidates JSON response

{
 "spatialReference": {
  "wkid": 4326,
  "latestWkid": 4326
 },
 "candidates": [
  {
   "address": "Slice",
   "location": {
    "x": 151.22911994113934,
    "y": -33.881879952247722
   },
   "score": 100,
   "attributes": {
    "Match_addr": "Slice",
    "Place_addr": "248 Glenmore Rd, Paddington, New South Wales, 2021",
    "Type": "Coffee Shop"
   },
   "extent": {
    "xmin": 151.22390000000007,
    "ymin": -33.88672999999995,
    "xmax": 151.23390000000006,
    "ymax": -33.876729999999945
   }
  },
  {
   "address": "Plumer at Fiveways",
   "location": {
    "x": 151.2280300510705,
    "y": -33.882209937820981
   },
   "score": 100,
   "attributes": {
    "Match_addr": "Plumer at Fiveways",
    "Place_addr": "226 Glenmore Rd, Paddington, New South Wales, 2021",
    "Type": "Coffee Shop"
   },
   "extent": {
    "xmin": 151.22305000000006,
    "ymin": -33.887119999999932,
    "xmax": 151.23305000000005,
    "ymax": -33.877119999999927
   }
  },
...

It is important to note that if maxLocations=10 had not been explicitly passed in the findAddressCandidates request, then 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, only a single candidate is returned.

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

Request URL

findAddressCandidates JSON response

{
 "spatialReference": {
  "wkid": 4326,
  "latestWkid": 4326
 },
 "candidates": [
  {
   "address": "Coffee Garam",
   "location": {
    "x": 151.21145000000001,
    "y": -33.883869999999945
   },
   "score": 100,
   "attributes": {
    
   },
   "extent": {
    "xmin": 151.20645000000002,
    "ymin": -33.888869999999947,
    "xmax": 151.21645000000001,
    "ymax": -33.878869999999942
   }
  }
 ]
}

A developer can use the isCollection property to properly handle cases such as this in their application. Specifically, for cases where 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 in order to show the user more results. For cases in which isCollection = false, the maxLocations parameter should be set to 1.

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

Suggest JSON response

{
 "suggestions": [
  {
   "text": "Esri, 380 New York St, Redlands, CA, 92373, USA",
   "magicKey": "dHA9MCNsb2M9NTE3MjI5NSNsbmc9MzMjcGw9MTYzNzA4MiNsYnM9MTQ6OTIxMjk4MQ==",
   "isCollection": false
  },
  {
   "text": "Esri Island, River Nile, SDN",
   "magicKey": "dHA9MCNsb2M9Mzk5ODA5OTIjbG5nPTE1OCNwbD0zNjY4MzQ2NCNsYnM9MTQ6OTIxMjk4OA==",
   "isCollection": false
  },
  {
   "text": "ESRIT, Улица Теразије, 11103, Стари Град, Београд, Град Београд, Централна Србија, SRB",
   "magicKey": "dHA9MCNsb2M9NDA0NDc3ODcjbG5nPTEyNiNwbD0zNzEyOTI5NSNsYnM9MTQ6ODc2ODc3Mw==",
   "isCollection": false
  },
  {
   "text": "Esri (Thailand) Co., Ltd., Si Lom, Bang Rak, Bangkok 10120, THA",
   "magicKey": "dHA9MCNsb2M9NDEzODEwNTQjbG5nPTE0MyNwbD0zODc4MDg0NyNsYnM9MTQ6OTIxMjk4Mg==",
   "isCollection": false
  },
  {
   "text": "Esri Eastern Africa, Kilimanjaro Ave, Nairobi, KEN",
   "magicKey": "dHA9MCNsb2M9MzMxNDUxMzcjbG5nPTMzI3BsPTI5MTc4Nzc1I2xicz0xNDo5MjEyOTg1",
   "isCollection": false
  },
  {
   "text": "Esri Eastern Africa, Nairobi, KEN",
   "magicKey": "dHA9MCNsb2M9MzMxNDUxMzMjbG5nPTMzI3BsPTI5MTc4NTE1I2xicz0xNDo5MjEyOTg1",
   "isCollection": false
  },
  {
   "text": "Esri Holding Lebanon, Rue 66, Mar Elias, Beyrouth, LBN",
   "magicKey": "dHA9MCNsb2M9MzMyNTUwNTEjbG5nPTQxI3BsPTI5NTQwMDEzI2xicz0xNDo5MjEyOTg2",
   "isCollection": false
  },
  {
   "text": "Esrimo, Calle Larga 76, 41130, La Puebla del Río, Sevilla, Andalucía, ESP",
   "magicKey": "dHA9MCNsb2M9Mjc0NDc4MzYjbG5nPTEzNCNwbD0xNTg2MDM4MCNsYnM9MTQ6OTIxMzAwMg==",
   "isCollection": false
  }
 ]
}

Limiting suggestions by country

By default, the World 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 Thailand only using countryCode (with input text esri)

Request URL

Suggest JSON response

{
 "suggestions": [
  {
   "text": "Esri (Thailand) Co., Ltd., Si Lom, Bang Rak, Bangkok 10120, THA",
   "magicKey": "dHA9MCNsb2M9NDEzODEwNTQjbG5nPTE0MyNwbD0zODc4MDg0NyNsYnM9MTQ6OTIxMjk4Mg==",
   "isCollection": false
  },
  {
   "text": "Esri (Thailand) Co., Ltd., Chong Nonsi, Yan Nawa, Bangkok 10110, THA",
   "magicKey": "dHA9MCNsb2M9NDEzOTg1MDcjbG5nPTE0MyNwbD0zODgxNzU2NSNsYnM9MTQ6OTIxMjk4Mg==",
   "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

JSON response

{
 "suggestions": [
  {
   "text": "Bear Lake, ID, USA",
   "magicKey": "dHA9MCNsb2M9NjMyNzQzNiNsbmc9MzMjcGw9MjAyODA2NiNsYnM9MTQ6NDgyNjI2Mw==",
   "isCollection": false
  },
  {
   "text": "Bear, DE, USA",
   "magicKey": "dHA9MCNsb2M9ODMyNjUwMyNsbmc9MzMjcGw9Mjg2MTQwMiNsYnM9MTQ6NDgyNTQwMA==",
   "isCollection": false
  },
  {
   "text": "Bear Creek Twp, MI, USA",
   "magicKey": "dHA9MCNsb2M9MTQzMzM2MCNsbmc9MzMjcGw9NDI2NTE2I2xicz0xNDo0ODI1ODgx",
   "isCollection": false
  },
  {
   "text": "Beardstown, IL, USA",
   "magicKey": "dHA9MCNsb2M9MTcwNzc4NyNsbmc9MzMjcGw9NTAzMTA0I2xicz0xNDo0ODI3NDM0",
   "isCollection": false
  },
  {
   "text": "Bear Valley Springs, CA, USA",
   "magicKey": "dHA9MCNsb2M9NTMxMjg5OSNsbmc9MzMjcGw9MTY5MzI2NSNsYnM9MTQ6NDgyNjkxNg==",
   "isCollection": false
  }
 ]
}

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

JSON response

{
 "suggestions": [
  {
   "text": "Bearsden Ski Club, Bearsden, Glasgow, Lanarkshire, Scotland, G61 3, GBR",
   "magicKey": "dHA9MCNsb2M9MTAyNjQyMDEjbG5nPTMzI3BsPTUyMzk4NDEjbGJzPTE0OjQ4MjgwNTQ=",
   "isCollection": false
  },
  {
   "text": "Bear Creek Mountain Resort, 101 Doe Mountain Ln, Macungie, PA, 18062, USA",
   "magicKey": "dHA9MCNsb2M9NzEzODEzMSNsbmc9MzMjcGw9MjQwNzY2NCNsYnM9MTQ6NDgyNTc3Nw==",
   "isCollection": false
  },
  {
   "text": "Bear Mountain, 43101 Goldmine Dr, Big Bear Lake, CA, 92315, USA",
   "magicKey": "dHA9MCNsb2M9NTE1NzkzMSNsbmc9MzMjcGw9MTYyOTA1MSNsYnM9MTQ6NDgyNjM5NA==",
   "isCollection": false
  },
  {
   "text": "Bear Paw Ski Bowl, Beaver Creek Rd, Havre, MT, 59501, USA",
   "magicKey": "dHA9MCNsb2M9ODM3Njg5MCNsbmc9MzMjcGw9Mjg3MzQ5MSNsYnM9MTQ6NDgyNjUwMg==",
   "isCollection": false
  },
  {
   "text": "Bear Peak, Grand Summit Rd, Bartlett, NH, 03812, USA",
   "magicKey": "dHA9MCNsb2M9NDcwMTE3OCNsbmc9MzMjcGw9MTQyODg2MCNsYnM9MTQ6NDgyNjUwOA==",
   "isCollection": false
  }
 ]
}

See Category filtering for complete details.

9/13/2017