The /suggest request autocompletes input text and return place names and addresses. For example, you can search for "New Y", "Dodgers S", and "Cali" to get a list of suggested place names that match.
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 find 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 Dakota380 New York St, Redlands, CA 92373
-
Street intersections
New York St and W Redlands Blvd, Redlands, CAJacques Veltmanstraat & Pieter Calandlaan, Amsterdam, NLD
-
Points of interest (POI) by name
DisneylandStarbucksMount Everest
-
POI by type
amusement parkcoffeegas station
-
Administrative place-names, such as city, county, state, province, or country names
SeattleState of MahārāshtraLiechtenstein
-
Postal codes
92591TW9 1 DN
Additionally, the suggest operation uses the same proximity algorithm as the find operation.
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
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 magic values for that suggestion can be passed with a find request as the values for the Single and magic input parameters, respectively:
https
Query parameters
| Name | Required | Type | Default | Description |
|---|---|---|---|---|
string | The request response format, either | |||
string | An access token with the required privileges. | |||
string | The input text. | |||
string | point | The origin point used to favor geocoding candidates based on their proximity to the location. | |||
string | The place or address type that can be used to filter results. | |||
The set of bounding box coordinates that limits the search area. | ||||
number | The maximum number of suggestions to be returned in a response. | |||
string | Limits the returned suggestions to a specific country. | |||
string | Limits the candidates returned to the specified country or countries. | |||
string | Returns specified address component values included in output fields. | |||
boolean |
| Prevents collections from being returned in the response. |
Required parameters
token
An access token with the required privileges.
- ArcGIS Location Platform: premium:user:geocode:temporary or premium:user:geocode:stored
- ArcGIS Online: premium:user:geocode or premium:user:geocode:stored
token=<ACCESS_TOKEN>To use HTTP headers instead of the token parameter, set the following:
GET <SERVICE_REQUEST> HTTP/1.1
Host: <SERVICE_DOMAIN>
X-Esri-Authorization: Bearer <ACCESS_TOKEN>Learn more about access tokens and privileges in the Security and authentication developer guide.
text
The input text entered by a user, which is used by the suggest operation to generate a list of possible matches.
Example
text=starbuOptional 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.
Example using simple syntax (WGS84)
location=-117.196,34.056JSON 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 details about the category parameter.
Example of category filtering with a single category
category=AddressExample of category filtering with multiple categories
category=Address,PostalsearchExtent
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 search 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,41Example 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 max is not included in the suggest request, the default value is 5.
Example
maxSuggestions=10countryCode
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.
Example
countryCode=USAsourceCountry
Similar to country , the source parameter limits the suggestions to the specified country or countries. For example, if source 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.
Example: Single country
sourceCountry=USAExample: Multiple countries
sourceCountry=FRA,DEU,ESPpreferredLabelValues
The preferred 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.
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, O , 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 preferred parameter can be used for this purpose. For the previous example, if preferred 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
preferredis invalid.Label Values=matched City,postal City - The
preferredparameter 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 theLabel Values preferredparameter passed in the request. The idea is for suggestions to reflect the user input as much as possible, and this takes precedence over theLabel Values preferredparameter.Label Values
Example: Include local city name in suggestion
preferredLabelValues=localCityreturnCollections
The return 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=falseResponse status
| Status | Meaning | Description | Schema |
|---|---|---|---|
200 | OK | A successful response for a | Inline |
400 | Bad request | Invalid query parameters. Learn more in Service output. | |
403 | Forbidden | The required paramter | |
5 | Unknown | An error occured on the server. Learn more in Service output. |
Go to Service output for extended codes.
Response details
{
"suggestions": [
{
"text": "<SuggestionText1>",
"magicKey": "<MagicKey1>",
"isCollection": "<IsCollection1>"
},
{
"text": "<SuggestionText2>",
"magicKey": "<MagicKey2>",
"isCollection": "<IsCollection2>"
},
{
"text": "<SuggestionText3>",
"magicKey": "<MagicKey3>",
"isCollection": "<IsCollection3>"
},
{
"text": "<SuggestionText4>",
"magicKey": "<MagicKey4>",
"isCollection": "<IsCollection4>"
},
{
"text": "<SuggestionText5>",
"magicKey": "<MagicKey5>",
"isCollection": "<IsCollection5>"
}
]
}
Go to Service output for more details about suggest responses.
Examples
Get suggestions using location
As with the find 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.
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 search 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.
GET https://geocode-api.arcgis.com/arcgis/rest/services/World/GeocodeServer/suggest?text=treas&location=-115.172783,36.114789&f=pjson&token=<ACCESS_TOKEN>Get suggestions without location
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 search parameter.
GET https://geocode-api.arcgis.com/arcgis/rest/services/World/GeocodeServer/suggest?text=treas&f=pjson&token=<ACCESS_TOKEN>Limit suggestions to a specified area
Unlike the location parameter, the search 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 search 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 search 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 search parameter in a suggest request, only suggestions beginning with Main St in Kansas City are returned.
Get suggestions using searchExtent
GET https://geocode-api.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>Get suggestions using searchExtent with a JSON envelope object
You can specify a spatial reference for search , 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 search 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.
GET https://geocode-api.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>Utilize the isCollection property
The is property is a Boolean flag that indicates the type of suggestion item returned by a suggest request. When is , 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 is , 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 magic pair for which is is sent in a find 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 is , 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.
Get the isCollection property
GET https://geocode-api.arcgis.com/arcgis/rest/services/World/GeocodeServer/suggest?text=coffee&location=151.229129,-33.879741&f=pjson&token=<ACCESS_TOKEN>Using a suggest result when isCollection=true
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 search parameter.
In this example, note that is for the first suggestion item Coffee Shop . The text and magic 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 magic combinations of the rest of the items, for which is , represent the names of coffee shops that are within 5,000 meters of the location.
When the text and magic combination of the item for which is is sent to the ArcGIS Geocoding service in a find request, with max , several coffee shops are returned.
GET https://geocode-api.arcgis.com/arcgis/rest/services/World/GeocodeServer/findAddressCandidates?singleLine=Coffee Shop&magicKey=dHA9MiN0dj00Yjg3MGE5MSNubT1Db2ZmZWUgU2hvcCNzej0xNTEuMjI5MTI5Oi0zMy44Nzk3NDEwMDAwMDAwMDMjY3M9NzAjbG49V29ybGQ=&maxLocations=10&outFields=Match_addr,Place_addr,Type&f=pjson&token=<ACCESS_TOKEN>A developer can use the is property to properly handle cases such as this in their application. Specifically, for cases in which is , the max parameter should be included in the corresponding find 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 is , the max parameter should be set to 1 .
Use a suggest result when isCollection=false
It is important to note that if max had not been explicitly passed in the find request, up to 50 candidates would have been returned, because the find operation returns all matching candidates (up to the maximum allowed by the service) in the absence of the max parameter. Also note that the JSON response shown here has been truncated to preserve space.
If the text and magic combination of any of the items for which is are passed in a find request, in most cases only a single candidate is returned.
GET https://geocode-api.arcgis.com/arcgis/rest/services/World/GeocodeServer/findAddressCandidates?singleLine=Coffee Tea & Me, 87 Macleay St, Elizabeth Bay, Sydney, New South Wales, 2011, AUS&magicKey=dHA9MCN0dj00Yjg3MGE5MSNsb2M9MzY3OTgzMjIjbG5nPTQyI3BsPTM3NzA2MDg1I2ZhPTIwOTcxNTIjbGJzPTE0OjE5MDc5ODIwI2xuPVdvcmxk&f=pjson&token=<ACCESS_TOKEN>A developer can use the is property to properly handle cases such as this in their application. Specifically, for cases in which is , the max parameter should be included in the corresponding find 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 is , the max parameter should be set to 1 .
Disable collections
If collections are not needed for your application, you can use the return parameter to prevent them from being returned in suggest responses. Specifically, if return is included in a suggest request, only suggestion items with is are returned in the response. Collections are returned by default for suggest , so return must be included in the suggest request to disable this feature.
Disable collections by using returnCollections=false
GET https://geocode-api.arcgis.com/arcgis/rest/services/World/GeocodeServer/suggest?text=w&location=-77.043,38.91&returnCollections=false&f=pjson&token=<ACCESS_TOKEN>Enable collections by using returnCollections=true
By contrast, when return for the same request, the top suggestion is collection "Whole Foods", which is a supermarket chain.
GET https://geocode-api.arcgis.com/arcgis/rest/services/World/GeocodeServer/suggest?text=w&location=-77.043,38.91&returnCollections=true&f=pjson&token=<ACCESS_TOKEN>Specify 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 max parameter to choose the amount of suggestions that works for you.
GET https://geocode-api.arcgis.com/arcgis/rest/services/World/GeocodeServer/suggest?text=esri&maxSuggestions=8&f=pjson&token=<ACCESS_TOKEN>Limit suggestions by country
By default, the ArcGIS Geocoding service returns suggestions from any relevant country based on the input text, unless the location or search parameters are used. These parameters do not strictly filter by country, however. To do so, the country parameter should be used. It allows you to limit the suggestions to one or more specific countries.
GET https://geocode-api.arcgis.com/arcgis/rest/services/World/GeocodeServer/suggest?text=esri&countryCode=IDN&f=pjson&token=<ACCESS_TOKEN>Filter categories
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.
Get suggestions for "Bear" without category
GET https://geocode-api.arcgis.com/arcgis/rest/services/World/GeocodeServer/suggest?text=bear&category=&f=pjson&token=<ACCESS_TOKEN>See Category filtering for details.
The solution for this case is to pass the category parameter in the request. By including category= 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.
Get suggestions for "Bear" with category=Ski Resort
GET https://geocode-api.arcgis.com/arcgis/rest/services/World/GeocodeServer/suggest?text=bear&category=Ski Resort&f=pjson&token=<ACCESS_TOKEN>See Category filtering for details.
Use the preferredLabelValues parameter with suggest
The preferred 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 preferred 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 preferred 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):
Return suggestions without using preferredLabelValues
GET https://geocode-api.arcgis.com/arcgis/rest/services/World/GeocodeServer/suggest?text=9001 W 62nd St&preferredLabelValues=&f=pjson&token=<ACCESS_TOKEN>The preferred parameter can be used to return a more suitable city name for this address in suggestions. Pass preferred in the suggest request to return Merriam as the city name in suggestions (refer to the top suggestion in the response for this example):
Return suggestions using preferredLabelValues=localCity
GET https://geocode-api.arcgis.com/arcgis/rest/services/World/GeocodeServer/suggest?text=9001 W 62nd St&preferredLabelValues=localCity&f=pjson&token=<ACCESS_TOKEN>However, if you start typing Mission as the city name for the same input, like this—9001 W 62nd St Mi —also with preferred , postal city name Mission is used in suggestions instead of local city name Merriam, even though local 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 preferred parameter (refer to the top suggestion in the response for this example).
Return suggestions using preferredLabelValues=localCity
GET https://geocode-api.arcgis.com/arcgis/rest/services/World/GeocodeServer/suggest?f=pjson&text=9001 W 62nd St Mi&preferredLabelValues=localCity&f=pjson&token=<ACCESS_TOKEN>When the preferred parameter is used for suggest , it should also be used in the corresponding find 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 find with preferred included in the request, the resulting response will include Merriam as the city name in labels instead of Mission. This is because find always honors the preferred parameter, unlike suggest , for which matching the user input is prioritized:
Use findAddressCandidates with magicKey when preferredLabelValues=localCity
GET https://geocode-api.arcgis.com/arcgis/rest/services/World/GeocodeServer/findAddressCandidates?outFields=Match_addr,City&f=pjson&singleline=9001 W 62nd St, Mission, KS, 66202, USA&magicKey=dHA9NCN0dj00Yjg3MGE5MSNubT05MDAxIFcgNjJuZCBTdCwgTWlzc2lvbiwgS1MsIDY2MjAyLCBVU0EjbG5nPTQyI2xuPVdvcmxk&preferredLabelValues=localCity&token=<ACCESS_TOKEN>Refer to the findAddressCandidates topic for more information about how the preferred parameter can be used with that operation.