SearchEngine

public class SearchEngine : AbstractSearchEngine
extension SearchEngine: IndexableDataResolver

An entry object for online search with autocomplete suggestions powered by Mapbox Search services

SearchEngine requires Mapbox Access Token with any scope and visibility. We recommend to pass your token through MBXAccessToken key in application’s Info.plist to share the token with the Mapbox SDKs. You may choose to provide the accessToken as a parameter value instead.

You must always assign delegate to receive search results provided by the engine. Update the SearchEngine.query value to start or continue your search experience. It is possible to update query value in real-time as the user types because the actual requests have a debounce logic.

Listing 1 Create you first search request

let engine = SearchEngine()
engine.delegate = self
engine.query = "Mapbox"

Implement SearchEngineDelegate protocol to receive updates and search results with coordinates data. Pay attention that SearchEngine provides a list of SearchSuggestion which doesn’t include coordinates information.

Listing 2 Implement SearchEngineDelegate protocol

   extension ViewController: SearchEngineDelegate {
       func resultsUpdated(searchEngine: SearchEngine) {
           displaySearchResults(searchEngine)
       }

       func resolvedResult(result: SearchResult) {
           presentSelectedResult(result)
       }

       func searchErrorHappened(searchError: SearchError) {
           presentSearchError(searchError)
       }
   }

Retrieve coordinates

Call select(suggestion: SearchSuggestion) when a customer makes a choice from the search results list to receive a SearchResult with populated coordinates field. You can expect a resolved search result with populated coordinates to be returned in SearchEngineDelegate.resolvedResult(result: SearchResult) delegate method.

Listing 3 Select search result

   override func tableView(_ tableView: UITableView, didSelectRowAt indexPath: IndexPath) {
       let suggestion = searchSuggestions[indexPath.row]

       dataSource.select(suggestion: suggestion)
   }

   
   // SearchEngineDelegate implementation
   func resolvedResult(result: SearchResult) {
       presentAnnotationAt(coordinate: result.coordinate,
                                title: result.name,
                             subtitle: result.address?.formattedAddress(style: .medium))
   }

Note

SearchEngine may respond with category suggestion. Selecting such suggestion would produce a new set of search results.

Location bias

Location is strongly recommended for accurate search results. By default, SearchEngine would anticipate DefaultLocationProvider to fulfill location data. DefaultLocationProvider would receive location updates if application already have a location permission. The default implementation declare low accuracy for better battery efficiency. It’s possible to provide exact coordinate for search request with search(query:options:) function. Engine will reuse these coordinates on each search request. To reset to default LocationProvider behavior, call search(query:options:) with nil proximity in SearchRequest.

Listing 4 Provide search coordinate

   let engine = SearchEngine()
   engine.search(query: "mapbox", options: SearchOptions(proximity: CLLocationCoordinate2D(latitude: 38.8998315, longitude: -77.0346164)))
  • Offline mode types

    See more

    Declaration

    Swift

    public enum OfflineMode
  • Offline mode state for engine

    Declaration

    Swift

    public private(set) var offlineMode: OfflineMode { get }
  • Set new offline mode. Enabling may take some to SearchEngine to detect all reagins in current TileStore

    Declaration

    Swift

    public func setOfflineMode(_ mode: OfflineMode, completion: (() -> Void)?)

    Parameters

    mode

    offline mode Enable/Disable

    completion

    called once SearchEngine ready for offline search

  • Delegate is required for SearchEngine interaction

    Declaration

    Swift

    public weak var delegate: SearchEngineDelegate?
  • Current search suggestions results.

    Declaration

    Swift

    public private(set) var suggestions: [SearchSuggestion] { get }
  • Search response information for current search items. Can be used for submitting missing result feedback

    Declaration

    Swift

    public private(set) var responseInfo: SearchResponseInfo? { get }
  • Actual search query. New value starts new search request in short amount of time. New search will reuse latest requestOptions

    Declaration

    Swift

    public var query: String { get set }
  • Start searching for query with provided options

    Declaration

    Swift

    public func search(query: String, options: SearchOptions? = nil)

    Parameters

    query

    query string to search

    options

    if no value provided Search Engine will use options from requestOptions field

  • Select one of the provided SearchSuggestion‘s. Search flow would continue if category suggestion was selected.

    Declaration

    Swift

    public func select(suggestion: SearchSuggestion)

    Parameters

    suggestion

    Suggestion to continue the search and retrieve resolved SearchResult via delegate.

  • Function to select multiple suggestions at once. With the current implementation, only POI suggestions support batch resolving. All suggestions must originate from the same search request. Suggestions with other types will be ignored. You can use SearchSuggestion.batchResolveSupported field for filtering.

    Declaration

    Swift

    public func select(suggestions: [SearchSuggestion])

    Parameters

    suggestions

    suggestions list to resolve. All suggestions must originate from the same search request.

  • Reverse geocoding of coordinates to addresses. The default behavior in reverse geocoding is to return at most one feature at each of the multiple levels of the administrative hierarchy (for example, one address, one region, one country). Increasing the limit allows returning multiple features of the same type, but only for one type (for example, multiple address results). Consequently, setting limit to a higher-than-default value requires specifying exactly one types parameter.

    Declaration

    Swift

    public func reverse(
        options: ReverseGeocodingOptions,
        completion: @escaping (Result<[SearchResult], SearchError>) -> Void
    )

    Parameters

    options

    Options with coordinates, mode, limits and query types for reverse geocoding.

    completion

    completion handler with either reverse geocoding Resuts or Error.