/suggest | ArcGIS REST APIs

GET
Use dark colors for code blocksCopy
GET https://geocode-api.arcgis.com/arcgis/rest/services/World/GeocodeServer/suggest

GET
Use dark colors for code blocksCopy
GET https://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer/suggest

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 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
Street intersections
- New York St and W Redlands Blvd, Redlands, CA
- Jacques Veltmanstraat & Pieter Calandlaan, Amsterdam, NLD
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 uses the same proximity algorithm as the findAddressCandidates 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://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer/suggest?<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:

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

Parameters

Name	Type	Default	Description
`f`	`string`		The request response format, either `json` or `pjson`
`token`	`string`		An access token with the required privileges.
`text`	`string`		The input text.
`location`	`string \| point`		The origin point used to favor geocoding candidates based on their proximity to the location.
`category`	`string`		The place or address type that can be used to filter results.
`searchExtent`	`envelope`		The set of bounding box coordinates that limits the search area.
`maxSuggestions`	`number`		The maximum number of suggestions to be returned in a response.
`countryCode`	`string`		Limits the returned suggestions to a specific country.
`sourceCountry`	`string`		Limits the candidates returned to the specified country or countries.
`preferredLabelValues`	`string`		Returns specified address component values included in output fields.
`returnCollections`	`boolean`	`true`	Prevents collections from being returned in the response.
`partialHouseNumber`	`boolean`	`false`	Allows PointAddress suggestions to be returned when only part of the house number is entered.
`partialSubaddress`	`boolean`	`false`	Allows subaddress suggestions to be returned when only part of the subunit value is entered.
`subaddressSummary`	`boolean`	`false`	Returns information in parenthesis for a PointAddress suggestion describing the count or range of Subaddresses that belong to it.
`subaddressAfterBaseAddress`	`boolean`	`false`	Returns a list of Subaddresses that belong to an input PointAddress.

Required parameters

f

stringrequired

Values: json | pjson

The response format.

Use dark colors for code blocksCopy
f=json

token

stringrequired

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

Use dark colors for code blocksCopy
token=<ACCESS_TOKEN>

To use HTTP headers instead of the token parameter, set the following:

X-Esri-Authorization

Authorization

Use dark colors for code blocksCopy

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

stringoptional

The input text entered by a user, which is used by the suggest operation to generate a list of possible matches.

Example

Use dark colors for code blocksCopy
text=starbu

Optional parameters

location

stringpointoptional

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)

Use dark colors for code blocksCopy
location=-117.196,34.056

JSON example with a spatial reference

Use dark colors for code blocksCopy
location=
{
    "x": -13046165.572,
    "y": 4036389.847,
    "spatialReference": {
        "wkid": 102100
    }
}

searchExtent

envelopeoptional

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

Use dark colors for code blocksCopy
searchExtent=-104,35.6,-94.32,41

Example with a spatial reference

Use dark colors for code blocksCopy
searchExtent=
{
    "xmin": -13052769,
    "ymin": 3951172,
    "xmax": -13019630,
    "ymax": 3978490,
    "spatialReference": {
        "wkid": 3395
    }
}

maxSuggestions

numberoptional

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 maxSuggestions is not included in the suggest request, the default value is 5.

Example

Use dark colors for code blocksCopy
maxSuggestions=10

countryCode

stringoptional

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

Use dark colors for code blocksCopy
countryCode=USA

sourceCountry

stringoptional

Similar to countryCode , the sourceCountry parameter limits the suggestions to the specified country or countries. For example, if sourceCountry=USA 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

Use dark colors for code blocksCopy
sourceCountry=USA

Example: Multiple countries

Use dark colors for code blocksCopy
sourceCountry=FRA,DEU,ESP

preferredLabelValues

stringoptional

The preferredLabelValues 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, OH, 45420 , 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 preferredLabelValues parameter can be used for this purpose. For the previous example, if preferredLabelValues=localCity 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 preferredLabelValues=matchedCity,postalCity is invalid.
The preferredLabelValues parameter 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 the preferredLabelValues parameter passed in the request. The idea is for suggestions to reflect the user input as much as possible, and this takes precedence over the preferredLabelValues parameter.

Example: Include local city name in suggestion

Use dark colors for code blocksCopy
preferredLabelValues=localCity

returnCollections

booleanoptional

Default value: true

The returnCollections 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

Use dark colors for code blocksCopy
returnCollections=false

partialHouseNumber

booleanoptional

Default value: false

The partialHouseNumber parameter allows PointAddress suggestions to be returned when only a partial house number is included in the input. For example, if you enter "Verlengde Nieuwstraat 12" with partialHouseNumber=true in the request, the following PointAddress suggestions are returned:

Verlengde Nieuwstraat 121, 3011 GX Rotterdam, NLD
Verlengde Nieuwstraat 123, 3011 GX Rotterdam, NLD
Verlengde Nieuwstraat 125, 3011 GX Rotterdam, NLD
Verlengde Nieuwstraat 127, 3011 GX Rotterdam, NLD
Verlengde Nieuwstraat 129, 3011 GX Rotterdam, NLD

The parameter value is false by default.

Example: Allow address suggestions based on partial house number input

Use dark colors for code blocksCopy
partialHouseNumber=true

partialSubaddress

booleanoptional

Default value: false

The partialSubaddress parameter allows Subaddress suggestions to be returned when only a partial subunit is included in the input. For example, if you enter "333 S Hope St #5" with partialSubaddress=true in the request, the following Subaddress suggestions are returned:

333 S Hope St, Suite 50, Los Angeles, CA, 90071, USA
333 S Hope St, Suite 51, Los Angeles, CA, 90071, USA
333 S Hope St, Suite 52, Los Angeles, CA, 90071, USA
333 S Hope St, Suite 53, Los Angeles, CA, 90071, USA
333 S Hope St, Suite 54, Los Angeles, CA, 90071, USA

The parameter value is false by default.

Example: Allow subaddress suggestions based on partial subunit input

Use dark colors for code blocksCopy
partialSubaddress=true

subaddressSummary

booleanoptional

Default value: false

With the subaddressSummary parameter, information about the count or range of Subaddresses that belong to a requested PointAddress is provided in the response.

In most cases the summary is represented as a range of Subaddresses. For example, if "865 S Figueroa St" is entered, the following suggestion is returned:

865 S Figueroa St (Suite 10-3500), Los Angeles, CA, 90017, USA

If the Subaddresses have different unit types (such as "Apt 1" and "Suite 100"), or if they include multiple subunit components (such as units and levels), then the summary is represented as a count. For instance, if "900 Wilshire Blvd" is entered, the following suggestion is returned:

900 Wilshire Blvd (190 units), Los Angeles, CA, 90017, USA

The parameter value is false by default.

Example: Allow subaddress suggestions based on partial subunit input

Use dark colors for code blocksCopy
subaddressSummary=true

subaddressAfterBaseAddress

booleanoptional

Default value: false

With the subaddressAfterBaseAddress parameter, a list of Subaddresses that belong to a requested PointAddress is returned; the Subaddresses are ordered after the base PointAddress. For example, if you enter "805 N Dalton Ave, Azusa" with subaddressAfterBaseAddress=true in the request, the following suggestions are returned:

16014 Adelante St, Irwindale, CA, 91702, USA
16014 Adelante St, Suite A, Irwindale, CA, 91702, USA
16014 Adelante St, Suite B, Irwindale, CA, 91702, USA
16014 Adelante St, Suite C, Irwindale, CA, 91702, USA
16014 Adelante St, Suite D, Irwindale, CA, 91702, USA

The parameter value is false by default.

Example: Allow subaddress suggestions based on partial subunit input

Use dark colors for code blocksCopy
subaddressAfterBaseAddress=true

Response status

Status	Meaning	Description	Schema
`200`	OK	A successful response for a `/reverseGeocode` request.	Inline
`400`	Bad request	Invalid query parameters. Learn more in Service output.	Error
`403`	Forbidden	The required paramter `token` is valid but does not have permission to access the service. Learn more in Service output.	Error
`5XX`	Unknown	An error occured on the server. Learn more in Service output.	Error

Go to Service output for extended codes.

Response details

