Search by Category

The Category Search feature in iOS equips you with the necessary tools to incorporate Points of Interest (POI) search into your application. This feature is versatile and can be used for various search needs, such as finding nearby cafes, locating parking in a different city, or identifying Electric Vehicle (EV) charging stations along a specific route. You can add this functionality to your application with minimal coding.

Category Search options

Category search can be implemented in various ways depending on your specific use case:

Search nearby

The Search nearby use case enables users to swiftly search for Points of Interest (POIs) in the vicinity of a specified geographical point, such as their current location. For instance, you can empower your users to find cafes, shops, and parks that are within a walkable distance.

Search in the area

The Search in the area use case assists your users in discovering Points of Interest (POIs) within a selected area, such as the current map view. For instance, if a user is looking for hotels in Paris, this feature will allow them to find hotels by navigating the map.

Search along the route

The Search along the route use case allows users to search for Points of Interest (POIs), such as Electric Vehicle (EV) charging stations, while navigating between two or more locations. This feature can be particularly useful for long-distance travel, where users may need to find amenities along their route.

We provide a pre-built sample application that you can experiment with in Xcode. This application includes the text search feature among other scenarios. We encourage you to download and explore it firsthand.

EXAMPLE

Full example of Discover Search

Learn how to integrate the Discover Search with MapKit and Search UI components in a sample app.

Getting Started with Category Search

GUIDE

Installation guide

Before utilizing any of Mapbox's Search products, there are some common installation steps that you need to follow. Refer to this guide, and then go ahead with the steps outlined below.

The Discover class serves as the primary access point for implementing text-based search functionality. To begin, you must first create an instance of this class. You can do this by using the following Swift code:


let discover = Discover(accessToken: mapboxAccessToken)

To create an instance of Discover.Query.Category, you can either choose one of the predefined constants or instantiate it with the canonical name of the Point of Interest (POI) category. Here's how you can do it:


let query = Discover.Query.Category.coffeeShopCafe


let query = Discover.Query.Category.canonicalName("charging_station")

To get the list of canonical names for supported categories, you can make a request to the following endpoint:


https://api.mapbox.com/search/searchbox/v1/list/category?access_token=<ACCESS_TOKEN>

To search for Points of Interest (POIs), the parameters of the function will differ based on the use case. Here's how you can implement it:

For the Search nearby use case, you will have to provide a geographic position represented by the CLLocationCoordinate2D type:


let userLocation: CLLocationCoordinate2D = retrieveUserLocation()
discover.search(for: query, proximity: userLocation) { result in ... }

For the Search in the area use case you will have to provide a region represented by BoundingBox instance:


let currentRegion: BoundingBox = currentBoundingBox
discover.search(for: query, in: currentRegion) { result in ... }

And for the Search along the route use case you will have to provide a route represented by a list of points:


let routeOptions: RouteOptions = .init(
    route: buildRoute(),
    time: calculateRouteTime()
)
discover.search(for: query, route: routeOptions) { result in ... }

After initiating a search request, you'll need to handle the response from the search() function. This function will either return an error or a list of results. Here's how you can process the response:


discover.search(for: query, route: routeOptions) { result in
    switch result {
    case .success(let results):
        self.processDiscoverResults(results)

    case .failure(let error):
        debugPrint(error)
    }
}