Suggest

Description

The suggest operation is performed on a geocode service resource. The result of this operation is a resource representing a list of suggested matches for the input text. This resource provides the matching text as well as a unique ID value, which links a suggestion to a specific place or address.

A geocode service must meet the following requirements to support the suggest operation:

The suggest operation allows character-by-character auto-complete 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. A client application can provide a list of suggestions that is updated with each character typed by a user until the address they are looking for appears in the list.

You can provide arguments to the suggest operation as query parameters defined in the following parameters table:

Request parameters

Parameter

Details

text

Description: The input text provided by a user that is used by the suggest operation to generate a list of possible matches. This is a required parameter.

Example: text=starbu

location

Description: Defines an origin point location that is used with the distance parameter to sort suggested 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 wants 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 a distance is not specified, it defaults to 2000 meters.

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

Example using basic 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

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

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

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 two miles): distance=3218.69

searchExtent

This option was added at 10.4.

Description: 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 searches 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 spatial reference: searchExtent=-104,35.6,-94.32,41

Example with spatial reference: searchExtent= { "xmin": -13052769, "ymin": 3951172, "xmax": -13019630, "ymax": 3978490, "spatialReference": { "wkid": 3395 } }

maxSuggestions

This option was added at 10.4.

Description: The maximum number of suggestions returned by a suggest operation, up to the maximum number allowed by the service. The maximum suggestions value can be modified in the source address locator. If maxSuggestions is not included in the suggest request, the default value is 5.

Example: maxSuggestions=10

countryCode

This option was added at 10.4.

Description: Limits the returned suggestions to values in a particular country.

Example: countryCode=USA

f

Description: The response format. The default response format is html.

Values: html | json

Example: f=json

category

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

Response properties

Property

Details

text

Description: The suggestion text, which can be used in a client application to populate a list of suggestions as a user types characters in a search text box.

Up to five text/magicKey pairs are returned in a suggest response.

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

magicKey

Description: A unique ID, which along with the text parameter, links a suggestion to a specific address or place.

Up to five text/magicKey pairs are returned in a suggest response.

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

isCollection

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

The isCollection property is only supported by the ArcGIS Online World Geocoding Service. For all other services, isCollection=false is always returned by suggest.

Example usage

Get suggestions for disney:

http://gisserver.domain.com:6080/arcgis/rest/services/myService/GeocodeServer/suggest?text=disney&location=-117.196171,34.057576&distance=10000&f=pjson

JSON response syntax

{"suggestions" : [ { "text" : "<text1>", "magicKey" : "<magicKey1>", "isCollection" : <true | false> }, { "text" : "<text 2>", "magicKey" : "<magicKey 2>", "isCollection" : <true | false> } ] }

JSON response example

{
 "suggestions": [
  {
   "text": "Disneyland, Anaheim, California, United States",
   "magicKey": "GST7YMc0AM9UOsKtGTyVGST7YMc0AM9UOsE9HhBzOhcGEZhqART4IjTmDbA81gyQOcbtGMytaikZUDkAQNFF",
   "isCollection": false
  },
  {
   "text": "Disney Store, San Bernardino, California, United States",
   "magicKey": "GST7YMc0AM9UOsKtGTyVGST7YMc0AM9UOsE9HhBzOhcGEZhqART4IjTmDbA81gyQOcbtGMytaikZQsoEU5oK",
   "isCollection": false
  },
  {
   "text": "Disney, Moreno Valley, California, United States",
   "magicKey": "GST7YMc0AM9UOsKtGTyVGST7YMc0AM9UOsE9HhBzOhcGEZhqART4IjTmDbA81gyQOcbtGMytaikZQsoKU5x7",
   "isCollection": false
  },
  {
   "text": "Disney California Adventure, Anaheim, California, United States",
   "magicKey": "GST7YMc0AM9UOsKtGTyVGST7YMc0AM9UOsE9HhBzOhcGEZhqART4IjTmDbA81gyQOcbtGMytaikZQsbKUDxK",
   "isCollection": false
  },
  {
   "text": "Disney CA Adventure-I-5 North Ent, Anaheim, California, United States",
   "magicKey": "GST7YMc0AM9UOsKtGTyVGST7YMc0AM9UOsE9HhBzOhcGEZhqART4IjTmDbA81gyQOcbtGMytaikZQB8HUBoA",
   "isCollection": false
  }
 ]
}

3/3/2017