> For the complete documentation index, see [llms.txt](https://docs.mapbox.com/android/ja/search/llms.txt)

# Forward, reverse geocoding

## Forward geocoding

> **Related content (example): [Forward geocoding](https://docs.mapbox.com/android/ja/search/examples/search/)**
> 
> 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`](https://docs.mapbox.com/android/search/api/core/2.28.2/sdk/com.mapbox.search/-search-options/), to [`SearchEngine.search()`](https://docs.mapbox.com/android/search/api/core/2.28.2/sdk/com.mapbox.search/-search-engine/#%5Bcom.mapbox.search%2FSearchEngine%2Fsearch%2F%23kotlin.String%23com.mapbox.search.SearchOptions%23com.mapbox.search.SearchSuggestionsCallback%2FPointingToDeclaration%2F%2C+com.mapbox.search%2FSearchEngine%2Fsearch%2F%23kotlin.String%23com.mapbox.search.SearchOptions%23java.util.concurrent.Executor%23com.mapbox.search.SearchSuggestionsCallback%2FPointingToDeclaration%2F%5D%2FFunctions%2F477219679), it returns a list of suggestions [`List<SearchSuggestion>`](https://docs.mapbox.com/android/search/api/core/2.28.2/sdk/com.mapbox.search.result/-search-suggestion/) that contain information about an address or a place (including name, categories, description, and type).

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

Resulting suggestions will be passed to the [`SearchSuggestionsCallback.onSuggestions()`](https://docs.mapbox.com/android/search/api/core/2.28.2/sdk/com.mapbox.search/-search-suggestions-callback/#%5Bcom.mapbox.search%2FSearchSuggestionsCallback%2FonSuggestions%2F%23kotlin.collections.List%5Bcom.mapbox.search.result.SearchSuggestion%5D%23com.mapbox.search.ResponseInfo%2FPointingToDeclaration%2F%5D%2FFunctions%2F477219679) callback:

```kotlin
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).

### Suggestion selection

To retrieve more information for a specific suggestion, use the [`SearchEngine.select()`](https://docs.mapbox.com/android/search/api/core/2.28.2/sdk/com.mapbox.search/-search-engine/#%5Bcom.mapbox.search%2FSearchEngine%2Fselect%2F%23com.mapbox.search.result.SearchSuggestion%23com.mapbox.search.SearchSelectionCallback%2FPointingToDeclaration%2F%2C+com.mapbox.search%2FSearchEngine%2Fselect%2F%23kotlin.collections.List%5Bcom.mapbox.search.result.SearchSuggestion%5D%23com.mapbox.search.SearchMultipleSelectionCallback%2FPointingToDeclaration%2F%2C+com.mapbox.search%2FSearchEngine%2Fselect%2F%23com.mapbox.search.result.SearchSuggestion%23com.mapbox.search.SelectOptions%23com.mapbox.search.SearchSelectionCallback%2FPointingToDeclaration%2F%2C+com.mapbox.search%2FSearchEngine%2Fselect%2F%23kotlin.collections.List%5Bcom.mapbox.search.result.SearchSuggestion%5D%23java.util.concurrent.Executor%23com.mapbox.search.SearchMultipleSelectionCallback%2FPointingToDeclaration%2F%2C+com.mapbox.search%2FSearchEngine%2Fselect%2F%23com.mapbox.search.result.SearchSuggestion%23com.mapbox.search.SelectOptions%23java.util.concurrent.Executor%23com.mapbox.search.SearchSelectionCallback%2FPointingToDeclaration%2F%5D%2FFunctions%2F477219679) method:

```kotlin
val selectRequestTask = searchEngine.select(suggestion, selectCallback)
```

The result of the select operation will be passed to one of the [`SearchSelectionCallback`](https://docs.mapbox.com/android/search/api/core/2.28.2/sdk/com.mapbox.search/-search-selection-callback/) callback functions:

```kotlin
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`](https://docs.mapbox.com/android/search/api/core/2.28.2/sdk/com.mapbox.search.result/-search-suggestion/#%5Bcom.mapbox.search.result%2FSearchSuggestion%2Ftype%2F%23%2FPointingToDeclaration%2F%5D%2FProperties%2F477219679), different selection logic is applied:

<table><thead><tr><th>Suggestion type</th><th>Result of select operation</th><th>Description</th></tr></thead><tbody><tr><td><a href="https://docs.mapbox.com/android/search/api/core/2.28.2/sdk/com.mapbox.search.result/-search-suggestion-type/-search-result-suggestion/"><code>SearchResultSuggestion</code></a></td><td><code>SearchResult</code></td><td>Suggestion has a place or address associated with it. Search result contains information about geographic coordinates.<br><br><em>Source of information</em>: server<br><em>Result of operation is passed to</em>: <a href="https://docs.mapbox.com/android/search/api/core/2.28.2/sdk/com.mapbox.search/-search-selection-callback/#%5Bcom.mapbox.search%2FSearchSelectionCallback%2FonResult%2F%23com.mapbox.search.result.SearchSuggestion%23com.mapbox.search.result.SearchResult%23com.mapbox.search.ResponseInfo%2FPointingToDeclaration%2F%5D%2FFunctions%2F477219679"><code>SearchSelectionCallback.onResult()</code></a></td></tr><tr><td><a href="https://docs.mapbox.com/android/search/api/core/2.28.2/sdk/com.mapbox.search.result/-search-suggestion-type/-category/"><code>Category</code></a></td><td><code>List&lt;SearchResult&gt;</code></td><td>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.<br><br><em>Source of information</em>: server<br><em>Result of operation is passed to</em>: <a href="https://docs.mapbox.com/android/search/api/core/2.28.2/sdk/com.mapbox.search/-search-selection-callback/on-results.html"><code>SearchSelectionCallback.onResults()</code></a></td></tr><tr><td><a href="https://docs.mapbox.com/android/search/api/core/2.28.2/sdk/com.mapbox.search.result/-search-suggestion-type/-brand/"><code>Brand</code></a></td><td><code>List&lt;SearchResult&gt;</code></td><td>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.<br><br><em>Source of information</em>: server<br><em>Result of operation is passed to</em>: <a href="https://docs.mapbox.com/android/search/api/core/2.28.2/sdk/com.mapbox.search/-search-selection-callback/on-results.html"><code>SearchSelectionCallback.onResults()</code></a></td></tr><tr><td><a href="https://docs.mapbox.com/android/search/api/core/2.28.2/sdk/com.mapbox.search.result/-search-suggestion-type/-query/"><code>Query</code></a></td><td><code>List&lt;SearchSuggestion&gt;</code></td><td>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.<br><br><em>Source of information</em>: server<br><em>Result of operation is passed to</em>: <a href="https://docs.mapbox.com/android/search/api/core/2.28.2/sdk/com.mapbox.search/-search-selection-callback/#%5Bcom.mapbox.search%2FSearchSuggestionsCallback%2FonSuggestions%2F%23kotlin.collections.List%5Bcom.mapbox.search.result.SearchSuggestion%5D%23com.mapbox.search.ResponseInfo%2FPointingToDeclaration%2F%5D%2FFunctions%2F477219679"><code>SearchSelectionCallback.onSuggestions()</code></a></td></tr><tr><td><a href="https://docs.mapbox.com/android/search/api/core/2.28.2/sdk/com.mapbox.search.result/-search-suggestion-type/-indexable-record-item/"><code>IndexableRecordItem</code></a></td><td><code>SearchResult</code></td><td>Suggestion has a place or address associated with it. Search result contains information about geographic coordinates.<br><br><em>Source of information</em>: data provider (read more in the <a href="/search/guides/search-engine/data-providers/">Data providers guide</a>)<br><em>Result of operation is passed to</em>: <a href="https://docs.mapbox.com/android/search/api/core/2.28.2/sdk/com.mapbox.search/-search-selection-callback/#%5Bcom.mapbox.search%2FSearchSelectionCallback%2FonResult%2F%23com.mapbox.search.result.SearchSuggestion%23com.mapbox.search.result.SearchResult%23com.mapbox.search.ResponseInfo%2FPointingToDeclaration%2F%5D%2FFunctions%2F477219679"><code>SearchSelectionCallback.onResult()</code></a></td></tr></tbody></table>

If the passed suggestion is of the type `SearchResultSuggestion` or `IndexableRecordItem`, then you receive information about coordinates in the [`SearchSelectionCallback.onResult()`](https://docs.mapbox.com/android/search/api/core/2.28.2/sdk/com.mapbox.search/-search-selection-callback/#%5Bcom.mapbox.search%2FSearchSelectionCallback%2FonResult%2F%23com.mapbox.search.result.SearchSuggestion%23com.mapbox.search.result.SearchResult%23com.mapbox.search.ResponseInfo%2FPointingToDeclaration%2F%5D%2FFunctions%2F477219679) method:

```kotlin
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) {
    }
}
```

> **Note: 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](https://docs.mapbox.com/android/ja/search/guides/search-engine/data-providers/)).If you want to turn off the default functionality, specify extra parameter [`options: SelectOptions`](https://docs.mapbox.com/android/search/api/core/2.28.2/sdk/com.mapbox.search/-select-options/) with the following options:`kotlinval options = SelectOptions(addResultToHistory = false)val selectRequestTask = searchEngine.select(suggestion, options, selectCallback)`

## Reverse geocoding

When you provide a [`Point`](https://docs.mapbox.com/android/java/api/libjava-geojson/5.8.0/) location and set of options, [`ReverseGeoOptions`](https://docs.mapbox.com/android/search/api/core/2.28.2/sdk/com.mapbox.search/-reverse-geo-options/), to `ReverseGeocodingSearchEngine`, it returns a list of places, addresses, and POIs [`List<SearchResult>`](https://docs.mapbox.com/android/search/api/core/2.28.2/sdk/com.mapbox.search.result/-search-result/).

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

Resulting suggestions will be passed to the [`SearchCallback.onResults()`](https://docs.mapbox.com/android/search/api/core/2.28.2/sdk/com.mapbox.search/-search-callback/#%5Bcom.mapbox.search%2FSearchCallback%2FonResults%2F%23kotlin.collections.List%5Bcom.mapbox.search.result.SearchResult%5D%23com.mapbox.search.ResponseInfo%2FPointingToDeclaration%2F%5D%2FFunctions%2F477219679) callback:

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

    override fun onError(e: Exception) {
    }
}
```

> **Related content (example): [Reverse geocoding](https://docs.mapbox.com/android/ja/search/examples/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`](https://docs.mapbox.com/android/search/api/core/2.28.2/sdk/com.mapbox.search/-category-search-options/), to `CategorySearchEngine`, it returns a list of POIs [`List<SearchResult>`](https://docs.mapbox.com/android/search/api/core/2.28.2/sdk/com.mapbox.search.result/-search-result/). You can find a list of common category names in the [Mapbox Geocoding API documentation](https://docs.mapbox.com/api/search/geocoding/#example-request-poi-category-search).

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

Resulting suggestions will be passed to the [`SearchCallback.onResults()`](https://docs.mapbox.com/android/search/api/core/2.28.2/sdk/com.mapbox.search/-search-callback/#%5Bcom.mapbox.search%2FSearchCallback%2FonResults%2F%23kotlin.collections.List%5Bcom.mapbox.search.result.SearchResult%5D%23com.mapbox.search.ResponseInfo%2FPointingToDeclaration%2F%5D%2FFunctions%2F477219679) callback:

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

    override fun onError(e: Exception) {
    }
}
```

> **Related content (example): [Category search](https://docs.mapbox.com/android/ja/search/examples/category-search/)**
> 
> Category search allows you to look for places that belong to a specified category.