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:

  • Street addresses (including street name)
    • 27488 Stanford Ave, Bowden, North Dakota
    • 380 New York St, Redlands, CA 92373
  • 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 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 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. It is also useful for web mapping applications where a user wants to find places within or near the map extent.

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 and WGS84:
location=-117.196,34.056
Example using JSON (102100 is the WKID for the Web Mercator projection):
location={"x": -13046165.572, "y": 4036389.847, "spatialReference": {"wkid": 102100}}

distance

Specifies the radius of an area around a point location, which is 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 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.

Example search limit of 2 miles:
distance=3218.69

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.

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.

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

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 and distance parameters 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

Note:

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

Using proximity with suggestions

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

By utilizing the location and distance parameters, you can define a circular area of influence for your searches. The locationparameter represents the center point of the area, and the distanceparameter defines the radius in meters. The purpose of this is to boost the rank of results closest to the specified location so they show up higher in the list of suggestions. Results that are within the 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, distance = 20000, and a user types Trea in a search box, the returned suggestions are all related to Treasure Island Hotel and Casino in Las Vegas.

Example: Get suggestions using location and distance

Request URL

Suggest JSON response

{
 "suggestions": [
  {
   "text": "Treasure Island (Performing Arts), 3300 Las Vegas Blvd S Las Vegas, NV 89109",
   "magicKey": "GST7YMc0AM9UOsE9HhFtGTyVGST7YMc0AM9UOsE9DbTVHgA9HhB0Zcp0OhNtGMytaikZQsoHQsbHUs8tIS9GOghnYnwZGPTq7iAm7Py_CR4PIic2BR4caocpOh9bZgKZQoc3YSyaagDIZhkZZc50HoFF",
   "isCollection": false
  },
  {
   "text": "Treasure Island (Tourist Attraction), 3300 Las Vegas Blvd S Las Vegas, NV 89109",
   "magicKey": "GST7YMc0AM9UOsE9HhFtGTyVGST7YMc0AM9UOsE9DbTVHgA9HhB0Zcp0OhNtGMytaikZQsoHQsbHUsNtIS9GOghnYnwZGPTq7iAm7Py_CR4PIic2BR4caocpOh9bZgKZQFc3YSyaagDIZhkZZc50HoFF",
   "isCollection": false
  },
  {
   "text": "Treasure Island Hotel and Casino (Casino), 3300 Las Vegas Blvd S Las Vegas, NV 89109",
   "magicKey": "GST7YMc0AM9UOsE9HhFtGTyVGST7YMc0AM9UOsE9DbTVHgA9HhB0Zcp0OhNtGMytaikZQsoHQsbHUBdtIS9GOghnYnwZGPTq7iAm7Py_CR4PIic2BR4caocpOh9bZgKZQ1c3YSyaagDIZhkZZc50HoFF",
   "isCollection": false
  },
  {
   "text": "Treasure Island Hotel and Casino (Hotel), 3300 Las Vegas Blvd S Las Vegas, NV 89109",
   "magicKey": "GST7YMc0AM9UOsE9HhFtGTyVGST7YMc0AM9UOsE9DbTVHgA9HhB0Zcp0OhNtGMytaikZQsoHQsbHUsVtIS9GOghnYnwZGPTq7iAm7Py_CR4PIic2BR4caocpOh9bZgKZUNc3YSyaagDIZhkZZc50HoFF",
   "isCollection": false
  },
  {
   "text": "Treasure Island, Mel Torme Way, Las Vegas, Nevada",
   "magicKey": "GST7YMc0AM9UOsE9HhFtGTyVGST7YMc0AM9UOsE9DbTVHgA9HhB0Zcp0OhNtGMytaikZQDbIUBxKQsxtIS9GOghnYnwZGPTq7iAm7Py_CR4PIic2BR4caocpOh9bZgKZUoc3YSyaagDIZhkZZc50HoFF",
   "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 and distance parameters are not passed in the suggest request, only admin places whose names begin with Trea are returned in the suggestions list.

Example: Get suggestions without location and distance

Request URL

Suggest JSON response

{
 "suggestions": [
  {
   "text": "Treasure State, United States",
   "magicKey": "GST7YMc0AM9UOsE9HhFtGTyVGST7YMc0AM9UOsE9DbTVHgA9HhB0Zcp0OhNtGMytaikZU5wOMsxJMoc4Hhp0OSTaSsEqAZ43AP9zJikuGPAmIYxQGPT-CZc0YiD7DsKJCZyAOh5-Dn47Z5EGYMyv",
   "isCollection": false
  },
  {
   "text": "Treaty Port, P'yŏngan-namdo, North Korea",
   "magicKey": "GST7YMc0AM9UOsE9HhFtGTyVGST7YMc0AM9UOsE9DbTVHgA9HhB0Zcp0OhNtGMytaikZQsNEQBwGMoc4Hhp0OSTaSsEqAZ43AP9zJikuGPAmIYxQGPT-CZc0YiD7DsKaCZyAOh5-Dn47Z5EGYMyv",
   "isCollection": false
  },
  {
   "text": "Treasure County, Montana, United States",
   "magicKey": "GST7YMc0AM9UOsE9HhFtGTyVGST7YMc0AM9UOsE9DbTVHgA9HhB0Zcp0OhNtGMytaikZUsdJQBxGQNc4Hhp0OSTaSsEqAZ43AP9zJikuGPAmIYxQGPT-CZc0YiD7DsKACZyAOh5-Dn47Z5EGYMyv",
   "isCollection": false
  },
  {
   "text": "Treasure Island, Florida, United States",
   "magicKey": "GST7YMc0AM9UOsE9HhFtGTyVGST7YMc0AM9UOsE9DbTVHgA9HhB0Zcp0OhNtGMytaikZQDgAQ58aUFc4Hhp0OSTaSsEqAZ43AP9zJikuGPAmIYxQGPT-CZc0YiD7DsKGCZyAOh5-Dn47Z5EGYMyv",
   "isCollection": false
  },
  {
   "text": "Treasure Lake, Pennsylvania, United States (City)",
   "magicKey": "GST7YMc0AM9UOsE9HhFtGTyVGST7YMc0AM9UOsE9DbTVHgA9HhB0Zcp0OhNtGMytaikZU5oIQDdEQ1c4Hhp0OSTaSsEqAZ43AP9zJikuGPAmIYxQGPT-CZc0YiD7DsK7CZyAOh5-Dn47Z5EGYMyv",
   "isCollection": false
  }
 ]
}

It is important to note that proximity search does not filter results that are outside of the location or distance area—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, distance = 20000, 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 20,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.

Note:

For best results, it is recommended that applications implementing suggestions apply the location and distance parameters at map scales of 1:300,000 and larger (1:200,000, 1:50,000, and so on). In all cases the distance value should not exceed 50,000.

Limiting suggestions to a specified area

Unlike the location and distance parameters, 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 Street Parking Garage, 1026 Main St, Kansas City, Missouri",
   "magicKey": "GST7YMc0AM9UOsE9HhFtGTyVGST7YMc0AM9UOsE9DbTVHgA9HhB0Zcp0OhNtGMytaikZQDkKQ5wAMsxtIS9GOghnYnwZGPTq7iAm7Py_CR4PIic2BR4caocpOh9bZgKZQoc3YSyaagDIZhkZDg9LDF4AZNFF",
   "isCollection": false
  },
  {
   "text": "Main St, Kansas City, Missouri, USA",
   "magicKey": "GST7YMc0AM9UOsE3GY8tIS9GOghnYnwZIip_GQypG1c2SckZBswGBBVAB5bHBBwGBNKOUN17U1aAMo1aUNcpOh9bZgKZQFc3YSyaagDIZhkZDg9LDF4AZNFF",
   "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 Street Parking Garage, 1026 Main St, Kansas City, Missouri",
   "magicKey": "GST7YMc0AM9UOsE9HhFtGTyVGST7YMc0AM9UOsE9DbTVHgA9HhB0Zcp0OhNtGMytaikZQDkKQ5wAMsxtIS9GOghnYnwZGPTq7iAm7Py_CR4PIic2BR4caocpOh9bZgKZQoc3YSyaagDIZhkZDg9LDF4AZNFF",
   "isCollection": false
  },
  {
   "text": "Main St, Kansas City, Missouri, USA",
   "magicKey": "GST7YMc0AM9UOsE3GY8tIS9GOghnYnwZIip_GQypG1c2SckZBswGBBVAB5bHBBwGBNKOUN17U1aAMo1aUNcpOh9bZgKZQFc3YSyaagDIZhkZDg9LDF4AZNFF",
   "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 Shop",
   "magicKey": "GST7YMc0AM9UOsE9HhFtS5KJUs8MQBNOCTwZBsbABBVEMsgtGSyJAnyUns8t7hc0YQWMYcyGngcnOMs0OoFF",
   "isCollection": true
  },
  {
   "text": "Bar Bacco, McLachlan Ave, Sydney, New South Wales",
   "magicKey": "GST7YMc0AM9UOsE9HhFtGTyVGST7YMc0AM9UOsE9DbTVHgA9HhB0Zcp0OhNtGMytaikZQsdGMs8KQBktIS9GOghnYnwZGPT-CZc0YiD7DsKaCZyAOh5-Dn47Z5EtDSswOgxF",
   "isCollection": false
  },
  {
   "text": "Cafe MAYBACH, McLachlan Ave, Sydney, New South Wales",
   "magicKey": "GST7YMc0AM9UOsE9HhFtGTyVGST7YMc0AM9UOsE9DbTVHgA9HhB0Zcp0OhNtGMytaikZQsdGMs8KQBxtIS9GOghnYnwZGPT-CZc0YiD7DsKACZyAOh5-Dn47Z5EtDSswOgxF",
   "isCollection": false
  },
  {
   "text": "Ignition Cafe, McLachlan Ave, Sydney, New South Wales",
   "magicKey": "GST7YMc0AM9UOsE9HhFtGTyVGST7YMc0AM9UOsE9DbTVHgA9HhB0Zcp0OhNtGMytaikZQsdGMs87U5btIS9GOghnYnwZGPT-CZc0YiD7DsKGCZyAOh5-Dn47Z5EtDSswOgxF",
   "isCollection": false
  },
  {
   "text": "Ash's Bay Cafe, 86 Bayswater Rd, Sydney, New South Wales",
   "magicKey": "GST7YMc0AM9UOsE9HhFtGTyVGST7YMc0AM9UOsE9DbTVHgA9HhB0Zcp0OhNtGMytaikZQBgOUsoaU5btIS9GOghnYnwZGPT-CZc0YiD7DsK7CZyAOh5-Dn47Z5EtDSswOgxF",
   "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.22911668800054,
    "y": -33.881879591999621
   },
   "score": 100,
   "attributes": {
    "Match_addr": "Slice",
    "Place_addr": "248 Glenmore Rd, Sydney, New South Wales",
    "Type": "Coffee Shop"
   },
   "extent": {
    "xmin": 151.22411700000001,
    "ymin": -33.886881000000002,
    "xmax": 151.234117,
    "ymax": -33.876880999999997
   }
  },
  {
   "address": "Bar Bacco",
   "location": {
    "x": 151.22651591900058,
    "y": -33.878369903999612
   },
   "score": 100,
   "attributes": {
    "Match_addr": "Bar Bacco",
    "Place_addr": "McLachlan Ave, Sydney, New South Wales",
    "Type": "Coffee Shop"
   },
   "extent": {
    "xmin": 151.22151600000001,
    "ymin": -33.883370999999997,
    "xmax": 151.231516,
    "ymax": -33.873370999999999
   }
  },
...

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": "Bar Bacco",
   "location": {
    "x": 151.22651591900058,
    "y": -33.878369903999612
   },
   "score": 100,
   "attributes": {
    
   },
   "extent": {
    "xmin": 151.22151600000001,
    "ymin": -33.883370999999997,
    "xmax": 151.231516,
    "ymax": -33.873370999999999
   }
  }
 ]
}

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, California",
   "magicKey": "GST7YMc0AM9UOsE9HhFtGTyVGST7YMc0AM9UOsE9DbTVHgA9HhB0Zcp0OhNtGMytaikZQDNKQ58JM5xtIS9GOghnYnwZGPTq7iAm7Py_CR4PIic2BR4caocpOh9bZgKZQoc3YSyaagDIZhkZOhca1oFF",
   "isCollection": false
  },
  {
   "text": "Esri Island, Sudan",
   "magicKey": "GST7YMc0AM9UOsE9HhFtGTyVGST7YMc0AM9UOsE9DbTVHgA9HhB0Zcp0OhNtGMytaikZQDbJUsbEUFc4Hhp0OSTaSsEqAZ43AP9zJikuGPAmIYxQGPT-CZc0YiD7DsKaCZyAOh5-Dn47Z5E0YT5L",
   "isCollection": false
  },
  {
   "text": "ESRIT, Beograd-Stari Grad, Centralna Srbija, Srbija",
   "magicKey": "GST7YMc0AM9UOsE9HhFtGTyVGST7YMc0AM9UOsE9DbTVHgA9HhB0Zcp0OhNtGMytaikZQBNKUD8JUD8tIS9GOghnYnwZGPTq7iAm7Py_CR4PIic2BR4caocpOh9bZgKZQ1c3YSyaagDIZhkZOhca1oFF",
   "isCollection": false
  },
  {
   "text": "Esri (Thailand) Co., Ltd., Sathon Nuea Rd., Si Lom, Bangkok",
   "magicKey": "GST7YMc0AM9UOsE9HhFtGTyVGST7YMc0AM9UOsE9DbTVHgA9HhB0Zcp0OhNtGMytaikZQDoOQ5NIQBotIS9GOghnYnwZGPTq7iAm7Py_CR4PIic2BR4caocpOh9bZgKZUNc3YSyaagDIZhkZOhca1oFF",
   "isCollection": false
  },
  {
   "text": "Esri (UK), Newman Court, Rotherham, South Yorkshire",
   "magicKey": "GST7YMc0AM9UOsE9HhFtGTyVGST7YMc0AM9UOsE9DbTVHgA9HhB0Zcp0OhNtGMytaikZQsdEQBdOU5wtIS9GOghnYnwZGPTq7iAm7Py_CR4PIic2BR4caocpOh9bZgKZUoc3YSyaagDIZhkZOhca1oFF",
   "isCollection": false
  },
  {
   "text": "Esrimo, Calle Larga 76, La Puebla del Río, Andalucía",
   "magicKey": "GST7YMc0AM9UOsE9HhFtGTyVGST7YMc0AM9UOsE9DbTVHgA9HhB0Zcp0OhNtGMytaikZQskEMsN7Q5dtIS9GOghnYnwZGPTq7iAm7Py_CR4PIic2BR4caocpOh9bZgKZUFc3YSyaagDIZhkZOhca1oFF",
   "isCollection": false
  },
  {
   "text": "Esri Global Inc, Sharjah, Emirates",
   "magicKey": "GST7YMc0AM9UOsE9HhFtGTyVGST7YMc0AM9UOsE9DbTVHgA9HhB0Zcp0OhNtGMytaikZQsbGQ5xIUBwtIS9GOghnYnwZGPTq7iAm7Py_CR4PIic2BR4caocpOh9bZgKZU1c3YSyaagDIZhkZOhca1oFF",
   "isCollection": false
  },
  {
   "text": "Esri Holding Lebanon, Beyrouth, Liban",
   "magicKey": "GST7YMc0AM9UOsE9HhFtGTyVGST7YMc0AM9UOsE9DbTVHgA9HhB0Zcp0OhNtGMytaikZQs8OU5xHQDdtIS9GOghnYnwZGPTq7iAm7Py_CR4PIic2BR4caocpOh9bZgKZMNc3YSyaagDIZhkZOhca1oFF",
   "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 the United States and United Kingdom only using countryCode (with input text esri)

Request URL

Suggest JSON response

{
 "suggestions": [
  {
   "text": "Esri, 380 New York St, Redlands, California",
   "magicKey": "GST7YMc0AM9UOsE9HhFtGTyVGST7YMc0AM9UOsE9DbTVHgA9HhB0Zcp0OhNtGMytaikZQDNKQ58JM5xtIS9GOghnYnwZGPTq7iAm7Py_CR4PIic2BR4caocpOh9bZgKZQoc3YSyaagDIZhkZOhca1oFF",
   "isCollection": false
  },
  {
   "text": "Esri (UK), Newman Court, Rotherham, South Yorkshire",
   "magicKey": "GST7YMc0AM9UOsE9HhFtGTyVGST7YMc0AM9UOsE9DbTVHgA9HhB0Zcp0OhNtGMytaikZQsdEQBdOU5wtIS9GOghnYnwZGPTq7iAm7Py_CR4PIic2BR4caocpOh9bZgKZQFc3YSyaagDIZhkZOhca1oFF",
   "isCollection": false
  },
  {
   "text": "ESRI, 8615 Westwood Center Dr, Vienna, Virginia",
   "magicKey": "GST7YMc0AM9UOsE9HhFtGTyVGST7YMc0AM9UOsE9DbTVHgA9HhB0Zcp0OhNtGMytaikZQDbJU5gIUDVtIS9GOghnYnwZGPTq7iAm7Py_CR4PIic2BR4caocpOh9bZgKZQ1c3YSyaagDIZhkZOhca1oFF",
   "isCollection": false
  },
  {
   "text": "Esri Minneapolis, 880 Blue Gentian Rd, Saint Paul, Minnesota",
   "magicKey": "GST7YMc0AM9UOsE9HhFtGTyVGST7YMc0AM9UOsE9DbTVHgA9HhB0Zcp0OhNtGMytaikZQsdaM5xAMsVtIS9GOghnYnwZGPTq7iAm7Py_CR4PIic2BR4caocpOh9bZgKZUNc3YSyaagDIZhkZOhca1oFF",
   "isCollection": false
  },
  {
   "text": "Esri Olympia, 606 Columbia St NW, Olympia, Washington",
   "magicKey": "GST7YMc0AM9UOsE9HhFtGTyVGST7YMc0AM9UOsE9DbTVHgA9HhB0Zcp0OhNtGMytaikZQsdaQskAQDktIS9GOghnYnwZGPTq7iAm7Py_CR4PIic2BR4caocpOh9bZgKZUoc3YSyaagDIZhkZOhca1oFF",
   "isCollection": false
  },
  {
   "text": "Esri Philadelpiha, 1325 Morris Dr, Wayne, Pennsylvania",
   "magicKey": "GST7YMc0AM9UOsE9HhFtGTyVGST7YMc0AM9UOsE9DbTVHgA9HhB0Zcp0OhNtGMytaikZQsk7UDd7UDVtIS9GOghnYnwZGPTq7iAm7Py_CR4PIic2BR4caocpOh9bZgKZUFc3YSyaagDIZhkZOhca1oFF",
   "isCollection": false
  },
  {
   "text": "Esri Regional Office, 3325 Springbank Ln Charlotte, NC 28226",
   "magicKey": "GST7YMc0AM9UOsE9HhFtGTyVGST7YMc0AM9UOsE9DbTVHgA9HhB0Zcp0OhNtGMytaikZQsdKM5NGQsVtIS9GOghnYnwZGPTq7iAm7Py_CR4PIic2BR4caocpOh9bZgKZU1c3YSyaagDIZhkZOhca1oFF",
   "isCollection": false
  },
  {
   "text": "Esri St Louis, 3060 Little Hills Expy St Charles, MO 63301",
   "magicKey": "GST7YMc0AM9UOsE9HhFtGTyVGST7YMc0AM9UOsE9DbTVHgA9HhB0Zcp0OhNtGMytaikZQsxJQD8JUBNtIS9GOghnYnwZGPTq7iAm7Py_CR4PIic2BR4caocpOh9bZgKZMNc3YSyaagDIZhkZOhca1oFF",
   "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 County, Idaho, United States",
   "magicKey": "GST7YMc0AM9UOsE9HhFtGTyVGST7YMc0AM9UOsE9DbTVHgA9HhB0Zcp0OhNtGMytaikZU5wJM587Uoc4Hhp0OSTaSsEqAZ43AP9zJikuGPAmIYxQGPT-CZc0YiD7DsKJCZyAOh5-Dn47Z5EVOg9a",
   "isCollection": false
  },
  {
   "text": "Bear, Delaware, United States",
   "magicKey": "GST7YMc0AM9UOsE9HhFtGTyVGST7YMc0AM9UOsE9DbTVHgA9HhB0Zcp0OhNtGMytaikZQDgIQ5xJMoc4Hhp0OSTaSsEqAZ43AP9zJikuGPAmIYxQGPT-CZc0YiD7DsKaCZyAOh5-Dn47Z5EVOg9a",
   "isCollection": false
  },
  {
   "text": "Beardstown, Illinois, United States",
   "magicKey": "GST7YMc0AM9UOsE9HhFtGTyVGST7YMc0AM9UOsE9DbTVHgA9HhB0Zcp0OhNtGMytaikZU5baMsVHMoc4Hhp0OSTaSsEqAZ43AP9zJikuGPAmIYxQGPT-CZc0YiD7DsKACZyAOh5-Dn47Z5EVOg9a",
   "isCollection": false
  },
  {
   "text": "Bear Valley Springs, California, United States",
   "magicKey": "GST7YMc0AM9UOsE9HhFtGTyVGST7YMc0AM9UOsE9DbTVHgA9HhB0Zcp0OhNtGMytaikZU5oOU5bHQNc4Hhp0OSTaSsEqAZ43AP9zJikuGPAmIYxQGPT-CZc0YiD7DsKGCZyAOh5-Dn47Z5EVOg9a",
   "isCollection": false
  },
  {
   "text": "Bear Creek, Alaska, United States (City)",
   "magicKey": "GST7YMc0AM9UOsE9HhFtGTyVGST7YMc0AM9UOsE9DbTVHgA9HhB0Zcp0OhNtGMytaikZUs8OMsbAU1c4Hhp0OSTaSsEqAZ43AP9zJikuGPAmIYxQGPT-CZc0YiD7DsK7CZyAOh5-Dn47Z5EVOg9a",
   "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": "Bear Creek Mountain Resort, 101 Doe Mountain Ln, Macungie, Pennsylvania",
   "magicKey": "GST7YMc0AM9UOsE9HhFtGTyVGST7YMc0AM9UOsE9DbTVHgA9HhB0Zcp0OhNtGMytaikZQDNOQswIQsVtIS9GOghnYnwZGYn-CR52GYTk7NcpOh9bZgKZQoc3YSyaagDIZhkZHMyvYFFF",
   "isCollection": false
  },
  {
   "text": "Bear Mountain, 43101 Goldmine Dr, Big Bear Lake, California",
   "magicKey": "GST7YMc0AM9UOsE9HhFtGTyVGST7YMc0AM9UOsE9DbTVHgA9HhB0Zcp0OhNtGMytaikZQDNKQsgHUsgtIS9GOghnYnwZGYn-CR52GYTk7NcpOh9bZgKZQFc3YSyaagDIZhkZHMyvYFFF",
   "isCollection": false
  },
  {
   "text": "Bear Paw Ski Bowl, Big Sandy Creek Rd, Box Elder, Montana",
   "magicKey": "GST7YMc0AM9UOsE9HhFtGTyVGST7YMc0AM9UOsE9DbTVHgA9HhB0Zcp0OhNtGMytaikZQDN7U5g7MsotIS9GOghnYnwZGYn-CR52GYTk7NcpOh9bZgKZQ1c3YSyaagDIZhkZHMyvYFFF",
   "isCollection": false
  },
  {
   "text": "Bear Peak, Grand Summit Rd, Bartlett, New Hampshire",
   "magicKey": "GST7YMc0AM9UOsE9HhFtGTyVGST7YMc0AM9UOsE9DbTVHgA9HhB0Zcp0OhNtGMytaikZQsdaUs8IUBdtIS9GOghnYnwZGYn-CR52GYTk7NcpOh9bZgKZUNc3YSyaagDIZhkZHMyvYFFF",
   "isCollection": false
  },
  {
   "text": "Bear Valley Mountain Resort, Mt Reba Rd, Markleeville, California",
   "magicKey": "GST7YMc0AM9UOsE9HhFtGTyVGST7YMc0AM9UOsE9DbTVHgA9HhB0Zcp0OhNtGMytaikZQDNKQsk7MsVtIS9GOghnYnwZGYn-CR52GYTk7NcpOh9bZgKZUoc3YSyaagDIZhkZHMyvYFFF",
   "isCollection": false
  }
 ]
}

See Category filtering for complete details.

Suggest limitation

In some cases, findAddressCandidates may return a different match than the selected suggestion item. This happens specifically when the input string for which a suggestion item is generated is an address with a house number that doesn't actually exist for the street. As an example, suppose a user types 5975 New York St Redlands in a search box, resulting in suggestion item 5975 New York St, Redlands, California, USA, which they select. When this addresses is geocoded using findAddressCandidates, it results in a street name match: New York St, Redlands, California, 92373. Why does findAddressCandidates return a different result than suggest, and why does suggest provide a suggestion item with a nonexistent street address in the first place?

The answer is related to performance. Recall the way that the suggest operation works—it compares an input string against strings in an index; the indexed terms represent a global database of addresses and places. This comparison is repeated for each keystroke as a user types, meaning that the index must be searched and suggestion results returned almost instantaneously. From a performance standpoint, this would not be possible if all valid house numbers for every street in the world were stored in the index, because the index would be greatly inflated. For this reason, only street names are indexed. When a house number and street name combination is passed to suggest, it finds the input street name in the index and appends the input house number to the street name in the suggestion item. If the house number that is sent to suggest is invalid, the scenario described in the preceding paragraph can result.