Search by Category
Category Search for Android gives you the tools you need to add POI (Points of Interest) search to your application. Whether your users need to search for cafes nearby, parking in another city, or Electric Vehicle (EV) charging stations along their route, this use case will help you to provide the functionality they need with a few lines of code.
Use cases
- Search nearby. This use case allows users to quickly search for POIs nearby a specified geographical point, such as the user’s location. For example, you can enable your users to discover cafes, shops, and parks within walking distance.
- Search in the area. This use case will help your users to discover POI in a selected area, such as the user's current map view. If your user is searching for hotels in Paris, for example, search in the area will enable them to discover hotels by navigating the map.
- Search along the route. This navigation use case enables users to search for POI, such as Electric Vehicle (EV) charging stations, while driving between two or more points.
We have a ready-made sample app that you can try in Android Studio with Category search (Discover class) and other scenarios. We encourage you to install and try it for yourself.
Learn how to integrate the Discover with Maps SDK and Search UI components in a sample app.
Integration
Discover class provides coroutine-based API. In the following integration steps, we assume that you are familiar with the Kotlin coroutines and your Android project has Kotlin-ktx dependencies added. See the Kotlin coroutines guide for more information.
Before using any of Mapbox's Search products, you need to do some common installation steps. Follow this guide to complete installation, then continue with the steps below.
- The main entrypoint class is called
Discover, you will need to instantiate this class first:
val discover = Discover.create(mapboxAccessToken)
- Create the
DiscoverQuery.Categoryinstance. You can pick one of the predefined constants or instantiate it with the textual POI's category canonical name.
val query = DiscoverQuery.Category.COFFEE_SHOP_CAFE
or
val query = DiscoverQuery.Category.create("charging_station")
Note that the list of valid canonical names is not final and might be changed while the API is in beta. The link to the list will be available soon.
- Search for the POIs. There's only one function called
search()which has method overloadings for different use cases. As was mentioned before, the Discover provides coroutine-based API, andsearch()is a suspend function which should be called only from a coroutine or another suspend function. In this short example we will assume that we call it from Activity'slifecycleScope:
lifecycleScope.launchWhenCreated {
val response = discover.search(query, ...)
}
The function parameters will vary depending on the use case.
- For the Search nearby use case you will have to provide geographic position represented by the
Pointclass:
val userLocation: Point = retrieveUserLocation()
val response = discover.search(query, userLocation)
- For the Search in the area use case you will have to provide a region represented by
BoundingBoxinstance:
val dcRegion = BoundingBox.fromPoints(
Point.fromLngLat(-77.04482563320445, 38.89626984069077),
Point.fromLngLat(-77.02584649998599, 38.907104458514695)
)
val response = discover.search(query, dcRegion)
- And for the Search along the route use case you will have to provide a route represented by a list of points:
val route: List<Point> = buildRoute()
val response = discover.search(query, route)
- Process the Discover response. The
search()function returns either error or value:
response.onValue { results: List<DiscoverResult> ->
showOnMap(results)
}.onError { e: Exception ->
showErrorMessage(e)
}
For more information, see the full API reference for the Discover for Android.
Search by Category Pricing
There is no separate charge if you choose to use Mapbox Search SDK for Android to access our APIs, you only pay by the Search API usage.
Usage of the Search by Category is measured in monthly API requests. Details about the number of API requests included in the free tier and the cost per request beyond what is included in the free tier are available on the pricing page.