Search SDK for iOS

The Mapbox Search SDK for iOS gives you the tools you need to add a search experience to your application. The Search SDK consists of various components that can be used standalone or combined together so you can build something truly custom. It takes only a few minutes to drop a pre-built user interface into your application.

Structure of the Search SDK

The Search SDK consists of two frameworks: Search Core (MapboxSearch) and the Search UI SDK (MapboxSearchUI).

Search Core

Search Core contains the logic that automatically handles configuring, sending, and parsing responses to requests. This code automatically integrates with the device to access its location and language settings and caches results on-device. It also powers the Search UI SDK.

Search UI SDK

The Search UI SDK is built on top of Search Core and provides ready-made search UI elements that you can use to add a search experience to your app. You can adjust the style of various elements of the pre-configured UI and customize results.

Search types

Single-box search

The Search SDK offers single-box search, which allows you to search by either place name, address, or category. There are two search engines available:

• Search: The SearchEngine class allows you to get the location of places by typing place names or addresses. This is also known as forward geocoding. For example, you can type in Lincoln Memorial and retrieve the geographic location of a place that matches that query (-77.050,38.889).
• Category search: The CategorySearchEngine class allows you to select a category (for example, restaurants) and retrieve a list of points of interest (POIs) that belong to that category. For example, if you want to display many restaurants within walking distance of a theater on a map, you can use category search with the restaurants category.

Reverse geocoding

You can also use the SearchEngine class to perform reverse geocoding. Reverse geocoding allows you to search for place names and addresses by providing geographic coordinates. For example, entering -77.050, 38.889 and retrieve 2 Lincoln Memorial Circle NW.

History and favorites

If a user has searched in your app before, the Search SDK will always suggest results from their search history. If the user also has a list of favorite search results, the SDK will suggest recent results as well as any favorites that match the query.

History

History is a list of the most recent search results selected on a device. The Search SDK automatically adds to a user’s history every time a result is selected.

The Search UI SDK uses history in two ways:

• When a user clicks on the empty search bar the SDK will automatically show recent searches in reverse chronological order.
• When a user starts to type a query the SDK will use the history to populate the suggestions drop down.

You can also access a device’s history using Search Core via ServiceProvider (ServiceProvider.shared.localHistoryProvider).

Favorites

Favorites is a list of past searches that a user has explicitly added to the list.

The Search UI SDK uses favorites in two ways:

• Users can click the star icon in the list of results to open the favorites menu where they can save the place.
• The user can manage their favorites through the “Favorites” component option where they can remove or rename their favorites.

You can also access a device’s favorites using Search Core via ServiceProvider(ServiceProvider.shared.localFavoritesProvider).

Why use SDK?

If your primary use case is targeted to mobile devices (iOS & Android), we strongly encourage you to use our Search SDK. With Search SDK, you get:

Stable SDK API

By defining our use cases, we aim to support the same interface for longer even if the underlying implementation changes. This means bumping the SDK version fixes all issues you might encounter without requiring you to rework the app or its integration code.

Fewer lines of code

Developers can get up and running with a few lines of straightforward code to start the SDK. See for yourself, it’s readable, maintainable, and error-proof.

Protecting against errors and pitfalls

Having a ready-made integration example enables you to experiment faster and avoid common pitfalls of using API in a non-preferred way.

Drop-in UI support

Have no need for custom UI and ready to get started? We have you covered with an easy-to-blend UI that doesn’t require extensive binding to current components and navigation flow.

Requirements

The Mapbox Search SDK for iOS can be used with iOS 11.0 and Xcode 11.3.

Pricing

Search SDK usage is measured in Temporary Geocoding API requests. See our pricing page for more details.