Discover

The Discover SDK 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, the Discover SDK will help you to provide this functionality (and more) with just a few lines of code.

We have a ready-made sample app that you can try in Android Studio with Discover SDK and other scenarios. We encourage you to install and try it for yourself.

Integration

Discover SDK 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.

1. The main entrypoint class is called Discover, you will need to instantiate this class first:

val discover = Discover.create(mapboxAccessToken)

2. Create the DiscoverQuery.Category instance. 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.

3. Search for the POIs. There's only one function called search() which has overloadings for different use cases. As was mentioned before, the Discover SDK provides coroutine-based API, and search() 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's lifecycleScope:

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 Point class:

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 BoundingBox instance:

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)

4. Process the Discover SDK response. The search() function returns either error or value:

response.onValue { results: List<DiscoverResult> ->
    showOnMap(results)
}.onError { e: Exception ->
    showErrorMessage(e)
}