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.
Access the services
To access the geocoding service you need the following:
- An ArcGIS Location Platform account or ArcGIS Online account.
- An access token (API key or OAuth 2.0) with the appropriate privilege.
Request URL
https
For more information about constructing a request, including how to choose which endpoint to use, refer to the Geocoding service overview.
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=starbuf
The service supports responses in JSON or PJSON format. You can specify the response format using the f parameter.
Example
f=pjsonOptional 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=falseSuggest output
The response returned by a suggest request is composed of an array of suggestions; each suggestion contains the suggestion text , a magic value, and the is flag. A maximum of five suggestions are included in the suggestions array.
Output properties
text
The suggestion text can be used in a client application to populate a list of suggestions as a user enters characters in a search text box.
It can also be included with magic in a find request to quickly retrieve a geosearch candidate.
Example
"text": Starbucks, 1265 Alabama St, Redlands, CaliforniamagicKey
An ID attribute value that, along with the text attribute, links a suggestion to an address or place.
After you make a suggest request, the typical workflow is to pass the text (as the Single parameter value) and magic values in a find request, which retrieves the result in less time than passing in a Single value by itself.
Example
"magicKey": JS91CYhQDS5vDPhvSMyGZby0YFbaUDoaM5bHMoFFisCollection
A Boolean parameter that indicates whether the suggestion item represents a collection of places, as opposed to a specific place.
If is 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 , Mc , Gas Station , and Airport will have is .
If is , the suggestion item represents a specific place-name or address; suggestion items such as Disneyland or 380 New York St, Redlands, CA will have is .
This flag can be used by application developers to apply different behavior to cases in which is is true versus cases in which is is false .
Example (for POI categories and common place-names)
"isCollection": trueExample (for street addresses, postal codes, admin places, and POI's)
"isCollection": falseWorking with suggestions
In broad terms, the suggestions engine compares tokens in the input text with indexed terms for each address and place in the service, and returns the closest matches. The input parameters included in the request affect the results. For instance, including the location parameter in the request influences the results to favor places near the defined location.
The suggestions functionality is accessed through the following URL:
https
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 magic values for that suggestion can be passed with a find request as the values for the Single and magic input parameters, respectively:
https
Using proximity with suggestions
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.
Example
Get suggestions using location
Request URL
https://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer/suggest?text=treas&location=-115.172783,36.114789&f=pjson&token=<ACCESS_TOKEN>JSON response
{
"suggestions": [
{
"text": "Treasure Island, 3300 Las Vegas Blvd S, Las Vegas, NV, 89109, USA",
"magicKey": "dHA9MCN0dj00Yjg3MGE5MSNsb2M9MTA3NTQwMDYjbG5nPTQyI3BsPTEwMDk3NzM3I2ZhPTExNzk2NDgjbGJzPTE0OjcyNDc0OTA1I2xuPVdvcmxk",
"isCollection": false
},
{
"text": "Treasure Island Wedding Chapels, 3300 Las Vegas Blvd S, Las Vegas, NV, 89109, USA",
"magicKey": "dHA9MCN0dj00Yjg3MGE5MSNsb2M9MTA4MDA0MTEjbG5nPTQyI3BsPTEwMTU5NDMzI2ZhPTIwOTcxNTIjbGJzPTE0OjcyNDc1MDc2I2xuPVdvcmxk",
"isCollection": false
},
{
"text": "Treasure Island Pool, 3300 Las Vegas Blvd S, Las Vegas, NV, 89109, USA",
"magicKey": "dHA9MCN0dj00Yjg3MGE5MSNsb2M9MTA4MDA0MTEjbG5nPTQyI3BsPTEwMTU5NTg5I2ZhPTIwOTcxNTIjbGJzPTE0OjcyNDc1MDM0I2xuPVdvcmxk",
"isCollection": false
},
{
"text": "Treasure Island Wedding Chapel, 3300 Las Vegas Blvd S, Las Vegas, NV, 89109, USA",
"magicKey": "dHA9MCN0dj00Yjg3MGE5MSNsb2M9MTA3NTQwMDYjbG5nPTQyI3BsPTEwMDk3ODI4I2ZhPTY1NTM2I2xicz0xNDo3MjQ3NTA3NSNsbj1Xb3JsZA==",
"isCollection": false
},
{
"text": "Treasure Island At The Mirage, 3300 Las Vegas Blvd S, Las Vegas, NV, 89109, USA",
"magicKey": "dHA9MCN0dj00Yjg3MGE5MSNsb2M9MTA4MDA0MTEjbG5nPTQyI3BsPTEwMTU4NTA3I2ZhPTIwOTcxNTIjbGJzPTE0OjcyNDc0OTIyI2xuPVdvcmxk",
"isCollection": false
}
]
}It is important to note that proximity search does not filter out results that are far from the input location—it is intended to influence the sort order of results so the most locationally relevant matches are returned first. For instance, if your location is in Seattle and you type Mount Ver , the first suggestion in the list is Mount Vernon, Washington, United States. The second is Mount Vernon, Westchester County, New York, United States. So even though Mount Vernon in New York is far from Seattle, it is still returned because it is the second most relevant candidate based on its distance from the location and its rank. To limit suggestions to a specific area, use the 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.
Example
Get suggestions without location
Request URL
https://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer/suggest?text=treas&f=pjson&token=<ACCESS_TOKEN>JSON response
{
"suggestions": [
{
"text": "Treasure County, MT, USA",
"magicKey": "dHA9MCN0dj00Yjg3MGE5MSNsb2M9MTA0NDQ5NTQjbG5nPTQyI3BsPTk4MjQzODUjbGJzPTE0OjcyNDc0NTc1I2xuPVdvcmxk",
"isCollection": false
},
{
"text": "Treas, Banteay Meanchey, KHM",
"magicKey": "dHA9MCN0dj00Yjg3MGE5MSNsb2M9NjIxNjc1NzkjbG5nPTQyI3BsPTgwNzg0MjgzI2xicz0xNDo3MjQ3MzkwNiNsbj1Xb3JsZA==",
"isCollection": false
},
{
"text": "Treasure Island, FL, USA",
"magicKey": "dHA9NCN0dj00Yjg3MGE5MSNubT1UcmVhc3VyZSBJc2xhbmQsIEZMLCBVU0EjbG5nPTQyI2xuPVdvcmxk",
"isCollection": false
},
{
"text": "Treascon, Portarlington, Laois, IRL",
"magicKey": "dHA9MCN0dj00Yjg3MGE5MSNsb2M9NjA2MDc0MzAjbG5nPTQyI3BsPTc3NDMyNzUyI2xicz0xNDo3MjQ3MzkzOSNsbj1Xb3JsZA==",
"isCollection": false
},
{
"text": "Treascon, Portarlington, Offaly, IRL",
"magicKey": "dHA9MCN0dj00Yjg3MGE5MSNsb2M9NjA2NjI5MzYjbG5nPTQyI3BsPTc3NDY3ODQyI2xicz0xNDo3MjQ3MzkzOSNsbj1Xb3JsZA==",
"isCollection": false
}
]
}It is important to note that proximity search does not filter out results that are far from the input location—it is intended to influence the sort order of results so the most locationally relevant matches are returned first. For instance, if your location is in Seattle and you type Mount Ver , the first suggestion in the list is Mount Vernon, Washington, United States. The second is Mount Vernon, Westchester County, New York, United States. So even though Mount Vernon in New York is far from Seattle, it is still returned because it is the second most relevant candidate based on its distance from the location and its rank. To limit suggestions to a specific area, use the search parameter.
Limiting 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.
Example
Get suggestions using search
Request URL
https://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer/suggest?text=main st&category=&searchExtent=-94.602026,39.083630,-94.570151,39.109774&location=&f=pjson&token=<ACCESS_TOKEN>JSON response
{
"suggestions": [
{
"text": "Main St, Kansas City, MO, 64108, USA",
"magicKey": "dHA9MCN0dj00Yjg3MGE5MSNsb2M9OTkxNTk3MCNsbmc9NDIjbGJzPTEwOTo5MjM0ODAzNSNsbj1Xb3JsZA==",
"isCollection": false
},
{
"text": "Main St, Kansas City, MO, 64106, USA",
"magicKey": "dHA9NCN0dj00Yjg3MGE5MSNubT1NYWluIFN0LCBLYW5zYXMgQ2l0eSwgTU8sIDY0MTA2LCBVU0Ejc3o9LTk0LjU4NjA4ODQ5OTk5OTk4ODozOS4wOTY3MDIwMDAwMDAwMDE7LTk0LjYwMjAyNTk5OTk5OTk5NTozOS4wODM2Mjk5OTk5OTk5OTk6LTk0LjU3MDE1MDk5OTk5OTk5NjozOS4xMDk3NzQwMDAwMDAwMDIjbG5nPTQyI2xuPVdvcmxk",
"isCollection": false
},
{
"text": "Main St, Kansas City, MO, 64105, USA",
"magicKey": "dHA9NCN0dj00Yjg3MGE5MSNubT1NYWluIFN0LCBLYW5zYXMgQ2l0eSwgTU8sIDY0MTA1LCBVU0Ejc3o9LTk0LjU4NjA4ODQ5OTk5OTk4ODozOS4wOTY3MDIwMDAwMDAwMDE7LTk0LjYwMjAyNTk5OTk5OTk5NTozOS4wODM2Mjk5OTk5OTk5OTk6LTk0LjU3MDE1MDk5OTk5OTk5NjozOS4xMDk3NzQwMDAwMDAwMDIjbG5nPTQyI2xuPVdvcmxk",
"isCollection": false
}
]
}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.
Example
Get suggestions using search with a JSON envelope object
Request URL
https://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer/suggest?text=main st&searchExtent={"xmin":-10531043,"ymin":4733652,"xmax":-10527501,"ymax":4737408,"spatialReference":{"wkid":102100}}&outSR=102100&f=pjson&token=<ACCESS_TOKEN>JSON response
{
"suggestions": [
{
"text": "Main St, Kansas City, MO, 64108, USA",
"magicKey": "dHA9MCN0dj00Yjg3MGE5MSNsb2M9OTkxNTk3MCNsbmc9NDIjbGJzPTEwOTo5MjM0ODAzNSNsbj1Xb3JsZA==",
"isCollection": false
},
{
"text": "Main St, Kansas City, MO, 64106, USA",
"magicKey": "dHA9NCN0dj00Yjg3MGE5MSNubT1NYWluIFN0LCBLYW5zYXMgQ2l0eSwgTU8sIDY0MTA2LCBVU0Ejc3o9LTk0LjU4NjA1OTY4MjUxNzIxNzozOS4wOTY2ODEzNjU5NzUwNzM7LTk0LjYwMTk2ODg0NjE5ODk3MjozOS4wODM1ODg1NjY5MjkwNTk6LTk0LjU3MDE1MDUxODgzNTQ2MjozOS4xMDk3NzQxNjUwMjEwODYjbG5nPTQyI2xuPVdvcmxk",
"isCollection": false
},
{
"text": "Main St, Kansas City, MO, 64105, USA",
"magicKey": "dHA9NCN0dj00Yjg3MGE5MSNubT1NYWluIFN0LCBLYW5zYXMgQ2l0eSwgTU8sIDY0MTA1LCBVU0Ejc3o9LTk0LjU4NjA1OTY4MjUxNzIxNzozOS4wOTY2ODEzNjU5NzUwNzM7LTk0LjYwMTk2ODg0NjE5ODk3MjozOS4wODM1ODg1NjY5MjkwNTk6LTk0LjU3MDE1MDUxODgzNTQ2MjozOS4xMDk3NzQxNjUwMjEwODYjbG5nPTQyI2xuPVdvcmxk",
"isCollection": false
}
]
}Utilizing 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.
Example
Using the is property
Request URL
https://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer/suggest?text=coffee&location=151.229129,-33.879741&f=pjson&token=<ACCESS_TOKEN>Suggest JSON response
{
"suggestions": [
{
"text": "Coffee Shop",
"magicKey": "dHA9MiN0dj00Yjg3MGE5MSNubT1Db2ZmZWUgU2hvcCNzej0xNTEuMjI5MTI5Oi0zMy44Nzk3NDEwMDAwMDAwMDMjY3M9NzAjbG49V29ybGQ=",
"isCollection": true
},
{
"text": "Coffee Tea & Me, 87C Macleay Street, Elizabeth Bay, Sydney, New South Wales, 2011, AUS",
"magicKey": "dHA9MCN0dj00Yjg3MGE5MSNsb2M9MzY3OTgzMjIjbG5nPTQyI3BsPTM3NzA2MDg1I2ZhPTIwOTcxNTIjbGJzPTE0OjE5MDc5ODIwI2xuPVdvcmxk",
"isCollection": false
},
{
"text": "Coffee Pros, 144-150 Liverpool Street, East Sydney, Sydney, New South Wales, 2010, AUS",
"magicKey": "dHA9MCN0dj00Yjg3MGE5MSNsb2M9MzY3OTQ4MjgjbG5nPTQyI3BsPTM3Njk3NzA1I2ZhPTExNzk2NDgjbGJzPTE0OjE5MDc4MDIyI2xuPVdvcmxk",
"isCollection": false
},
{
"text": "Coffee Tea & Me, 224 Oxford Street, Bondi Junction, Sydney, New South Wales, 2022, AUS",
"magicKey": "dHA9MCN0dj00Yjg3MGE5MSNsb2M9MzY3ODQ1MTUjbG5nPTQyI3BsPTM3NjY3OTI4I2ZhPTM4NjY2MjQjbGJzPTE0OjE5MDc5ODIwI2xuPVdvcmxk",
"isCollection": false
},
{
"text": "Coffee In A Cone Food, 481 Crown Street, Surry Hills, Sydney, New South Wales, 2010, AUS",
"magicKey": "dHA9MCN0dj00Yjg3MGE5MSNsb2M9MzY4MzcxODIjbG5nPTQyI3BsPTM3ODA4NTYzI2ZhPTQ1ODc1MjAjbGJzPTE0OjE5MDc1NDAzI2xuPVdvcmxk",
"isCollection": false
}
]
}It is important to note that proximity search does not filter out results that are far from the input location—it is intended to influence the sort order of results so the most locationally relevant matches are returned first. For instance, if your location is in Seattle and you type Mount Ver , the first suggestion in the list is Mount Vernon, Washington, United States. The second is Mount Vernon, Westchester County, New York, United States. So even though Mount Vernon in New York is far from Seattle, it is still returned because it is the second most relevant candidate based on its distance from the location and its rank. To limit suggestions to a specific area, use the 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.
Example
Using a suggest result in a find request when is
Request URL
https://geocode.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>findAddressCandidates JSON response
{
"spatialReference": {
"wkid": 4326,
"latestWkid": 4326
},
"candidates": [
{
"address": "Scramble & Bean",
"location": {
"x": 151.2284146,
"y": -33.8752326
},
"score": 100,
"attributes": {
"Match_addr": "Scramble & Bean",
"Type": "Coffee Shop",
"Place_addr": "13-19 Waratah Street, Rushcutters Bay, Sydney, New South Wales, 2011"
},
"extent": {
"xmin": 151.2234146,
"ymin": -33.8802326,
"xmax": 151.2334146,
"ymax": -33.8702326
}
},
{
"address": "Bayswater Bru",
"location": {
"x": 151.22344,
"y": -33.87525
},
"score": 100,
"attributes": {
"Match_addr": "Bayswater Bru",
"Type": "Coffee Shop",
"Place_addr": "17 Bayswater Road, Kings Cross, Sydney, New South Wales, 2011"
},
"extent": {
"xmin": 151.21844,
"ymin": -33.88025,
"xmax": 151.22844,
"ymax": -33.87025
}
}A developer can use the 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 .
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.
Example
Using a suggest result in a find request when is
Request URL
https://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer/findAddressCandidates?singleLine=Coffee Tea & Me, 87 Macleay St, Elizabeth Bay, Sydney, New South Wales, 2011, AUS&magicKey=dHA9MCN0dj00Yjg3MGE5MSNsb2M9MzY3OTgzMjIjbG5nPTQyI3BsPTM3NzA2MDg1I2ZhPTIwOTcxNTIjbGJzPTE0OjE5MDc5ODIwI2xuPVdvcmxk&f=pjson&token=<ACCESS_TOKEN>findAddressCandidates JSON response
{
"spatialReference": {
"wkid": 4326,
"latestWkid": 4326
},
"candidates": [
{
"address": "Coffee Tea & Me",
"location": {
"x": 151.2253078,
"y": -33.8711299
},
"score": 100,
"attributes": {
},
"extent": {
"xmin": 151.2203078,
"ymin": -33.8761299,
"xmax": 151.2303078,
"ymax": -33.8661299
}
}
]
}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 .
Disabling 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.
Example
Disable collections by using return with input text w and location in Washington, DC (location=-77.043,38.91 )
Request URL
https://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer/suggest?text=w&location=-77.043,38.91&returnCollections=false&f=pjson&token=<ACCESS_TOKEN>JSON response
{
"suggestions": [
{
"text": "Washington Monument, 2 15th St NW, Washington, DC, 20006, USA",
"magicKey": "dHA9MCN0dj00Yjg3MGE5MSNsb2M9MzEwNzk3NyNsbmc9NDIjcGw9MzYzMjY1NiNmYT02NTUzNiNsYnM9MTQ6NzYxNDgzNDYjbG49V29ybGQ=",
"isCollection": false
},
{
"text": "Washington, DC, USA",
"magicKey": "dHA9MCN0dj00Yjg3MGE5MSNsb2M9MzEwMTk0MiNsbmc9NDIjcGw9MzYyMjE0NyNsYnM9MTQ6NzYxNDUxODMjbG49V29ybGQ=",
"isCollection": false
},
{
"text": "Walt Disney World, Disneys Hollywood Studios Access Rd, Kissimmee, FL, 34747, USA",
"magicKey": "dHA9MCN0dj00Yjg3MGE5MSNsb2M9MzQ1NDQyMiNsbmc9NDIjcGw9MzgwNjM5MSNsYnM9MTQ6NzU3NDk3MjcjbG49V29ybGQ=",
"isCollection": false
},
{
"text": "Winter Park Resort, Winter Park Dr, Winter Park, CO, 80482, USA",
"magicKey": "dHA9MCN0dj00Yjg3MGE5MSNsb2M9MjYxMjg0OCNsbmc9NDIjcGw9MzAxNzc5MyNsYnM9MTQ6NzY4MzE5MDQjbG49V29ybGQ=",
"isCollection": false
},
{
"text": "Wrocław, Dolnośląskie, POL",
"magicKey": "dHA9MCN0dj00Yjg3MGE5MSNsb2M9NzAyNjY1MzAjbG5nPTEzNCNwbD05MDUxMjc5OSNsYnM9MTQ6NzcwNDMyNjYjbG49V29ybGQ=",
"isCollection": false
}
]
}As you can see, the suggestions returned for this request (with return ) all represent specific, individual places.
By contrast, when return for the same request, the top suggestion is collection "Whole Foods", which is a supermarket chain.
Example
Enable collections by using return with input text w and location in Washington, DC (location=-77.043,38.91 )
Request URL
https://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer/suggest?text=w&location=-77.043,38.91&returnCollections=true&f=pjson&token=<ACCESS_TOKEN>JSON response
{
"suggestions": [
{
"text": "Whole Foods",
"magicKey": "dHA9MSN0dj00Yjg3MGE5MSNubT1XaG9sZSBGb29kcyNzej0tNzcuMDQzMDAwMDAwMDAwMDA2OjM4LjkwOTk5OTk5OTk5OTk5NyNjcz0xMjYjbG49V29ybGQ=",
"isCollection": true
},
{
"text": "Washington Monument, 2 15th St NW, Washington, DC, 20006, USA",
"magicKey": "dHA9MCN0dj00Yjg3MGE5MSNsb2M9MzEwNzk3NyNsbmc9NDIjcGw9MzYzMjY1NiNmYT02NTUzNiNsYnM9MTQ6NzYxNDgzNDYjbG49V29ybGQ=",
"isCollection": false
},
{
"text": "Washington, DC, USA",
"magicKey": "dHA9MCN0dj00Yjg3MGE5MSNsb2M9MzEwMTk0MiNsbmc9NDIjcGw9MzYyMjE0NyNsYnM9MTQ6NzYxNDUxODMjbG49V29ybGQ=",
"isCollection": false
},
{
"text": "Waterfall",
"magicKey": "dHA9MiN0dj00Yjg3MGE5MSNubT1XYXRlcmZhbGwjc3o9LTc3LjA0MzAwMDAwMDAwMDAwNjozOC45MDk5OTk5OTk5OTk5OTcjY3M9MzE5I2xuPVdvcmxk",
"isCollection": true
},
{
"text": "Wine and liquor",
"magicKey": "dHA9MiN0dj00Yjg3MGE5MSNubT1XaW5lIGFuZCBsaXF1b3Ijc3o9LTc3LjA0MzAwMDAwMDAwMDAwNjozOC45MDk5OTk5OTk5OTk5OTcjY3M9MzY2I2xuPVdvcmxk",
"isCollection": true
}
]
}Specifying the number of suggestions
Depending on the use cases of your application, the default number of suggestions returned by a suggest request (5) may be too few, or too many. You can use the max parameter to choose the amount of suggestions that works for you.
Example
Choosing the number of suggestions to return with max (with input text esri )
Request URL
https://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer/suggest?text=esri&maxSuggestions=8&f=pjson&token=<ACCESS_TOKEN>JSON response
{
"suggestions": [
{
"text": "Esri, 380 New York St, Redlands, CA, 92373, USA",
"magicKey": "dHA9MCN0dj00Yjg3MGE5MSNsb2M9MTg5NjQ2MCNsbmc9NDIjcGw9MTIzMTY4NiNmYT02NTUzNiNsYnM9MTQ6MjYzNDI1MDEjbG49V29ybGQ=",
"isCollection": false
},
{
"text": "Esri Australia Pty. Ltd. – Brisbane Office, 111 Elizabeth Street, Level 3, Brisbane, Queensland, 4000, AUS",
"magicKey": "dHA9MCN0dj00Yjg3MGE5MSNsb2M9MzcxOTAxODkjbG5nPTQyI3BsPTM4MTczMzk5I2ZhPTY1NTM3I2xicz0xNDoyNjM0MjUwNyNsbj1Xb3JsZA==",
"isCollection": false
},
{
"text": "Esri Canada Ltd., 12 Concorde Place, Suite 900, Toronto, ON, M3C 3R8, CAN",
"magicKey": "dHA9MCN0dj00Yjg3MGE5MSNsb2M9MjA3NDM5NzYjbG5nPTQyI3BsPTE4OTg3MTExI2ZhPTY1NTM3I2xicz0xNDoyNjM0MjU0MiNsbj1Xb3JsZA==",
"isCollection": false
},
{
"text": "Esri Chile S.A., Apoquindo 6550, Las Condes, Santiago, 7560903, CHL",
"magicKey": "dHA9MCN0dj00Yjg3MGE5MSNsb2M9NDI3MTcxODUjbG5nPTE1OSNwbD00NDI5ODYzMCNmYT02NTUzNyNsYnM9MTQ6MjYzNDI1NDUjbG49V29ybGQ=",
"isCollection": false
},
{
"text": "Esri Deutschland GmbH, Ring Straße 7, 85402, Kranzberg, Bayern, DEU",
"magicKey": "dHA9MCN0dj00Yjg3MGE5MSNsb2M9MjQwNDY4MTQjbG5nPTU3I3BsPTIzMzU1MTM4I2ZhPTY1NTM2I2xicz0xNDoyNjM0MjU1NSNsbj1Xb3JsZA==",
"isCollection": false
},
{
"text": "Esri España Soluciones Geoespaciales S.L., Paseo de la Castellana 91, 28046, Madrid, ESP",
"magicKey": "dHA9MCN0dj00Yjg3MGE5MSNsb2M9NTAzODgyOTQjbG5nPTE1OSNwbD01MDIwODMwMyNmYT02NTUzNiNsYnM9MTQ6MjYzNDI1NTkjbG49V29ybGQ=",
"isCollection": false
},
{
"text": "Esri Finland Oy, Bertel Jungin Aukio 3, 02600, Espoo, FIN",
"magicKey": "dHA9MCN0dj00Yjg3MGE5MSNsb2M9NTA3NzM3NDQjbG5nPTUwI3BsPTUwNTc0NzU2I2ZhPTY1NTM2I2xicz0xNDoyNjM0MjU2MSNsbj1Xb3JsZA==",
"isCollection": false
},
{
"text": "Esri Indonesia, Jalan TB Simatupang 1, Pasar Minggu, DKI Jakarta, 12560, IDN",
"magicKey": "dHA9MCN0dj00Yjg3MGE5MSNsb2M9NTI4NjAxMjgjbG5nPTgxI3BsPTUzMDgyMzQ1I2ZhPTY1NTM3I2xicz0xNDoyNjM0MjU3NSNsbj1Xb3JsZA==",
"isCollection": false
}
]
}Limiting suggestions by country
By default, the ArcGIS Geocoding service returns suggestions from any relevant country based on the input text, unless the location or 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.
Example
Return suggestions for Indonesia only using country (with input text esri )
Request URL
https://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer/suggest?text=esri&countryCode=IDN&f=pjson&token=<ACCESS_TOKEN>JSON response
{
"suggestions": [
{
"text": "Esri Indonesia, Jalan TB Simatupang 1, Pasar Minggu, DKI Jakarta, 12560, IDN",
"magicKey": "dHA9MCN0dj00Yjg3MGE5MSNsb2M9NTI4NjAxMjgjbG5nPTgxI3BsPTUzMDgyMzQ1I2ZhPTY1NTM3I2xicz0xNDoyNjM0MjU3NSNsbj1Xb3JsZA==",
"isCollection": false
},
{
"text": "Esri Villa's, Desa Bangujiwo, Kasihan, Yogyakarta, 55184, IDN",
"magicKey": "dHA9MCN0dj00Yjg3MGE5MSNsb2M9NTU2MzM3NzUjbG5nPTgxI3BsPTU3OTc1NzU1I2xicz0xNDoyNjM0MjY3MSNsbj1Xb3JsZA==",
"isCollection": false
},
{
"text": "Esri Wedding Organizer, Jl. Kerenceng, Cidahu, Jawa Barat, 43358, IDN",
"magicKey": "dHA9MCN0dj00Yjg3MGE5MSNsb2M9NTM0OTM1OTMjbG5nPTgxI3BsPTU0MTIxMzMzI2xicz0xNDoyNjM0MjY3MyNsbj1Xb3JsZA==",
"isCollection": false
},
{
"text": "Esri Indonesia Branch Balikpapan, Jalan Jendral Sudirman 7, Balikpapan, East Kalimantan, 76114, IDN",
"magicKey": "dHA9MCN0dj00Yjg3MGE5MSNsb2M9NTI4NjAxMzAjbG5nPTgxI3BsPTUzMDgyMzQ3I2ZhPTY1NTM3I2xicz0xNDoyNjM0MjU3NiNsbj1Xb3JsZA==",
"isCollection": false
},
{
"text": "Esri Indonesia Branch Pekanbaru, Jalan Todak 18, Marpoyan Damai, Riau, 28124, IDN",
"magicKey": "dHA9MCN0dj00Yjg3MGE5MSNsb2M9NTUxNjY5MzQjbG5nPTgxI3BsPTU3MTI0MTM1I2ZhPTY1NTM2I2xicz0xNDoyNjM0MjU3NyNsbj1Xb3JsZA==",
"isCollection": false
}
]
}Category filtering
The suggest operation supports filtering searches by category values, which represent address and place types. By including the category parameter in a suggest request, you can avoid false positive matches to unexpected place and address types due to ambiguous searches.
For example, a user may type Bear in a search box, expecting the service to return Bear Mountain ski resort as a suggestion. However, there are many populated places in the world with Bear in their name, and this is reflected in the suggestions.
Example
Get suggestions for "Bear" without category
Request URL
https://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer/suggest?text=bear&category=&f=pjson&token=<ACCESS_TOKEN>JSON response
{
"suggestions": [
{
"text": "Bearsden, Dunbartonshire, Scotland, GBR",
"magicKey": "dHA9MCN0dj00Yjg3MGE5MSNsb2M9MjMyMTY3MjUjbG5nPTQyI3BsPTIyMjM4MzUwI2xicz0xNDoxMjI5MzE2OCNsbj1Xb3JsZA==",
"isCollection": false
},
{
"text": "Bear Lake County, ID, USA",
"magicKey": "dHA9MCN0dj00Yjg3MGE5MSNsb2M9NDkyODczNiNsbmc9NDIjcGw9NTQ3NjE5MCNsYnM9MTQ6MTIyODc4MTkjbG49V29ybGQ=",
"isCollection": false
},
{
"text": "Bear, DE, USA",
"magicKey": "dHA9MCN0dj00Yjg3MGE5MSNsb2M9MzAzOTE1OCNsbmc9NDIjcGw9MzU2NzkxMiNsYnM9MTQ6MTIyODU1NzcjbG49V29ybGQ=",
"isCollection": false
},
{
"text": "Bear Valley Springs, CA, USA",
"magicKey": "dHA9MCN0dj00Yjg3MGE5MSNsb2M9MTI3OTY5NyNsbmc9NDIjcGw9OTcyMzIwI2xicz0xNDoxMjI4OTU1MyNsbj1Xb3JsZA==",
"isCollection": false
},
{
"text": "Bear Creek, AL, USA",
"magicKey": "dHA9MCN0dj00Yjg3MGE5MSNsb2M9MTQzODc0I2xuZz00MiNwbD00MjE0MyNsYnM9MTQ6MTIyODYzMTkjbG49V29ybGQ=",
"isCollection": false
}
]
}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.
Example
Get suggestions for "Bear" with category=
Request URL
https://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer/suggest?text=bear&category=Ski Resort&f=pjson&token=<ACCESS_TOKEN>JSON response
{
"suggestions": [
{
"text": "Bear Mountain, 43101 Goldmine Dr, Big Bear Lake, CA, 92315, USA",
"magicKey": "dHA9MCN0dj00Yjg3MGE5MSNsb2M9MTU4NjMwNiNsbmc9NDIjcGw9MTExOTM1MCNmYT02NTUzNiNsYnM9MTQ6MTIyODgxMTMjbG49V29ybGQ=",
"isCollection": false
},
{
"text": "Bear Valley Alpine Ski Company Main Office, Arnold, CA, 95223, USA",
"magicKey": "dHA9MCN0dj00Yjg3MGE5MSNsb2M9MTIwNzAxOCNsbmc9NDIjcGw9OTQ4NTA1I2xicz0xNDoxMjI4OTM5MCNsbj1Xb3JsZA==",
"isCollection": false
},
{
"text": "Beartooth Basin Summer Ski Area, US Highway 212, Cody, WY, USA",
"magicKey": "dHA9MCN0dj00Yjg3MGE5MSNsb2M9MjAyMTAxMzgjbG5nPTQyI3BsPTE4MzM5MDk3I2xicz0xNDoxMjI5MzQ0MCNsbj1Xb3JsZA==",
"isCollection": false
},
{
"text": "Beartown Ski Area, 285 Beartown Rd, West Chazy, NY, 12992, USA",
"magicKey": "dHA9MCN0dj00Yjg3MGE5MSNsb2M9MTE2MTExNzQjbG5nPTQyI3BsPTExMDA3NDYxI2ZhPTY1NTM2I2xicz0xNDoxMjI5MzU3NCNsbj1Xb3JsZA==",
"isCollection": false
}
]
}See Category filtering for details.
Using 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):
Example
Return suggestions without using preferred (text = 9001 W 62nd St )
Request URL
https://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer/suggest?text=9001 W 62nd St&preferredLabelValues=&f=pjson&token=<ACCESS_TOKEN>JSON response
{
"suggestions": [
{
"text": "9001 W 62nd St, Mission, KS, 66202, USA",
"magicKey": "dHA9MCN0dj00Yjg3MGE5MSNsb2M9Njg5MDM5MSNsbmc9NDIjZmE9NjU1MzYjaG49OTAwMSNsYnM9MTA5Ojc1MzQxNjE0I2xuPVdvcmxk",
"isCollection": false
},
{
"text": "9001 W 62nd St, Indianapolis, IN, 46278, USA",
"magicKey": "dHA9MCN0dj00Yjg3MGE5MSNsb2M9NTk2MDA4NyNsbmc9NDIjaG49OTAwMSNsYnM9MTA5Ojc1MzQxNjE0I2xuPVdvcmxk",
"isCollection": false
},
{
"text": "9001 W 62nd St S, Monroe, IA, 50170, USA",
"magicKey": "dHA9MCN0dj00Yjg3MGE5MSNsb2M9NjQwMDE0NSNsbmc9NDIjaG49OTAwMSNsYnM9MTA5Ojc1MzQxNjE2I2xuPVdvcmxk",
"isCollection": false
},
{
"text": "9001 62nd St S, Cottage Grove, MN, 55016, USA",
"magicKey": "dHA9NCN0dj00Yjg3MGE5MSNubT05MDAxIDYybmQgU3QgUywgQ290dGFnZSBHcm92ZSwgTU4sIDU1MDE2LCBVU0EjbG5nPTQyI2xuPVdvcmxk",
"isCollection": false
},
{
"text": "9001 62nd St, Newaygo, MI, 49337, USA",
"magicKey": "dHA9MCN0dj00Yjg3MGE5MSNsb2M9ODY3MTQ3NCNsbmc9NDIjaG49OTAwMSNsYnM9MTA5Ojg1NzI5NDI5I2xuPVdvcmxk",
"isCollection": false
}
]
}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):
Example
Return suggestions using preferred (text = 9001 W 62nd St )
Request URL
https://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer/suggest?text=9001 W 62nd St&preferredLabelValues=localCity&f=pjson&token=<ACCESS_TOKEN>JSON response
{
"suggestions": [
{
"text": "9001 W 62nd St, Merriam, KS, 66202, USA",
"magicKey": "dHA9MCN0dj00Yjg3MGE5MSNsb2M9Njg5MDM5MSNsbmc9NDIjZmE9NjU1MzYjaG49OTAwMSNsYnM9MTA5Ojc1MzQxNjE0I2xuPVdvcmxk",
"isCollection": false
},
{
"text": "9001 W 62nd St, Indianapolis, IN, 46278, USA",
"magicKey": "dHA9MCN0dj00Yjg3MGE5MSNsb2M9NTk2MDA4NyNsbmc9NDIjaG49OTAwMSNsYnM9MTA5Ojc1MzQxNjE0I2xuPVdvcmxk",
"isCollection": false
},
{
"text": "9001 W 62nd St S, Fairview, IA, 50170, USA",
"magicKey": "dHA9MCN0dj00Yjg3MGE5MSNsb2M9NjQwMDE0NSNsbmc9NDIjaG49OTAwMSNsYnM9MTA5Ojc1MzQxNjE2I2xuPVdvcmxk",
"isCollection": false
},
{
"text": "9001 62nd St S, Cottage Grove, MN, 55016, USA",
"magicKey": "dHA9NCN0dj00Yjg3MGE5MSNubT05MDAxIDYybmQgU3QgUywgQ290dGFnZSBHcm92ZSwgTU4sIDU1MDE2LCBVU0EjbG5nPTQyI2xuPVdvcmxk",
"isCollection": false
},
{
"text": "9001 62nd St, Croton, MI, 49337, USA",
"magicKey": "dHA9MCN0dj00Yjg3MGE5MSNsb2M9ODY3MTQ3NCNsbmc9NDIjaG49OTAwMSNsYnM9MTA5Ojg1NzI5NDI5I2xuPVdvcmxk",
"isCollection": false
}
]
}However, if you start typing Mission as the city name for the same input, like this—9001 W 62nd St Mi —also with 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):
Example
Return suggestions using preferred ; the parameter is overridden by input city (text = 9001 W 62nd St Mi )
Request URL
https://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer/suggest?f=pjson&text=9001 W 62nd St Mi&preferredLabelValues=localCity&f=pjson&token=<ACCESS_TOKEN>JSON response
{
"suggestions": [
{
"text": "9001 W 62nd St, Mission, KS, 66202, USA",
"magicKey": "dHA9NCN0dj00Yjg3MGE5MSNubT05MDAxIFcgNjJuZCBTdCwgTWlzc2lvbiwgS1MsIDY2MjAyLCBVU0EjbG5nPTQyI2xuPVdvcmxk",
"isCollection": false
},
{
"text": "9001 62nd St, Croton, MI, 49337, USA",
"magicKey": "dHA9MCN0dj00Yjg3MGE5MSNsb2M9ODY3MTQ3NCNsbmc9NDIjaG49OTAwMSNsYnM9MTA5Ojg1NzI5NDI5OzI6NDQwOTExMTQjbG49V29ybGQ=",
"isCollection": false
},
{
"text": "9001 62nd St, Geneva, MI, 49090, USA",
"magicKey": "dHA9MCN0dj00Yjg3MGE5MSNsb2M9ODc0Mzc4NSNsbmc9NDIjaG49OTAwMSNsYnM9MTA5Ojg1NzI5NDI5OzI6NDQwOTExMTQjbG49V29ybGQ=",
"isCollection": false
},
{
"text": "9001 62nd St S, Cottage Grove, MN, 55016, USA",
"magicKey": "dHA9NCN0dj00Yjg3MGE5MSNubT05MDAxIDYybmQgU3QgUywgQ290dGFnZSBHcm92ZSwgTU4sIDU1MDE2LCBVU0EjbG5nPTQyI2xuPVdvcmxk",
"isCollection": false
},
{
"text": "9001 62nd St NW, Minot, ND, 58703, USA",
"magicKey": "dHA9MCN0dj00Yjg3MGE5MSNsb2M9MTMxNjg2MTAjbG5nPTQyI2huPTkwMDEjbGJzPTEwOTo4NTcyOTQzMzs5OjQ3Njk3Njg1I2xuPVdvcmxk",
"isCollection": false
}
]
}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:
Example
Use find with magic when preferred ; the parameter is overridden by input city (text = 9001 W 62nd St Mi )
Request URL
https://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer/findAddressCandidates?outFields=Match_addr,City&f=pjson&singleline=9001 W 62nd St, Mission, KS, 66202, USA&magicKey=dHA9NCN0dj00Yjg3MGE5MSNubT05MDAxIFcgNjJuZCBTdCwgTWlzc2lvbiwgS1MsIDY2MjAyLCBVU0EjbG5nPTQyI2xuPVdvcmxk&preferredLabelValues=localCity&token=<ACCESS_TOKEN>findAddressCandidates JSON response
{
"spatialReference": {
"wkid": 4326,
"latestWkid": 4326
},
"candidates": [
{
"address": "9001 W 62nd St, Merriam, Kansas, 66202",
"location": {
"x": -94.689894642071,
"y": 39.01691560122
},
"score": 100,
"attributes": {
"Match_addr": "9001 W 62nd St, Merriam, Kansas, 66202",
"City": "Merriam"
},
"extent": {
"xmin": -94.690894642071,
"ymin": 39.01591560122,
"xmax": -94.688894642071,
"ymax": 39.01791560122
}
}
]
}Refer to the findAddressCandidates topic for more information about how the preferred parameter can be used with that operation.