Forward, reverse geocoding | Search SDK | Android Docs

Forward geocoding

Forward geocoding allows you to search for places by name.

Forward geocoding in the Search SDK consists of two steps: suggestions search and suggestions selection.

Suggestions search

When you provide a String query and set of options, SearchOptions, to SearchEngine.search(), it returns a list of suggestions List<SearchSuggestion> that contain information about an address or a place (including name, categories, description, and type).


val task = searchEngine.search(
    "Paris Eiffel Tower",
    SearchOptions(limit = 5),
    searchCallback
)

Resulting suggestions will be passed to the SearchSuggestionsCallback.onSuggestions() callback:


val searchCallback = object : SearchSuggestionsCallback {
    override fun onSuggestions(suggestions: List<SearchSuggestion>, responseInfo: ResponseInfo) {
        val suggestion = suggestions.firstOrNull()
    }

    override fun onError(e: Exception) {
    }
}

Additional information, like geographic coordinates of a place, is not available at this step. To get more information about a suggestion you need to make a suggestion selection.

Suggestion selection

To retrieve more information for a specific suggestion, use the SearchEngine.select() method:


val selectRequestTask = searchEngine.select(suggestion, selectCallback)

The result of the select operation will be passed to one of the SearchSelectionCallback callback functions:


val selectCallback = object : SearchSelectionCallback {
    override fun onResult(
        suggestion: SearchSuggestion,
        result: SearchResult,
        responseInfo: ResponseInfo
    ) {
    }

    override fun onSuggestions(suggestions: List<SearchSuggestion>, responseInfo: ResponseInfo) {
    }

    override fun onResults(
        suggestion: SearchSuggestion,
        results: List<SearchResult>,
        responseInfo: ResponseInfo
    ) {
    }

    override fun onError(e: Exception) {
    }
}

Depending on the type of suggestion, SearchSuggestion.type, different selection logic is applied:

Suggestion type	Result of select operation	Description
`SearchResultSuggestion`	`SearchResult`	Suggestion has a place or address associated with it. Search result contains information about geographic coordinates. Source of information: server Result of operation is passed to: `SearchSelectionCallback.onResult()`
`Category`	`List<SearchResult>`	Suggestion indicates that the SDK found a category name for category search. Selection of such suggestion results in a category search request with the result being list of POIs. Each search result contains information about geographic coordinates. Source of information: server Result of operation is passed to: `SearchSelectionCallback.onResults()`
`Brand`	`List<SearchResult>`	Suggestion indicates that the SDK found a brand name. Selection of such suggestion results in a search request with the result being list of POIs. Each search result contains information about geographic coordinates. Source of information: server Result of operation is passed to: `SearchSelectionCallback.onResults()`
`Query`	`List<SearchSuggestion>`	Suggestion indicates that a user has likely misspelled a query during the first step of forward geocoding. Selection of such suggestion results in the same search request from the first step with a changed query. The result of the operation is new list of suggestions. Source of information: server Result of operation is passed to: `SearchSelectionCallback.onSuggestions()`
`IndexableRecordItem`	`SearchResult`	Suggestion has a place or address associated with it. Search result contains information about geographic coordinates. Source of information: data provider (read more in the Data providers guide) Result of operation is passed to: `SearchSelectionCallback.onResult()`

If the passed suggestion is of the type SearchResultSuggestion or IndexableRecordItem, then you receive information about coordinates in the SearchSelectionCallback.onResult() method:


val selectCallback = object : SearchSelectionCallback {
    override fun onResult(
        suggestion: SearchSuggestion,
        result: SearchResult,
        responseInfo: ResponseInfo
    ) {
        val coordinates = result.coordinate
    }

    override fun onSuggestions(suggestions: List<SearchSuggestion>, responseInfo: ResponseInfo) {
    }

    override fun onResults(
        suggestion: SearchSuggestion,
        results: List<SearchResult>,
        responseInfo: ResponseInfo
    ) {
    }

    override fun onError(e: Exception) {
    }
}

Automatic history record creation

A successfully completed SearchEngine.select() method adds HistoryRecord, created from SearchResult, to HistoryDataProvider by default (read more about history data provider in the Data Providers guide).If you want to turn off the default functionality, specify extra parameter options: SelectOptions with the following options:

kotlinval options = SelectOptions(addResultToHistory = false)val selectRequestTask = searchEngine.select(suggestion, options, selectCallback)

Batch suggestions selection

You can also select multiple suggestions at once with the SearchEngine.select() method. The only requirements are:

All suggestions must originate from the same search request
All suggestions should be allowed for batch selection

Invoke SearchSuggestion.isBatchResolveSupported to check if a suggestion can be used for batch selection.


val batchSuggestions = suggestions.filter { it.isBatchResolveSupported }
val selectRequestTask = searchEngine.select(batchSuggestions, multipleSelectCallback)

Provided results will be passed to the SearchMultipleSelectionCallback.onResult() callback.


val multipleSelectCallback = object : SearchMultipleSelectionCallback {
    override fun onResult(
        suggestions: List<SearchSuggestion>,
        results: List<SearchResult>,
        responseInfo: ResponseInfo
    ) {
    }

    override fun onError(e: Exception) {
    }
}

EXAMPLE

Batch search

Forward geocoding with batch selection allows you to get several search results using fewer requests.

Reverse geocoding

When you provide a Point location and set of options, ReverseGeoOptions, to ReverseGeocodingSearchEngine, it returns a list of places, addresses, and POIs List<SearchResult>.


val task = searchEngine.search(
    ReverseGeoOptions(
        center = Point.fromLngLat(2.294434, 48.858349)
    ),
    reverseSearchCallback
)

Resulting suggestions will be passed to the SearchCallback.onResults() callback:


val reverseSearchCallback = object : SearchCallback {
    override fun onResults(results: List<SearchResult>, responseInfo: ResponseInfo) {
    }

    override fun onError(e: Exception) {
    }
}

EXAMPLE

Reverse geocoding

Reverse geocoding allows you to enter a geographic coordinate and receive the name of one or more places that exist at that location.

Category search

When you provide a String query and set of options, CategorySearchOptions, to CategorySearchEngine, it returns a list of POIs List<SearchResult>. You can find a list of common category names in the Mapbox Geocoding API documentation.


val task = searchEngine.search(
    "cafe",
    CategorySearchOptions(limit = 1),
    categorySearchCallback
)

Resulting suggestions will be passed to the SearchCallback.onResults() callback:


val categorySearchCallback = object : SearchCallback {
    override fun onResults(results: List<SearchResult>, responseInfo: ResponseInfo) {
    }

    override fun onError(e: Exception) {
    }
}