Search SDK for iOS

Search SDK for iOS

Current version: v1.0.0-beta.1

  • Add pre-built UI components to your app
  • Search for places by name, category, or coordinate
  • Save your favorite places
  • Access your search history

The Mapbox Search SDK for iOS gives you the tools you need to add a search experience to your application. It takes only a few minutes to drop a pre-built user interface (UI) powered by the Mapbox Geocoding API into your application. We also make the core search logic that powers the UI available to you directly so you can build something truly custom.

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

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


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

Install the Search SDK

To use the Search SDK, you'll need to configure your credentials and add the SDK as a dependency.

Configure credentials

Before installing the SDK, you will need to gather the appropriate credentials. The SDK requires two pieces of sensitive information from your Mapbox account. If you don't have a Mapbox account: sign up and navigate to your Account page. You'll need:

  • A public access token: From your account's tokens page, you can either copy your default public token or click the Create a token button to create a new public token.
  • A secret access token with the Downloads:Read scope.
    1. From your account's tokens page, click the Create a token button.
    2. From the token creation page, give your token a name and make sure the box next to the Downloads:Read scope is checked.
    3. Click the Create token button at the bottom of the page to create your token.
    4. The token you've created is a secret token, which means you will only have one opportunity to copy it somewhere secure.

You should not expose these access tokens in publicly-accessible source code where unauthorized users might find them. Instead, you should store them somewhere safe on your computer and make sure they're only added when your app is compiled. Once this configuration step has been completed, you will be able to reference your credentials in other parts of your app.

Configure your secret token

Your secret token enables you to download the SDK directly from Mapbox. In order to use your secret token, you will need to store it a .netrc file in your home directory. This approach helps avoid accidentally exposing your secret token by keeping it out of your application's source code. Depending on your environment, you may have this file already, so check first before creating a new one.

The .netrc file is a plain text file that is used in certain development environments to store credentials used to access remote servers. To set up the credentials required to download the SDK, add the following entry to your .netrc file:

login mapbox

Configure your public token

To configure your public access token, open your project's Info.plist file and add a MGLMapboxAccessToken key whose value is your public access token.

If you ever need to rotate your access token, you will need to update the token value in your Info.plist file accordingly.

Add the dependency

Mapbox provides the Search SDK via CocoaPods.

To add the Mapbox Search SDK dependency with CocoaPods, you will need to configure your build to download the Search SDK from Mapbox directly. This requires a valid username and an access token with the Downloads: Read scope. In a previous step, you added these items to your .netrc file.

  1. Add the dependency to your Podfile. There are two options:

    • Option 1: To use the Search SDK with pre-built UI components, add the MapboxSearchUI dependency. This will also include MapboxSearch automatically.
    target "TargetNameForYourApp" do
      pod 'MapboxSearchUI', ">= 1.0.0-beta.1", "< 2.0"
    • Option 2: To use the Search SDK without pre-built UI components, add the MapboxSearch dependency.
    target "TargetNameForYourApp" do
      pod 'MapboxSearch', ">= 1.0.0-beta.1", "< 2.0"
  2. Run pod install to install the dependency.

Add search to an app

You can start by adding a search UI to your application using Swift.

Insert the following code snippets into your ViewController.

import UIKit
import MapboxSearch
import MapboxSearchUI
class ViewController: UIViewController {
let searchController = MapboxSearchController()
override func viewDidLoad() {
searchController.delegate = self
let panelController = MapboxPanelController(rootViewController: searchController)
extension ViewController: SearchControllerDelegate {
func searchResultSelected(_ searchResult: SearchResult) { }
func categorySearchResultsReceived(results: [SearchResult]) { }
func userFavoriteSelected(_ userFavorite: FavoriteRecord) { }

Run your application and you will see a functional search UI. Begin typing in the search bar or click on a category to see results.


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

Was this page helpful?