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 YMKSearchManager class or use an existing one.

   let searchManager = YMKSearch.sharedInstance().createSearchManager(with: .combined)
   

2. Use the YMKSearchManager.createSuggestSession() method to instantiate a Geosuggest session.

   let suggestSession = searchManager.createSuggestSession()
   

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

   Example of parameter values for limiting the search to organizations:

   let suggestOptions = {
       let options = YMKSuggestOptions()
       options.suggestTypes: .biz
   }()
   

4. Using YMKSearchSuggestSession.suggest(withText:window:suggestOptions:responseHandler:), 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(
       withText: "ho",
       window: YMKBoundingBox(
           southWest: map.visibleRegion.bottomLeft,
           northEast: map.visibleRegion.topRight
       ),
       suggestOptions: suggestOptions,
       responseHandler: handleSuggestSessionResponse
   )
   

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

   func handleSuggestSessionResponse(response: YMKSuggestResponse?, error: Error?) {
       if let error {
           // Handle geo suggest error
           return
       }
   
       // Handle geo suggest response
   }
   

   Pass this handler method as an argument whenever you call a method for creating a new geo suggestion query.

Geosuggest sessionGeosuggest session

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

This class provides the following functionality:

• YMKSearchSuggestSession.suggest(withText:window:suggestOptions:responseHandler:): 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.

• YMKSearchSuggestSession.reset(): Cancels the current query and resets the internal state of the Geosuggest session.

Geo suggestion parametersGeo suggestion parameters

With YMKSuggestOptions, 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, pass the responseHandler parameter into YMKSearchSuggestSession.suggest(withText:window:suggestOptions:responseHandler:) method. This handler will be called once the suggestion query finishes.

YMKSearchSuggestSessionResponseHandler takes two parameters:

1. response: If present, says about a successful geo suggestion query completion. The value of type YMKSuggestResponse contains information about the results of the request.

2. error: If present, says about an error, occurred while a query execution.

Suggestion dataSuggestion data

The YMKSuggestItem 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 YMKSuggestItem 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 YMKSpannableString 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 YMKSuggestItem.action, you can get the type of action to be performed when the suggestion is selected:

• search: Perform a new search query. If YMKSuggestItem.uri returns a non-null URI, a URI search is to be performed. If it's missing, search by the text from the YMKSuggestItem.searchText 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 YMKSuggestItem.displayText 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 MapSearch app in our GitHub repository.