Search by Text
The Place Autocomplete returns place suggestions in response to user search queries, such as addresses, businesses and POIs. The Place Autocomplete will help you to implement such functionality in a few lines of code.
User experience
This use case allows users quickly search for a place by its name, results can be limited to a region and sorted by proximity.
We have a ready-made sample app that you can try in Android Studio with Place Autocomplete and other scenarios. We encourage you to install and try it for yourself.
Learn how to integrate the Place Autocomplete with Maps SDK and Search UI components in a sample app.
Integration
Place Autocomplete 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
PlaceAutocomplete, you will need to instantiate this class first:
val placeAutocomplete = PlaceAutocomplete.create(mapboxAccessToken)
- Retrieve autocomplete suggestions. There's only one function called
suggestions()which has method overloadings for different use cases. As was mentioned before, the Place Autocomplete provides coroutine-based API, andsuggestions()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 = placeAutocomplete.suggestions(query)
}
- For the Search by name use case you will have to provide a String query:
val response = placeAutocomplete.suggestions("Washington DC")
- Process the Place Autocomplete response. The suggestions() function returns either error or suggestions list:
response.onValue { suggestions: List<PlaceAutocompleteSuggestion> ->
processSuggestions(suggestions)
}.onError { e ->
// process error
}
- When a user has selected a suggestion, call
select()function. This function returnsPlaceAutocompleteResultobject that provides detailed information about the place. Also,select()function ends billing session, so it's obligatory to call it every time your users select suggestions.
val selectedSuggestion = pickSuggestion(suggestions)
val selectionResponse = placeAutocomplete.select(selectedSuggestion)
selectionResponse.onValue { result ->
// process result
}.onError { e ->
// process error
}
For more information, see the full API reference for the Place Autocomplete for Android.
Search by Text 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 Text is measured in monthly API sessions. 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.