Use dark colors for code blocksCopy

{
  "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 findAddressCandidates 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 searchExtent 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.

Use dark colors for code blocksCopy
GET https://geocode-api.arcgis.com/arcgis/rest/services/World/GeocodeServer/suggest?text=treas&location=-115.172783,36.114789&f=pjson&token=<ACCESS_TOKEN>

Use dark colors for code blocksCopy
{
 "suggestions": [
  {
   "text": "Treasure Island, 3300 Las Vegas Boulevard South, Las Vegas, NV, 89109, USA",
   "magicKey": "dHA9MCN0dj0xZWJkOWY4YiNsb2M9MTMyODY4MDMjbG5nPTQxI3BsPTExMDA0ODgzI2ZhPTU4OTgyNCNsYnM9MTQ6NzQwNjk3MDkjbG49V29ybGQ=",
   "isCollection": false
  },
  {
   "text": "Treasure Island Wedding Chapels, 3300 Las Vegas Boulevard South, Las Vegas, NV, 89109, USA",
   "magicKey": "dHA9MCN0dj0xZWJkOWY4YiNsb2M9MTMyODY4MDMjbG5nPTQxI3BsPTExMDA0OTk3I2ZhPTU4OTgyNCNsYnM9MTQ6NzQwNjk5MDkjbG49V29ybGQ=",
   "isCollection": false
  },
  {
   "text": "Treasure Island Pool, 3300 Las Vegas Blvd S, Las Vegas, NV, 89109, USA",
   "magicKey": "dHA9MCN0dj0xZWJkOWY4YiNsb2M9MTMzMzcwMTQjbG5nPTQxI3BsPTExMDk5MTY3I2ZhPTIwOTcxNTIjbGJzPTE0Ojc0MDY5ODUyI2xuPVdvcmxk",
   "isCollection": false
  },
  {
   "text": "Treasure Island At The Mirage, 3300 Las Vegas Blvd S, Las Vegas, NV, 89109, USA",
   "magicKey": "dHA9MCN0dj0xZWJkOWY4YiNsb2M9MTMzMzcwMTQjbG5nPTQxI3BsPTExMTAwMTc0I2ZhPTIwOTcxNTIjbGJzPTE0Ojc0MDY5NzI5I2xuPVdvcmxk",
   "isCollection": false
  },
  {
   "text": "Treasure Island Hotel and Casino, Paradise, NV, USA",
   "magicKey": "dHA9MCN0dj0xZWJkOWY4YiNsb2M9MTMzMzIwMjEjbG5nPTQxI3BsPTExMDIzOTYwI2xicz0xNDo3NDA2OTgwOSNsbj1Xb3JsZA==",
   "isCollection": false
  }
 ]
}

Get suggestions without location

Use dark colors for code blocksCopy
GET https://geocode-api.arcgis.com/arcgis/rest/services/World/GeocodeServer/suggest?text=treas&f=pjson&token=<ACCESS_TOKEN>

Use dark colors for code blocksCopy
{
 "suggestions": [
  {
   "text": "Treasure County, MT, USA",
   "magicKey": "dHA9MCN0dj0xZWJkOWY4YiNsb2M9MTI5MDcyMzgjbG5nPTQxI3BsPTEwNzA3NDMwI2xicz0xNDo3NDA2OTMzOSNsbj1Xb3JsZA==",
   "isCollection": false
  },
  {
   "text": "Treas, Banteay Meanchey, KHM",
   "magicKey": "dHA9MCN0dj0xZWJkOWY4YiNsb2M9NjQ0NTIyMTUjbG5nPTQxI3BsPTgyMDQwMjc1I2xicz0xNDo3NDA2ODYwOCNsbj1Xb3JsZA==",
   "isCollection": false
  },
  {
   "text": "Treasure Island, FL, USA",
   "magicKey": "dHA9NCN0dj0xZWJkOWY4YiNubT1UcmVhc3VyZSBJc2xhbmQsIEZMLCBVU0EjbG5nPTQxI2xuPVdvcmxk",
   "isCollection": false
  },
  {
   "text": "Treasure Lake, PA, USA",
   "magicKey": "dHA9NCN0dj0xZWJkOWY4YiNubT1UcmVhc3VyZSBMYWtlLCBQQSwgVVNBI2xuZz00MSNsbj1Xb3JsZA==",
   "isCollection": false
  },
  {
   "text": "Treascon, Portarlington, Laois, IRL",
   "magicKey": "dHA9MCN0dj0xZWJkOWY4YiNsb2M9NjI4OTQwNjYjbG5nPTQxI3BsPTc4ODk4OTUxI2xicz0xNDo3NDA2ODYzOCNsbj1Xb3JsZA==",
   "isCollection": false
  }
 ]
}

Limit suggestions to a specified area

Unlike the location parameter, the searchExtent 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 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.

Get suggestions using searchExtent

Use dark colors for code blocksCopy
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>

Use dark colors for code blocksCopy
{
 "suggestions": [
  {
   "text": "Main St, Kansas City, MO, 64108, USA",
   "magicKey": "dHA9MCN0dj0xZWJkOWY4YiNsb2M9MTIyMzE0MDMjbG5nPTQxI2xicz0xMDk6OTI3MjY2NDAjbG49V29ybGQ=",
   "isCollection": false
  },
  {
   "text": "Main St, Kansas City, MO, 64106, USA",
   "magicKey": "dHA9NCN0dj0xZWJkOWY4YiNubT1NYWluIFN0LCBLYW5zYXMgQ2l0eSwgTU8sIDY0MTA2LCBVU0Ejc3o9LTk0LjU4NjA4ODQ5OTk5OTk4ODozOS4wOTY3MDIwMDAwMDAwMDE7LTk0LjYwMjAyNTk5OTk5OTk5NTozOS4wODM2Mjk5OTk5OTk5OTk6LTk0LjU3MDE1MDk5OTk5OTk5NjozOS4xMDk3NzQwMDAwMDAwMDIjbG5nPTQxI2xuPVdvcmxk",
   "isCollection": false
  },
  {
   "text": "Main St, Kansas City, MO, 64105, USA",
   "magicKey": "dHA9NCN0dj0xZWJkOWY4YiNubT1NYWluIFN0LCBLYW5zYXMgQ2l0eSwgTU8sIDY0MTA1LCBVU0Ejc3o9LTk0LjU4NjA4ODQ5OTk5OTk4ODozOS4wOTY3MDIwMDAwMDAwMDE7LTk0LjYwMjAyNTk5OTk5OTk5NTozOS4wODM2Mjk5OTk5OTk5OTk6LTk0LjU3MDE1MDk5OTk5OTk5NjozOS4xMDk3NzQwMDAwMDAwMDIjbG5nPTQxI2xuPVdvcmxk",
   "isCollection": false
  },
  {
   "text": "Main Street Financial Advisors, 2300 Main St, Kansas City, MO, 64108, USA",
   "magicKey": "dHA9MCN0dj0xZWJkOWY4YiNsb2M9MTI0NDc1MTIjbG5nPTQxI3BsPTEwNDY5NzQ4I2ZhPTIzNTkyOTYjbGJzPTE0OjQ1NzQ3ODQzI2xuPVdvcmxk",
   "isCollection": false
  }
 ]
}

Get suggestions using searchExtent with a JSON envelope object

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 use 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.

Use dark colors for code blocksCopy
GET https://geocode-api.arcgis.com/arcgis/rest/services/World/GeocodeServer/suggest?text=main%20st&searchExtent=%7B%22xmin%22%3A-10531043%2C%22ymin%22%3A4733652%2C%22xmax%22%3A-10527501%2C%22ymax%22%3A4737408%2C%22spatialReference%22%3A%7B%22wkid%22%3A102100%7D%7D&outSR=102100&f=pjson&token=<ACCESS_TOKEN>

Use dark colors for code blocksCopy
{
 "suggestions": [
  {
   "text": "Main St, Kansas City, MO, 64108, USA",
   "magicKey": "dHA9MCN0dj0xZWJkOWY4YiNsb2M9MTIyMzE0MDMjbG5nPTQxI2xicz0xMDk6OTI3MjY2NDAjbG49V29ybGQ=",
   "isCollection": false
  },
  {
   "text": "Main St, Kansas City, MO, 64106, USA",
   "magicKey": "dHA9NCN0dj0xZWJkOWY4YiNubT1NYWluIFN0LCBLYW5zYXMgQ2l0eSwgTU8sIDY0MTA2LCBVU0Ejc3o9LTk0LjU4NjA1OTY4MjUxNzIxNzozOS4wOTY2ODEzNjU5NzUwNzM7LTk0LjYwMTk2ODg0NjE5ODk3MjozOS4wODM1ODg1NjY5MjkwNTk6LTk0LjU3MDE1MDUxODgzNTQ2MjozOS4xMDk3NzQxNjUwMjEwODYjbG5nPTQxI2xuPVdvcmxk",
   "isCollection": false
  },
  {
   "text": "Main St, Kansas City, MO, 64105, USA",
   "magicKey": "dHA9NCN0dj0xZWJkOWY4YiNubT1NYWluIFN0LCBLYW5zYXMgQ2l0eSwgTU8sIDY0MTA1LCBVU0Ejc3o9LTk0LjU4NjA1OTY4MjUxNzIxNzozOS4wOTY2ODEzNjU5NzUwNzM7LTk0LjYwMTk2ODg0NjE5ODk3MjozOS4wODM1ODg1NjY5MjkwNTk6LTk0LjU3MDE1MDUxODgzNTQ2MjozOS4xMDk3NzQxNjUwMjEwODYjbG5nPTQxI2xuPVdvcmxk",
   "isCollection": false
  },
  {
   "text": "Main Street Financial Advisors, 2300 Main St, Kansas City, MO, 64108, USA",
   "magicKey": "dHA9MCN0dj0xZWJkOWY4YiNsb2M9MTI0NDc1MTIjbG5nPTQxI3BsPTEwNDY5NzQ4I2ZhPTIzNTkyOTYjbGJzPTE0OjQ1NzQ3ODQzI2xuPVdvcmxk",
   "isCollection": false
  }
 ]
}

Utilize 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.

Get the isCollection property

Use dark colors for code blocksCopy
GET https://geocode-api.arcgis.com/arcgis/rest/services/World/GeocodeServer/suggest?text=coffee&location=151.229129,-33.879741&f=pjson&token=<ACCESS_TOKEN>

Use dark colors for code blocksCopy
{
 "suggestions": [
  {
   "text": "Coffee Shop",
   "magicKey": "dHA9MiN0dj0xZWJkOWY4YiNubT1Db2ZmZWUgU2hvcCNzej0xNTEuMjI5MTI5Oi0zMy44Nzk3NDEwMDAwMDAwMDMjY3M9NzAjbG49V29ybGQ=",
   "isCollection": true
  },
  {
   "text": "Coffee Book, 102 Burton Street, Darlinghurst, Sydney, New South Wales, 2010, AUS",
   "magicKey": "dHA9MCN0dj0xZWJkOWY4YiNsb2M9NDE0NzAwNTgjbG5nPTQxI3BsPTM4OTY1ODgzI2ZhPTc4NjQzMiNsYnM9MTQ6MTk1MDY2MjQjbG49V29ybGQ=",
   "isCollection": false
  },
  {
   "text": "Coffee Tea & Me, Hughes Street & Macleay Street, Potts Point, Sydney, New South Wales, 2011, AUS",
   "magicKey": "dHA9MCN0dj0xZWJkOWY4YiNsb2M9NDE0OTgxMjcjbG5nPTQxI3BsPTM5MDYzOTgwI2xicz0xNDoxOTUxNTA5MSNsbj1Xb3JsZA==",
   "isCollection": false
  },
  {
   "text": "Coffee Roaster, 81 Macleay Street, Potts Point, Sydney, New South Wales, 2011, AUS",
   "magicKey": "dHA9MCN0dj0xZWJkOWY4YiNsb2M9NDE0OTgwODkjbG5nPTQxI3BsPTM5MDYzNzI5I2ZhPTY1NTM2MCNsYnM9MTQ6MTk1MTM0NTAjbG49V29ybGQ=",
   "isCollection": false
  },
  {
   "text": "Coffee Tea & Me, 224 Oxford Street, Bondi Junction, Sydney, New South Wales, 2022, AUS",
   "magicKey": "dHA9MCN0dj0xZWJkOWY4YiNsb2M9NDE0NjExODAjbG5nPTQxI3BsPTM4OTMyNDgyI2ZhPTMwMTQ2NTYjbGJzPTE0OjE5NTE1MDkxI2xuPVdvcmxk",
   "isCollection": false
  }
 ]
}

Using a suggest result when `isCollection=true`

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 ArcGIS Geocoding service in a findAddressCandidates request, with maxLocations = 10 , several coffee shops are returned.

Use dark colors for code blocksCopy
GET https://geocode-api.arcgis.com/arcgis/rest/services/World/GeocodeServer/findAddressCandidates?singleLine=Coffee Shop&magicKey=dHA9MiN0dj0xZWJkOWY4YiNubT1Db2ZmZWUgU2hvcCNzej0xNTEuMjI5MTI5Oi0zMy44Nzk3NDEwMDAwMDAwMDMjY3M9NzAjbG49V29ybGQ==&maxLocations=10&outFields=Match_addr,Place_addr,Type&f=pjson&token=<ACCESS_TOKEN>

findAddressCandidates JSON response

Use dark colors for code blocksCopy
{
 "spatialReference": {
  "wkid": 4326,
  "latestWkid": 4326
 },
 "candidates": [
  {
   "address": "Padre Coffee Paddington",
   "location": {
    "x": 151.2286325,
    "y": -33.882286
   },
   "score": 100,
   "attributes": {
    "Match_addr": "Padre Coffee Paddington",
    "Type": "Coffee Shop",
    "Place_addr": "241A-241B Glenmore Road, Paddington, Sydney, New South Wales, 2021"
   },
   "extent": {
    "xmin": 151.2236325,
    "ymin": -33.887286,
    "xmax": 151.2336325,
    "ymax": -33.877286
   }
  },
  {
   "address": "Primary Coffee",
   "location": {
    "x": 151.2251344,
    "y": -33.873814
   },
   "score": 100,
   "attributes": {
    "Match_addr": "Primary Coffee",
    "Type": "Coffee Shop",
    "Place_addr": "9 Ward Avenue, Potts Point, Sydney, New South Wales, 2011"
   },
   "extent": {
    "xmin": 151.2201344,
    "ymin": -33.878814,
    "xmax": 151.2301344,
    "ymax": -33.868814
   }
  }
 ]
}

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

Use a suggest result when `isCollection=false`

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

Use dark colors for code blocksCopy
GET https://geocode-api.arcgis.com/arcgis/rest/services/World/GeocodeServer/findAddressCandidates?singleLine=Coffee Book, 102 Burton Street, Darlinghurst, Sydney, New South Wales, 2010, AUS&magicKey=dHA9MCN0dj0xZWJkOWY4YiNsb2M9NDE0NzAwNTgjbG5nPTQxI3BsPTM4OTY1ODgzI2ZhPTc4NjQzMiNsYnM9MTQ6MTk1MDY2MjQjbG49V29ybGQ=&f=pjson&token=<ACCESS_TOKEN>

findAddressCandidates JSON response

Use dark colors for code blocksCopy
{
 "spatialReference": {
  "wkid": 4326,
  "latestWkid": 4326
 },
 "candidates": [
  {
   "address": "Coffee Book",
   "location": {
    "x": 151.21874,
    "y": -33.87869
   },
   "score": 100,
   "attributes": {

   },
   "extent": {
    "xmin": 151.21374,
    "ymin": -33.88369,
    "xmax": 151.22374,
    "ymax": -33.87369
   }
  }
 ]
}

Disable collections

If collections are not needed for your application, you can use the returnCollections parameter to prevent them from being returned in suggest responses. Specifically, if returnCollections=false is included in a suggest request, only suggestion items with isCollection = false are returned in the response. Collections are returned by default for suggest , so returnCollections=false must be included in the suggest request to disable this feature.

Disable collections by using returnCollections=false

Use dark colors for code blocksCopy
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>

Use dark colors for code blocksCopy
{
 "suggestions": [
  {
   "text": "White House, 1600 Pennsylvania Ave NW, Washington, DC, 20500, USA",
   "magicKey": "dHA9MCN0dj0xZWJkOWY4YiNsb2M9MzgyMTE1MiNsbmc9NDEjcGw9MzkxMzIzOCNmYT02NTUzNiNsYnM9MTQ6NzgzMzM4NjIjbG49V29ybGQ=",
   "isCollection": false
  },
  {
   "text": "Washington Monument, 2 15Th Street Northwest, Washington, DC, 20006, USA",
   "magicKey": "dHA9MCN0dj0xZWJkOWY4YiNsb2M9MzgyMTEyMyNsbmc9NDEjcGw9MzkxMzE5MCNmYT02NTUzNiNsYnM9MTQ6Nzc4MjE2NTQjbG49V29ybGQ=",
   "isCollection": false
  },
  {
   "text": "Washington, DC, USA",
   "magicKey": "dHA9MCN0dj0xZWJkOWY4YiNsb2M9MzgxMzQzMCNsbmc9NDEjcGw9MzkwMjI3NSNsYnM9MTQ6Nzc4MTgwMTQjbG49V29ybGQ=",
   "isCollection": false
  },
  {
   "text": "Walt Disney World, Disneys Hollywood Studios Access Rd, Kissimmee, FL, 34747, USA",
   "magicKey": "dHA9MCN0dj0xZWJkOWY4YiNsb2M9NDIwNjc5MiNsbmc9NDEjcGw9NDExNzU5NiNsYnM9MTQ6Nzc0MTk4MTQjbG49V29ybGQ=",
   "isCollection": false
  },
  {
   "text": "Winter Park Resort, 85 Parsenn Road, Winter Park, CO, 80482, USA",
   "magicKey": "dHA9MCN0dj0xZWJkOWY4YiNsb2M9MzIyMzM0NSNsbmc9NDEjcGw9MzI0ODk1NiNmYT02NTUzNiNsYnM9MTQ6Nzg1NjY4NDAjbG49V29ybGQ=",
   "isCollection": false
  }
 ]
}

Enable collections by using returnCollections=true

By contrast, when returnCollections=true for the same request, the top suggestion is collection "Whole Foods", which is a supermarket chain.

Use dark colors for code blocksCopy
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>

Use dark colors for code blocksCopy
{
 "suggestions": [
  {
   "text": "Whole Foods",
   "magicKey": "dHA9MSN0dj0xZWJkOWY4YiNubT1XaG9sZSBGb29kcyNzej0tNzcuMDQzMDAwMDAwMDAwMDA2OjM4LjkwOTk5OTk5OTk5OTk5NyNjcz0xMjYjbG49V29ybGQ=",
   "isCollection": true
  },
  {
   "text": "White House, 1600 Pennsylvania Ave NW, Washington, DC, 20500, USA",
   "magicKey": "dHA9MCN0dj0xZWJkOWY4YiNsb2M9MzgyMTE1MiNsbmc9NDEjcGw9MzkxMzIzOCNmYT02NTUzNiNsYnM9MTQ6NzgzMzM4NjIjbG49V29ybGQ=",
   "isCollection": false
  },
  {
   "text": "Washington Monument, 2 15Th Street Northwest, Washington, DC, 20006, USA",
   "magicKey": "dHA9MCN0dj0xZWJkOWY4YiNsb2M9MzgyMTEyMyNsbmc9NDEjcGw9MzkxMzE5MCNmYT02NTUzNiNsYnM9MTQ6Nzc4MjE2NTQjbG49V29ybGQ=",
   "isCollection": false
  },
  {
   "text": "Washington, DC, USA",
   "magicKey": "dHA9MCN0dj0xZWJkOWY4YiNsb2M9MzgxMzQzMCNsbmc9NDEjcGw9MzkwMjI3NSNsYnM9MTQ6Nzc4MTgwMTQjbG49V29ybGQ=",
   "isCollection": false
  },
  {
   "text": "Waterfall",
   "magicKey": "dHA9MiN0dj0xZWJkOWY4YiNubT1XYXRlcmZhbGwjc3o9LTc3LjA0MzAwMDAwMDAwMDAwNjozOC45MDk5OTk5OTk5OTk5OTcjY3M9MzE5I2xuPVdvcmxk",
   "isCollection": true
  }
 ]
}

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 maxSuggestions parameter to choose the amount of suggestions that works for you.

Use dark colors for code blocksCopy
GET https://geocode-api.arcgis.com/arcgis/rest/services/World/GeocodeServer/suggest?text=esri&maxSuggestions=8&f=pjson&token=<ACCESS_TOKEN>

Use dark colors for code blocksCopy
{
 "suggestions": [
  {
   "text": "Esri, 380 New York St, Redlands, CA, 92373, USA",
   "magicKey": "dHA9MCN0dj0xZWJkOWY4YiNsb2M9MjQ2ODM2MiNsbmc9NDEjcGw9MzIwNzc2NSNmYT02NTUzNiNsYnM9MTQ6MjY5MTY0MTYjbG49V29ybGQ=",
   "isCollection": false
  },
  {
   "text": "Esri Australia Pty. Ltd. – Brisbane Office, 111 Elizabeth Street, Level 3, Brisbane, Queensland, 4000, AUS",
   "magicKey": "dHA9MCN0dj0xZWJkOWY4YiNsb2M9NDE5ODU4MzUjbG5nPTQxI3BsPTM5NTcyODgxI2ZhPTY1NTM3I2xicz0xNDoyNjkxNjQyMiNsbj1Xb3JsZA==",
   "isCollection": false
  },
  {
   "text": "Esri Canada Ltd., 12 Concorde Place, Suite 900, Toronto, ON, M3C 3R8, CAN",
   "magicKey": "dHA9MCN0dj0xZWJkOWY4YiNsb2M9MjYxNzcxMzcjbG5nPTQxI3BsPTIxMjY2ODI3I2ZhPTY1NTM3I2xicz0xNDoyNjkxNjQ1NiNsbj1Xb3JsZA==",
   "isCollection": false
  },
  {
   "text": "Esri Chile S.A., Avenida Apoquindo 6550, Las Condes, Santiago, 7560903, CHL",
   "magicKey": "dHA9MCN0dj0xZWJkOWY4YiNsb2M9NDkyNzkxODYjbG5nPTE1OCNwbD00NTc5OTA4NSNmYT02NTUzNyNsYnM9MTQ6MjY5MTY0NTkjbG49V29ybGQ=",
   "isCollection": false
  },
  {
   "text": "Esri Deutschland GmbH, Ringstraße 7, 85402, Kranzberg, Bayern, DEU",
   "magicKey": "dHA9MCN0dj0xZWJkOWY4YiNsb2M9Mjg5ODc3MzAjbG5nPTU2I3BsPTI1MTg4MTg2I2ZhPTY1NTM2I2xicz0xNDoyNjkxNjQ2OSNsbj1Xb3JsZA==",
   "isCollection": false
  },
  {
   "text": "Esri España Soluciones Geoespaciales S.L., Paseo de la Castellana 91, 28046, Madrid, ESP",
   "magicKey": "dHA9MCN0dj0xZWJkOWY4YiNsb2M9NTU0ODY4MTEjbG5nPTE1OCNwbD01MTQ5ODI3NyNmYT02NTUzNiNsYnM9MTQ6MjY5MTY0NzMjbG49V29ybGQ=",
   "isCollection": false
  },
  {
   "text": "Esri Finland Oy, Bertel Jungin Aukio 3, 02600, Espoo, FIN",
   "magicKey": "dHA9MCN0dj0xZWJkOWY4YiNsb2M9NTU5MzQxMDAjbG5nPTQ5I3BsPTUxODI3MTk5I2ZhPTY1NTM2I2xicz0xNDoyNjkxNjQ3NSNsbj1Xb3JsZA==",
   "isCollection": false
  },
  {
   "text": "Esri Indonesia, Jalan TB Simatupang 1, Pasar Minggu, DKI Jakarta, 12560, IDN",
   "magicKey": "dHA9MCN0dj0xZWJkOWY4YiNsb2M9NTc3MjU2MTUjbG5nPTgwI3BsPTU0Mzc2NDYwI2ZhPTY1NTM3I2xicz0xNDoyNjkxNjQ4OCNsbj1Xb3JsZA==",
   "isCollection": false
  }
 ]
}

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

Use dark colors for code blocksCopy
GET https://geocode-api.arcgis.com/arcgis/rest/services/World/GeocodeServer/suggest?text=esri&countryCode=IDN&f=pjson&token=<ACCESS_TOKEN>

Use dark colors for code blocksCopy
{
 "suggestions": [
  {
   "text": "Esri Indonesia, Jalan TB Simatupang 1, Pasar Minggu, DKI Jakarta, 12560, IDN",
   "magicKey": "dHA9MCN0dj0xZWJkOWY4YiNsb2M9NTc3MjU2MTUjbG5nPTgwI3BsPTU0Mzc2NDYwI2ZhPTY1NTM3I2xicz0xNDoyNjkxNjQ4OCNsbj1Xb3JsZA==",
   "isCollection": false
  },
  {
   "text": "Esri Indonesia Branch Balikpapan, Jalan Jendral Sudirman 7, Balikpapan, East Kalimantan, 76114, IDN",
   "magicKey": "dHA9MCN0dj0xZWJkOWY4YiNsb2M9NTc3MjU2MTcjbG5nPTgwI3BsPTU0Mzc2NDYyI2ZhPTY1NTM3I2xicz0xNDoyNjkxNjQ4OSNsbj1Xb3JsZA==",
   "isCollection": false
  },
  {
   "text": "Esri Indonesia Branch Pekanbaru, Jalan Todak 18, Marpoyan Damai, Riau, 28124, IDN",
   "magicKey": "dHA9MCN0dj0xZWJkOWY4YiNsb2M9NTg0MjkwNjcjbG5nPTgwI3BsPTU4ODU5MzI4I2ZhPTY1NTM2I2xicz0xNDoyNjkxNjQ5MCNsbj1Xb3JsZA==",
   "isCollection": false
  },
  {
   "text": "Esri Indonesia Branch Surabaya, Jalan Embong Malang 1-5, Tegalsari, East Java, 60261, IDN",
   "magicKey": "dHA9MCN0dj0xZWJkOWY4YiNsb2M9NTc3MjU2MTYjbG5nPTgwI3BsPTU0Mzc2NDYxI2ZhPTY1NTM3I2xicz0xNDoyNjkxNjQ5MSNsbj1Xb3JsZA==",
   "isCollection": false
  },
  {
   "text": "Esrim Food, Gang Pojok 3, Bekasi Barat, Jawa Barat, 17136, IDN",
   "magicKey": "dHA9MCN0dj0xZWJkOWY4YiNsb2M9NTc4NDAwNTIjbG5nPTgwI3BsPTU1MjcxODMyI2ZhPTE5NjYwOCNsYnM9MTQ6MjY5MTY1OTYjbG49V29ybGQ=",
   "isCollection": false
  }
 ]
}

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

Use dark colors for code blocksCopy
GET https://geocode-api.arcgis.com/arcgis/rest/services/World/GeocodeServer/suggest?text=bear&category=&f=pjson&token=<ACCESS_TOKEN>

Use dark colors for code blocksCopy
{
 "suggestions": [
  {
   "text": "Bear, DE, USA",
   "magicKey": "dHA9MCN0dj0xZWJkOWY4YiNsb2M9Mzc0MTUxNyNsbmc9NDEjcGw9Mzg0MjEyNiNsYnM9MTQ6MTI0NTc0NTMjbG49V29ybGQ=",
   "isCollection": false
  },
  {
   "text": "Bearsden, Dunbartonshire, Scotland, GBR",
   "magicKey": "dHA9MCN0dj0xZWJkOWY4YiNsb2M9MjgxNzE1MTQjbG5nPTQxI3BsPTI0MTIzNzk3I2xicz0xNDoxMjQ2NjI0MyNsbj1Xb3JsZA==",
   "isCollection": false
  },
  {
   "text": "Bear Lake County, ID, USA",
   "magicKey": "dHA9MCN0dj0xZWJkOWY4YiNsb2M9NjAyNDMxOCNsbmc9NDEjcGw9NTkzMjA2OSNsYnM9MTQ6MTI0NjAwNTQjbG49V29ybGQ=",
   "isCollection": false
  },
  {
   "text": "Bear Valley Springs, CA, USA",
   "magicKey": "dHA9MCN0dj0xZWJkOWY4YiNsb2M9MTY3MDk5MSNsbmc9NDEjcGw9MTA3Mzg3MyNsYnM9MTQ6MTI0NjIwNzYjbG49V29ybGQ=",
   "isCollection": false
  },
  {
   "text": "Bear Creek, PA, USA",
   "magicKey": "dHA9MCN0dj0xZWJkOWY4YiNsb2M9MTg0MDIzOTAjbG5nPTQxI3BsPTE1MTIyMDUxI2xicz0xNDoxMjQ1ODMzNyNsbj1Xb3JsZA==",
   "isCollection": false
  }
 ]
}

See Category filtering for details.

The solution for this case is to pass the category parameter in the request. By including category=Amusement Park in the request, all places that are not amusement parks are bypassed by the search, and only amusement parks whose names begin with Bear are returned.

Get suggestions for "Bear" with category=Amusement Park

Use dark colors for code blocksCopy
GET https://geocode-api.arcgis.com/arcgis/rest/services/World/GeocodeServer/suggest?text=bear&category=Amusement Park&f=pjson&token=<ACCESS_TOKEN>

Use dark colors for code blocksCopy
{
 "suggestions": [
  {
   "text": "Bear Foot Bay Indoor Water Park, 1801 Cabela's Lane, Prairie du Chien, WI, 53821, USA",
   "magicKey": "dHA9MCN0dj0xZWJkOWY4YiNsb2M9MjQ2NDM1NTgjbG5nPTQxI3BsPTE5NjU1NDQxI2ZhPTY1NTM2I2xicz0xNDoxMjQ1OTQzNiNsbj1Xb3JsZA==",
   "isCollection": false
  },
  {
   "text": "Bear Track Landing - Great Wolf, 159 Great Wolf Drive, Fitchburg, MA, 01420, USA",
   "magicKey": "dHA9MCN0dj0xZWJkOWY4YiNsb2M9MTAxODk3MzcjbG5nPTQxI3BsPTg3NTI3NTkjZmE9MTMxMDcyI2xicz0xNDoxMjQ2MTcyOCNsbj1Xb3JsZA==",
   "isCollection": false
  },
  {
   "text": "Bear Track Landing Waterpark, 20500 Old Highway 99 Southwest, Centralia, WA, 98531, USA",
   "magicKey": "dHA9MCN0dj0xZWJkOWY4YiNsb2M9MjM4NzI0NjcjbG5nPTQxI3BsPTE5MTI2MDk3I2ZhPTY1NTM2I2xicz0xNDoxMjQ2MTcyOSNsbj1Xb3JsZA==",
   "isCollection": false
  },
  {
   "text": "Bear Track Landing, Great Wolf Drive, Mason, OH, 45040, USA",
   "magicKey": "dHA9MCN0dj0xZWJkOWY4YiNsb2M9MTY4MTk1NzgjbG5nPTQxI3BsPTEzODg0ODAwI2xicz0xNDoxMjQ2MTcyNyNsbj1Xb3JsZA==",
   "isCollection": false
  },
  {
   "text": "Beardy Waters Woodlands, 15237 Gwydir Highway, Shannon Vale, Glen Innes Severn, New South Wales, 2370, AUS",
   "magicKey": "dHA9MCN0dj0xZWJkOWY4YiNsb2M9NDEzOTI5NzcjbG5nPTQxI3BsPTM4ODIwOTUzI2ZhPTE5NjYwOCNsYnM9MTQ6MTI0NjQ1MzUjbG49V29ybGQ=",
   "isCollection": false
  }
 ]
}

See Category filtering for details.

Use the `preferredLabelValues` parameter with suggest

The preferredLabelValues 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 preferredLabelValues 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 preferredLabelValues 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

Use dark colors for code blocksCopy
GET https://geocode-api.arcgis.com/arcgis/rest/services/World/GeocodeServer/suggest?text=9001 W 62nd St&preferredLabelValues=&f=pjson&token=<ACCESS_TOKEN>

Use dark colors for code blocksCopy
{
 "suggestions": [
  {
   "text": "9001 W 62nd St, Mission, KS, 66202, USA",
   "magicKey": "dHA9MCN0dj0xZWJkOWY4YiNsb2M9ODQ4NDM1MSNsbmc9NDEjZmE9NjU1MzYjaG49OTAwMSNsYnM9MTA5Ojc2OTkzNzY5I2xuPVdvcmxk",
   "isCollection": false
  },
  {
   "text": "9001 W 62nd St, Indianapolis, IN, 46278, USA",
   "magicKey": "dHA9MCN0dj0xZWJkOWY4YiNsb2M9NzI3OTc3NCNsbmc9NDEjaG49OTAwMSNsYnM9MTA5Ojc2OTkzNzY5I2xuPVdvcmxk",
   "isCollection": false
  },
  {
   "text": "9001 W 62nd St S, Monroe, IA, 50170, USA",
   "magicKey": "dHA9MCN0dj0xZWJkOWY4YiNsb2M9Nzg1NjkxMSNsbmc9NDEjaG49OTAwMSNsYnM9MTA5Ojc2OTkzNzcxI2xuPVdvcmxk",
   "isCollection": false
  },
  {
   "text": "9001 62nd St S, Cottage Grove, MN, 55016, USA",
   "magicKey": "dHA9NCN0dj0xZWJkOWY4YiNubT05MDAxIDYybmQgU3QgUywgQ290dGFnZSBHcm92ZSwgTU4sIDU1MDE2LCBVU0EjbG5nPTQxI2xuPVdvcmxk",
   "isCollection": false
  },
  {
   "text": "9001 62nd St, Newaygo, MI, 49337, USA",
   "magicKey": "dHA9MCN0dj0xZWJkOWY4YiNsb2M9MTA2NjI4MjYjbG5nPTQxI2huPTkwMDEjbGJzPTEwOTo4Nzk5NjgxNCNsbj1Xb3JsZA==",
   "isCollection": false
  }
 ]
}

The preferredLabelValues parameter can be used to return a more suitable city name for this address in suggestions. Pass preferredLabelValues=localCity 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

Use dark colors for code blocksCopy
GET https://geocode-api.arcgis.com/arcgis/rest/services/World/GeocodeServer/suggest?text=9001 W 62nd St&preferredLabelValues=localCity&f=pjson&token=<ACCESS_TOKEN>

Use dark colors for code blocksCopy
{
 "suggestions": [
  {
   "text": "9001 W 62nd St, Merriam, KS, 66202, USA",
   "magicKey": "dHA9MCN0dj0xZWJkOWY4YiNsb2M9ODQ4NDM1MSNsbmc9NDEjZmE9NjU1MzYjaG49OTAwMSNsYnM9MTA5Ojc2OTkzNzY5I2xuPVdvcmxk",
   "isCollection": false
  },
  {
   "text": "9001 W 62nd St, Indianapolis, IN, 46278, USA",
   "magicKey": "dHA9MCN0dj0xZWJkOWY4YiNsb2M9NzI3OTc3NCNsbmc9NDEjaG49OTAwMSNsYnM9MTA5Ojc2OTkzNzY5I2xuPVdvcmxk",
   "isCollection": false
  },
  {
   "text": "9001 W 62nd St S, Fairview, IA, 50170, USA",
   "magicKey": "dHA9MCN0dj0xZWJkOWY4YiNsb2M9Nzg1NjkxMSNsbmc9NDEjaG49OTAwMSNsYnM9MTA5Ojc2OTkzNzcxI2xuPVdvcmxk",
   "isCollection": false
  },
  {
   "text": "9001 62nd St S, Cottage Grove, MN, 55016, USA",
   "magicKey": "dHA9NCN0dj0xZWJkOWY4YiNubT05MDAxIDYybmQgU3QgUywgQ290dGFnZSBHcm92ZSwgTU4sIDU1MDE2LCBVU0EjbG5nPTQxI2xuPVdvcmxk",
   "isCollection": false
  },
  {
   "text": "9001 62nd St, Croton, MI, 49337, USA",
   "magicKey": "dHA9MCN0dj0xZWJkOWY4YiNsb2M9MTA2NjI4MjYjbG5nPTQxI2huPTkwMDEjbGJzPTEwOTo4Nzk5NjgxNCNsbj1Xb3JsZA==",
   "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 preferredLabelValues=localCity , postal city name Mission is used in suggestions instead of local city name Merriam, even though localCity 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 preferredLabelValues parameter (refer to the top suggestion in the response for this example).

Return suggestions using preferredLabelValues=localCity

Use dark colors for code blocksCopy
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>

Use dark colors for code blocksCopy
{
 "suggestions": [
  {
   "text": "9001 W 62nd St, Mission, KS, 66202, USA",
   "magicKey": "dHA9MCN0dj0xZWJkOWY4YiNsb2M9ODQ4NDM1MSNsbmc9NDEjZmE9NjU1MzYjaG49OTAwMSNsYnM9MTA5Ojc2OTkzNzY5Ozk6NDg3NjIwODEjbG49V29ybGQ=",
   "isCollection": false
  },
  {
   "text": "9001 W 62nd St, Merriam, KS, 66202, USA",
   "magicKey": "dHA9MCN0dj0xZWJkOWY4YiNsb2M9ODI2MDkwMSNsbmc9NDEjaG49OTAwMSNsYnM9MTA5Ojc2OTkzNzY5I2xuPVdvcmxk",
   "isCollection": false
  },
  {
   "text": "9001 62nd St, Croton, MI, 49337, USA",
   "magicKey": "dHA9MCN0dj0xZWJkOWY4YiNsb2M9MTA2NjI4MjYjbG5nPTQxI2huPTkwMDEjbGJzPTEwOTo4Nzk5NjgxNDsyOjQ0OTcxOTI4I2xuPVdvcmxk",
   "isCollection": false
  },
  {
   "text": "9001 62nd St, Geneva, MI, 49090, USA",
   "magicKey": "dHA9MCN0dj0xZWJkOWY4YiNsb2M9MTA3NDA5OTcjbG5nPTQxI2huPTkwMDEjbGJzPTEwOTo4Nzk5NjgxNDsyOjQ0OTcxOTI4I2xuPVdvcmxk",
   "isCollection": false
  },
  {
   "text": "9001 62nd St S, Cottage Grove, MN, 55016, USA",
   "magicKey": "dHA9NCN0dj0xZWJkOWY4YiNubT05MDAxIDYybmQgU3QgUywgQ290dGFnZSBHcm92ZSwgTU4sIDU1MDE2LCBVU0EjbG5nPTQxI2xuPVdvcmxk",
   "isCollection": false
  }
 ]
}

When the preferredLabelValues parameter is used for suggest , it should also be used in the corresponding findAddressCandidates 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 findAddressCandidates with preferredLabelValues=localCity included in the request, the resulting response will include Merriam as the city name in labels instead of Mission. This is because findAddressCandidates always honors the preferredLabelValues parameter, unlike suggest , for which matching the user input is prioritized:

Use findAddressCandidates with magicKey when preferredLabelValues=localCity

Use dark colors for code blocksCopy
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=dHA9MCN0dj0xZWJkOWY4YiNsb2M9ODQ4NDM1MSNsbmc9NDEjZmE9NjU1MzYjaG49OTAwMSNsYnM9MTA5Ojc2OTkzNzY5Ozk6NDg3NjIwODEjbG49V29ybGQ=&preferredLabelValues=localCity&token=<ACCESS_TOKEN>

findAddressCandidates JSON response

Use dark colors for code blocksCopy
{
 "spatialReference": {
  "wkid": 4326,
  "latestWkid": 4326
 },
 "candidates": [
  {
   "address": "9001 W 62nd St, Merriam, Kansas, 66202",
   "location": {
    "x": -94.689810655401,
    "y": 39.01695801365
   },
   "score": 100,
   "attributes": {
    "Match_addr": "9001 W 62nd St, Merriam, Kansas, 66202",
    "City": "Merriam"
   },
   "extent": {
    "xmin": -94.690810655401,
    "ymin": 39.01595801365,
    "xmax": -94.688810655401,
    "ymax": 39.01795801365
   }
  }
 ]
}

Refer to the findAddressCandidates topic for more information about how the preferredLabelValues parameter can be used with that operation.

Suggestions for partial house number input

Suggestions can be returned for address input with incomplete house numbers by using the partialHouseNumber parameter. This can be useful for applications where a list of potential addresses to choose from is needed.

The parameter is only functional for address formats where the street name is followed by the house number.

Example ("Verlengde Nieuwstraat 1")

Use dark colors for code blocksCopy
GET https://geocode-api.arcgis.com/arcgis/rest/services/World/GeocodeServer/suggest?text=Verlengde Nieuwstraat 1&location=4.487,51.92&partialHouseNumber=true&f=pjson&token=<ACCESS_TOKEN>

Use dark colors for code blocksCopy
{
 "suggestions": [
  {
   "text": "Verlengde Nieuwstraat 101, 3011 GX Rotterdam, NLD",
   "magicKey": "dHA9MCN0dj0xZWJkOWY4YiNsb2M9NzE0OTEwODcjbG5nPTM5I2ZhPTMwODAxOTIjaG49MTAxI2V4dD1HWCNsYnM9MTA5Ojk1OTI4NDQ1I2xuPVdvcmxk",
   "isCollection": false
  },
  {
   "text": "Verlengde Nieuwstraat 103, 3011 GX Rotterdam, NLD",
   "magicKey": "dHA9MCN0dj0xZWJkOWY4YiNsb2M9NzE0OTEwODcjbG5nPTM5I2ZhPTMxNDU3MjgjaG49MTAzI2V4dD1HWCNsYnM9MTA5Ojk1OTI4NDQ1I2xuPVdvcmxk",
   "isCollection": false
  },
  {
   "text": "Verlengde Nieuwstraat 105, 3011 GX Rotterdam, NLD",
   "magicKey": "dHA9MCN0dj0xZWJkOWY4YiNsb2M9NzE0OTEwODcjbG5nPTM5I2ZhPTMyMTEyNjQjaG49MTA1I2V4dD1HWCNsYnM9MTA5Ojk1OTI4NDQ1I2xuPVdvcmxk",
   "isCollection": false
  },
  {
   "text": "Verlengde Nieuwstraat 107, 3011 GX Rotterdam, NLD",
   "magicKey": "dHA9MCN0dj0xZWJkOWY4YiNsb2M9NzE0OTEwODcjbG5nPTM5I2ZhPTMyNzY4MDAjaG49MTA3I2V4dD1HWCNsYnM9MTA5Ojk1OTI4NDQ1I2xuPVdvcmxk",
   "isCollection": false
  },
  {
   "text": "Verlengde Nieuwstraat 109, 3011 GX Rotterdam, NLD",
   "magicKey": "dHA9MCN0dj0xZWJkOWY4YiNsb2M9NzE0OTEwODcjbG5nPTM5I2ZhPTMzNDIzMzYjaG49MTA5I2V4dD1HWCNsYnM9MTA5Ojk1OTI4NDQ1I2xuPVdvcmxk",
   "isCollection": false
  }
 ]
}

Suggestions for partial subunit input

Suggestions can be returned for Subaddress input with incomplete subunit values by using the partialSubaddress parameter. It allows you to see a list of Subaddresses to choose from at a particular location.

Example ("333 S Hope St #1")

Use dark colors for code blocksCopy
GET https://geocode-api.arcgis.com/arcgis/rest/services/World/GeocodeServer/suggest?text=333 S Hope St %231&partialSubaddress=true&maxSuggestions=10&f=pjson&token=<ACCESS_TOKEN>

Use dark colors for code blocksCopy
{
 "suggestions": [
  {
   "text": "333 S Hope St, Suite 10, Los Angeles, CA, 90071, USA",
   "magicKey": "dHA9MCN0dj01ODg2MWNiI2xvYz0yNjE0ODI1I2xuZz00MSNmYT02NTUzNzAjaG49MzMzI2xicz0xMDk6NjI5ODc4OTAjbGJzZXh0PTQzOjEwOzQwOlN1aXRlI2xuPVdvcmxk",
   "isCollection": false
  },
  {
   "text": "333 S Hope St, Suite 11, Los Angeles, CA, 90071, USA",
   "magicKey": "dHA9MCN0dj01ODg2MWNiI2xvYz0yNjE0ODI1I2xuZz00MSNmYT02NTU0MTkjaG49MzMzI2V4dD0xNDk3I2xicz0xMDk6NjI5ODc4OTAjbGJzZXh0PTQzOjExOzQwOlN1aXRlI2xuPVdvcmxk",
   "isCollection": false
  },
  {
   "text": "333 S Hope St, Suite 12, Los Angeles, CA, 90071, USA",
   "magicKey": "dHA9MCN0dj01ODg2MWNiI2xvYz0yNjE0ODI1I2xuZz00MSNmYT02NTUzOTgjaG49MzMzI2V4dD0xNDk1I2xicz0xMDk6NjI5ODc4OTAjbGJzZXh0PTQzOjEyOzQwOlN1aXRlI2xuPVdvcmxk",
   "isCollection": false
  },
  {
   "text": "333 S Hope St, Suite 13, Los Angeles, CA, 90071, USA",
   "magicKey": "dHA9MCN0dj01ODg2MWNiI2xvYz0yNjE0ODI1I2xuZz00MSNmYT02NTUzODEjaG49MzMzI2xicz0xMDk6NjI5ODc4OTAjbGJzZXh0PTQzOjEzOzQwOlN1aXRlI2xuPVdvcmxk",
   "isCollection": false
  },
  {
   "text": "333 S Hope St, Suite 14, Los Angeles, CA, 90071, USA",
   "magicKey": "dHA9MCN0dj01ODg2MWNiI2xvYz0yNjE0ODI1I2xuZz00MSNmYT02NTU0MTAjaG49MzMzI2xicz0xMDk6NjI5ODc4OTAjbGJzZXh0PTQzOjE0OzQwOlN1aXRlI2xuPVdvcmxk",
   "isCollection": false
  },
  {
   "text": "333 S Hope St, Suite 16, Los Angeles, CA, 90071, USA",
   "magicKey": "dHA9MCN0dj01ODg2MWNiI2xvYz0yNjE0ODI1I2xuZz00MSNmYT02NTU0MjQjaG49MzMzI2V4dD0xNDEwI2xicz0xMDk6NjI5ODc4OTAjbGJzZXh0PTQzOjE2OzQwOlN1aXRlI2xuPVdvcmxk",
   "isCollection": false
  },
  {
   "text": "333 S Hope St, Suite 17, Los Angeles, CA, 90071, USA",
   "magicKey": "dHA9MCN0dj01ODg2MWNiI2xvYz0yNjE0ODI1I2xuZz00MSNmYT02NTUzODYjaG49MzMzI2V4dD0xNDExI2xicz0xMDk6NjI5ODc4OTAjbGJzZXh0PTQzOjE3OzQwOlN1aXRlI2xuPVdvcmxk",
   "isCollection": false
  },
  {
   "text": "333 S Hope St, Suite 18, Los Angeles, CA, 90071, USA",
   "magicKey": "dHA9MCN0dj01ODg2MWNiI2xvYz0yNjE0ODI1I2xuZz00MSNmYT02NTUzODgjaG49MzMzI2V4dD0xNDMwI2xicz0xMDk6NjI5ODc4OTAjbGJzZXh0PTQzOjE4OzQwOlN1aXRlI2xuPVdvcmxk",
   "isCollection": false
  },
  {
   "text": "333 S Hope St, Suite 19, Los Angeles, CA, 90071, USA",
   "magicKey": "dHA9MCN0dj01ODg2MWNiI2xvYz0yNjE0ODI1I2xuZz00MSNmYT02NTUzODUjaG49MzMzI2V4dD0xNDk0I2xicz0xMDk6NjI5ODc4OTAjbGJzZXh0PTQzOjE5OzQwOlN1aXRlI2xuPVdvcmxk",
   "isCollection": false
  },
  {
   "text": "333 S Hope St, Suite 1100, Los Angeles, CA, 90071, USA",
   "magicKey": "dHA9MCN0dj01ODg2MWNiI2xvYz0yNjE0ODI1I2xuZz00MSNmYT02NTU0MDEjaG49MzMzI2V4dD0xNDk3I2xicz0xMDk6NjI5ODc4OTAjbGJzZXh0PTQzOjExMDA7NDA6U3VpdGUjbG49V29ybGQ=",
   "isCollection": false
  }
 ]
}

Summarize subunits at an address

The subaddressSummary parameter provides information about the Subaddresses that are associated with an input PointAddress in the suggestion for the address. The information is presented within parenthesis in the suggestion label as either a count of total Subaddresses ("900 Wilshire Blvd (190 units), Los Angeles, CA") or a range of subunit values (60 Queen St W (Unit 8-351), Toronto, ON").

Example ("60 Queen St W")

Use dark colors for code blocksCopy
GET https://geocode-api.arcgis.com/arcgis/rest/services/World/GeocodeServer/suggest?text=60 Queen St W&subaddressSummary=true&f=pjson&token=<ACCESS_TOKEN>

Use dark colors for code blocksCopy
{
 "suggestions": [
  {
   "text": "60 Queen St W (Unit 8-351), Toronto, ON, M5H 2M3, CAN",
   "magicKey": "dHA9MCN0dj0xZWJkOWY4YiNsb2M9MjYxMzc1NTUjbG5nPTQxI2ZhPTQ1ODc1MiNobj02MCNsYnM9MTA5Ojk0MTU4NjY0I2xuPVdvcmxk",
   "isCollection": false
  },
  {
   "text": "60 Queen St W, Cambridge, ON, N3C 1G1, CAN",
   "magicKey": "dHA9MCN0dj0xZWJkOWY4YiNsb2M9MjYxNTA4ODkjbG5nPTQxI2ZhPTEzNzYyNTYjaG49NjAjbGJzPTEwOTo5NDE1ODY2NCNsbj1Xb3JsZA==",
   "isCollection": false
  },
  {
   "text": "60 Queen St W, Norfolk County, ON, N0E 1P0, CAN",
   "magicKey": "dHA9MCN0dj0xZWJkOWY4YiNsb2M9MjU5MzIzMDUjbG5nPTQxI2ZhPTI0OTAzNjgjaG49NjAjbGJzPTEwOTo5NDE1ODY2NCNsbj1Xb3JsZA==",
   "isCollection": false
  },
  {
   "text": "60 Queen St, Newtown, CT, 06470, USA",
   "magicKey": "dHA9MCN0dj0xZWJkOWY4YiNsb2M9MzcxMDEyNiNsbmc9NDEjZmE9MjY4Njk3NiNobj02MCNsYnM9MTA5Ojk0MTU4NjUyOzM6NzgyMDM0NDMjbG49V29ybGQ=",
   "isCollection": false
  },
  {
   "text": "60 Queen St, North Kingstown, RI, 02852, USA",
   "magicKey": "dHA9MCN0dj0xZWJkOWY4YiNsb2M9MTkyNTQ0NDAjbG5nPTQxI2ZhPTI2MjE0NCNobj02MCNsYnM9MTA5Ojk0MTU4NjUyOzM6Nzc4MTkwMDQjbG49V29ybGQ=",
   "isCollection": false
  }
 ]
}

Show Subaddresses at an address

The subaddressAfterBaseAddress parameter provides a list of Subaddresses that are associated with an input PointAddress.

The subaddressAfterBaseAddress and subaddressSummary parameters complement each other, and may be used together in a request to get a more complete picture of the Subaddresses that exist at a PointAddress location.

Example ("424 Church St, Nashville, TN")

Use dark colors for code blocksCopy
GET https://geocode-api.arcgis.com/arcgis/rest/services/World/GeocodeServer/suggest?text=424 Church St, Nashville, TN&subaddressAfterBaseAddress=true&f=pjson&token=<ACCESS_TOKEN>

Use dark colors for code blocksCopy
{
 "suggestions": [
  {
   "text": "424 Church St, Nashville, TN, 37219, USA",
   "magicKey": "dHA9MCN0dj0xZWJkOWY4YiNsb2M9MjAzNDg2MDEjbG5nPTQxI2ZhPTQ1ODc1MiNobj00MjQjbGJzPTEwOTo4OTUwNjQyNTs5OjUxNTQ2NzczOzI6NzA4OTI2OTkjbG49V29ybGQ=",
   "isCollection": false
  },
  {
   "text": "424 Church St, Suite 1, Nashville, TN, 37219, USA",
   "magicKey": "dHA9MCN0dj0xZWJkOWY4YiNsb2M9MjAzNDg2MDEjbG5nPTQxI2ZhPTQ1ODc5MSNobj00MjQjbGJzPTEwOTo4OTUwNjQyNTs5OjUxNTQ2NzczOzI6NzA4OTI2OTkjbG49V29ybGQ=",
   "isCollection": false
  },
  {
   "text": "424 Church St, Suite 2, Nashville, TN, 37219, USA",
   "magicKey": "dHA9MCN0dj0xZWJkOWY4YiNsb2M9MjAzNDg2MDEjbG5nPTQxI2ZhPTQ1ODc2MSNobj00MjQjbGJzPTEwOTo4OTUwNjQyNTs5OjUxNTQ2NzczOzI6NzA4OTI2OTkjbG49V29ybGQ=",
   "isCollection": false
  },
  {
   "text": "424 Church St, Suite 3, Nashville, TN, 37219, USA",
   "magicKey": "dHA9MCN0dj0xZWJkOWY4YiNsb2M9MjAzNDg2MDEjbG5nPTQxI2ZhPTQ1OTAyNyNobj00MjQjbGJzPTEwOTo4OTUwNjQyNTs5OjUxNTQ2NzczOzI6NzA4OTI2OTkjbG49V29ybGQ=",
   "isCollection": false
  },
  {
   "text": "424 Church St, Suite 4, Nashville, TN, 37219, USA",
   "magicKey": "dHA9MCN0dj0xZWJkOWY4YiNsb2M9MjAzNDg2MDEjbG5nPTQxI2ZhPTQ1ODkzOSNobj00MjQjbGJzPTEwOTo4OTUwNjQyNTs5OjUxNTQ2NzczOzI6NzA4OTI2OTkjbG49V29ybGQ=",
   "isCollection": false
  }
 ]
}

Parameters

Required parameters

f

token

text

Optional parameters

location

category

searchExtent

maxSuggestions

countryCode

sourceCountry

preferredLabelValues

returnCollections

partialHouseNumber

partialSubaddress

subaddressSummary

subaddressAfterBaseAddress

Response status

Response details

Examples

Get suggestions using location

Get suggestions without location

Limit suggestions to a specified area

Get suggestions using searchExtent

Get suggestions using searchExtent with a JSON envelope object

Utilize the isCollection property

Get the isCollection property

Using a suggest result when isCollection=true

Use a suggest result when isCollection=false

Disable collections

Disable collections by using returnCollections=false

Enable collections by using returnCollections=true

Specify the number of suggestions

Limit suggestions by country

Filter categories

Get suggestions for "Bear" without category

Get suggestions for "Bear" with category=Amusement Park

Use the preferredLabelValues parameter with suggest

Return suggestions without using preferredLabelValues

Return suggestions using preferredLabelValues=localCity

Return suggestions using preferredLabelValues=localCity

Use findAddressCandidates with magicKey when preferredLabelValues=localCity

Suggestions for partial house number input

Example ("Verlengde Nieuwstraat 1")

Suggestions for partial subunit input

Example ("333 S Hope St #1")

Summarize subunits at an address

Example ("60 Queen St W")

Show Subaddresses at an address

Example ("424 Church St, Nashville, TN")

Get suggestions using `location`

Using a suggest result when `isCollection=true`

Use a suggest result when `isCollection=false`

Use the `preferredLabelValues` parameter with suggest