Geosuggest

Geosuggest is a built-in functionality of the maps API for autofilling and checking the names of organizations and addresses in user search queries. When integrated with the MapKit SDK, Geosuggest can generate a list of geo suggestions and make the search query input process easier and more convenient.

Executing a geo suggestion queryExecuting a geo suggestion query

The process for executing a geo suggestion query is similar to creating a search query, but has a few important differences. To create a query, follow the steps below:

1. Create a new instance of the SearchManager class or use an existing one.

   val searchManager = SearchFactory.getInstance().createSearchManager(SearchManagerType.COMBINED)
   

2. Use the SearchManager.createSuggestSession method to instantiate a Geosuggest session.

   val suggestSession = searchManager.createSuggestSession()
   

3. Create an instance of the SuggestOptions class to set the geo suggestion query parameters.

   Example of parameter values for limiting the search to organizations:

   val suggestOptions = SuggestOptions()
       .setSuggestTypes(
           SuggestType.BIZ.value
       )
   

4. Using SuggestSession.suggest, create a new geo suggestion query.

   This example searches for available search queries that contain the "ho" prefix, such as "Hotels" and "Hospitals".

   suggestSession.suggest(
       "ho",
       BoundingBox(map.visibleRegion.bottomLeft, map.visibleRegion.topRight),
       suggestOptions,
       suggestListener,
   )
   

5. When creating the geo suggestion query, use the following mechanism to retrieve the geo suggestion results.

   val suggestListener = object : SuggestSession.SuggestListener {
       override fun onResponse(items: MutableList<SuggestItem>) {
           // Handle geo suggest response.
       }
   
       override fun onError(error: Error) {
           // Handle geo suggest error.
       }
   }
   

   Pass an implementation of this interface as an argument to the method for creating a new geo suggestion query.

Geosuggest sessionGeosuggest session

Geosuggest sessions are represented by the SuggestSession class, which is used to manage queries.

This class provides the following functionality:

• SuggestSession.suggest: Used for creating a new geo suggestion query. Accepts the following arguments:

  • text: Base text for generating search suggestions.
  • window: Current position of the map viewport.
  • Geo suggestion parameters.
  • Parameter to handle query results and errors.

• SuggestSession.reset: Cancels the current query and resets the internal state of the Geosuggest session.

Geo suggestion parametersGeo suggestion parameters

With SuggestOptions, you can set:

• suggestTypes: Type of search objects to be selected (organizations, toponyms, or public transport). This parameter is a bitmask, so you can select multiple types.

• userPosition: Current position of the user. Used to calculate the distance from the user's location to available suggestion options.

Geo suggestion resultsGeo suggestion results

To retrieve the results of a geo suggestion query, use a subscription to the SuggestListener interface. Pass an implementation of this interface whenever you call the SuggestSession.suggest method to create a geo suggestion query.

This interface provides the following events:

1. SuggestListener.onResponse: Called on successful completion of a query. Provides a list of found suggestions represented by SuggestItem objects.

2. SuggestListener.onError: Called when a query completes with an error.

Suggestion dataSuggestion data

The SuggestItem class provides a wide range of data, the key ones being:

• type: Suggestion type (toponym, organization, or public transport).
• searchText: Text to search for if this suggestion is selected.
• displayText: Text to display in the query input field.
• uri: Object URI.
• distance: Distance to the object.
• action: Type of action to be performed when this option is selected (substitution or instant search).
• distance: Distance to the search object.
• center: Position on the map.

Displaying suggestionsDisplaying suggestions

The SuggestItem class provides information for easy display of suggestions on the screen:

• title: Short title of the suggestion.
• subtitle: Position data and address.

These parameters are of the SpannableString type. This type represents a string where substrings that match the search query text entered by the user are highlighted. These substrings are supposed to be rendered in accent colors.

Processing suggestion clicksProcessing suggestion clicks

With SuggestItem.getAction, you can get the type of action to be performed when the suggestion is selected:

• SEARCH: Perform a new search query. If SuggestItem.getUri returns a non-null URI, a URI search is to be performed. If it's missing, search by the text from the SuggestItem.getSearchText method. This type is usually used when the user clicks a category name, such as "Cafe" or "Restaurant", or the name of an organization.

• SUBSTITUTE: Replace the current search query text with the text obtained from SuggestItem.getDisplayText and execute a new geo suggestion query. This is typically used when searching for addresses, where the API first substitutes the name of the city, then the street, and so on.

Source codeSource code

For an example of using geo suggestions with the MapKit SDK, see the map-search app in our GitHub repository.