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

# Offline Search

> **Note (beta): Enable offline search**
> 
> The Mapbox Offline Search for Android is a premium feature. [Contact our sales team](https://www.mapbox.com/contact/sales/) to enable your Mapbox account for Offline Search.

The **Mapbox Offline Search for Android** gives you the tools you need to add an offline search experience to your application. It takes only a few steps to make your application work offline.

These are a few key terms and concepts you may need to reference when working with the Offline Search:

-   **Offline Search Engine**: The Offline Search Engine API provides an entrypoint for offline search functionality. It is used to make search requests in offline and to produce tileset descriptors that can be used with a tile store.
-   **Tileset descriptor**: A tileset descriptor contains metadata about the tilesets that cached tile packs should include. You can create tileset descriptors with the Offline Search Engine.
-   **Tile Region**: A tile region is a geographic area for which offline data is needed. Tile regions are used by tile stores to fetch and manage tile packs necessary to provide offline support in that area. To create a tile region, a developer must specify a geometry describing each region's boundaries, and source tileset(s).
-   **Tile Store**: The tile store manages retrieving and organizing tile regions. The Offline Search only uses the tile store for tile regions. Although the Offline Search handles creating tileset descriptors, it is the job of the tile store to manage tile regions. You should keep the TileStore instance by keeping a reference to it while using the SDK to avoid unnecessary re-initialization and possible loss of options you provided earlier.

## Integration guide

Using Offline Search requires three steps:

1.  SDK installation
2.  Downloading the offline tiles
3.  Searching with the downloaded data

### Installation

> **Related content (guide): [Installation guide](https://docs.mapbox.com/android/ja/search/guides/install/)**
> 
> Before you are able to use any of the Search products you need to do common installation steps. Follow this guide to install, then continue with the steps below.

### Tile regions downloading

#### Initialize `OfflineSearchEngine` and `TileStore` instances

`OfflineSearchEngine` and `TileStore` are two main components required for the offline search functionality.

`TileStore` allows users to create and download offline regions ahead of time, enabling offline search functionality.

> **Note: TileStore with the Navigation and Maps SDKs**
> 
> `TileStore` handles offline regions data for the Search SDK, the Navigation SDK, and the Maps SDK. Find more details on how to use `TileStore` for map data in the [Maps SDK documentation](https://docs.mapbox.com/android/ja/maps/guides/offline/), and for navigation data in the [Navigation SDK documentation](https://docs.mapbox.com/android/ja/navigation/guides/advanced/offline/).

Once `TileStore` instance is initialized, you can create `OfflineSearchEngine`:

```kotlin
val searchEngine = OfflineSearchEngine.create(
    OfflineSearchEngineSettings(tileStore)
)
```

#### Define a tileset descriptors and load tile regions

Use the tileset descriptor to define the tilesets that will be available for the offline search. The Offline Search supports the following data types:

-   **Address**: Individual residential or business addresses.
-   **POI (Point of Interest)**: Locations such as cafes, charging stations, etc.
-   **Place**: Typically these are cities, villages, municipalities, etc.

Use [`OfflineSearchEngine.createTilesetDescriptor()`](https://docs.mapbox.com/android/search/api/offline/2.28.2/offline/com.mapbox.search.offline/-offline-search-engine/-companion/create-tileset-descriptor.html) to create descriptors for addresses, places, POIs, and [`OfflineSearchEngine.createPlacesTilesetDescriptor()`](https://docs.mapbox.com/android/search/api/offline/2.28.2/offline/com.mapbox.search.offline/-offline-search-engine/-companion/create-places-tileset-descriptor.html) for places only:

```kotlin
val descriptors = listOf(
    OfflineSearchEngine.createTilesetDescriptor(),
    OfflineSearchEngine.createPlacesTilesetDescriptor(),
)
```

> **Note (beta): Unstable dataset version names in beta**
> 
> Dataset and version names required for tileset descriptor creation are unstable. It's recommended to use `createTilesetDescriptor()`, and `createPlacesTilesetDescriptor()` functions with default parameters while the Offline Search is in beta.

To start a tiles loading operation, provide descriptors and geometry defining a set of tiles to be loaded to the `TileRegionLoadOptions`:

```kotlin
val tileRegionId = "Washington DC"
val dcLocation = Point.fromLngLat(-77.0339911055176, 38.899920004207516)

val tileRegionLoadOptions = TileRegionLoadOptions.Builder()
    .descriptors(descriptors)
    .geometry(dcLocation)
    .build()
```

And then start tiles loading operation:

```kotlin
val tilesLoadingTask = tileStore.loadTileRegion(tileRegionId, tileRegionLoadOptions, onProgressCallback, onFinishedCallback)
```

#### Observe tile regions state

When tile regions downloading successfully finished, `OfflineSearchEngine` needs some time to index data, usually this takes less than a second, depending on downloaded data size. To observe tile regions state and data availability for the `OfflineSearchEngine`, add `OnIndexChangeListener`:

```kotlin
searchEngine.addOnIndexChangeListener(object : OfflineSearchEngine.OnIndexChangeListener {
    override fun onIndexChange(event: OfflineIndexChangeEvent) {
        if (event.regionId == tileRegionId && (event.type == EventType.ADD || event.type == EventType.UPDATE)) {
            // Regions with id `tileRegionId` is ready and available for search
        }
    }

    override fun onError(event: OfflineIndexErrorEvent) {
        // Process error
    }
})
```

Note that `OnIndexChangeListener` will not be called if it's added after tile region data is processed, so `OnIndexChangeListener` should be added before `TileStore.loadTileRegion()` call if you need to check whether tile region is available for the search.

## Search in offline

Once the above steps are complete, you can start making search requests in offline mode. `OfflineSearchEngine` provides functionality for:

### Forward geocoding

**Forward geocoding** is likely what comes to mind when you think about a typical search experience: for the given `String` query a user gets geographic coordinates of an address or place.

You can search for addresses, POIs, or places offline using the [`OfflineSearchEngine.search()`](https://docs.mapbox.com/android/search/api/offline/2.28.2/offline/com.mapbox.search.offline/-offline-search-engine/search.html) function. Provide the feature you're looking for (e.g., POI name, address, city name) as a query parameter, along with [`OfflineSearchOptions`](https://docs.mapbox.com/android/search/api/offline/2.28.2/offline/com.mapbox.search.offline/-offline-search-options/), to start the search.

```kotlin
searchEngine.search(
    "1133 15th St NW, Washington, DC 20005, United States",
    OfflineSearchOptions(),
    searchCallback
)
```

By default, if location services are available, the `OfflineSearchEngine` uses the device's geolocation to bias the response, favoring results that are closer to the current location. You can also provide a custom proximity point to rank results closer to a specific location.

```kotlin
searchEngine.search(
    "cafe",
    OfflineSearchOptions(proximity = Point.fromLngLat(-77.03400094304453, 38.90484584480497)),
    searchCallback
)
```

**Search along a street** is a special case of forward geocoding. It allows you to find addresses near a specified street by using [`searchAddressesNearby`](https://docs.mapbox.com/android/search/api/offline/2.28.2/offline/com.mapbox.search.offline/-offline-search-engine/search-addresses-nearby.html).

```kotlin
searchEngine.searchAddressesNearby(
    street = "15th St",
    proximity = Point.fromLngLat(-77.03400094304453, 38.90484584480497),
    radiusMeters = 50.0,
    callback = searchCallback
)
```

> **Related content (example): [Forward geocoding](https://docs.mapbox.com/android/ja/search/examples/offline-search/)**
> 
> Forward geocoding allows you to search for places by name.

### Reverse geocoding

**Reverse geocoding** is an opposite operation of forward geocoding: for the given geographic coordinates a user gets place names or addresses.

```kotlin
searchEngine.reverseGeocoding(
    OfflineReverseGeoOptions(Point.fromLngLat(-77.03400094304453, 38.90484584480497)),
    searchCallback
)
```

> **Related content (example): [Reverse geocoding](https://docs.mapbox.com/android/ja/search/examples/offline-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.

## Search for EV Charging Stations

> **Note: Experimental API**
> 
> Search for EV Charging Stations is in a preview state and has a high chance of being changed in the future.

> **Note (beta): Limited support**
> 
> Only specific [datasets](#define-a-tileset-descriptors-and-load-tile-regions) support the search for EV charging stations. [Contact our sales team](https://www.mapbox.com/contact/sales/) to access datasets that include EV charging station data.

Search for EV Charging Stations supports additional parameters and can provide extended metadata. For instance, you can filter charging stations by specific operators, connector types, and charging power. Call [`OfflineSearchEngine.search()`](https://docs.mapbox.com/android/search/api/offline/2.28.2/offline/com.mapbox.search.offline/-offline-search-engine/search.html) and pass [`OfflineEvSearchOptions`](https://docs.mapbox.com/android/search/api/offline/2.28.2/offline/com.mapbox.search.offline/-offline-ev-search-options/) as the [`OfflineSearchOptions.evSearchOptions`](https://docs.mapbox.com/android/search/api/offline/2.28.2/offline/com.mapbox.search.offline/-offline-search-options/ev-search-options.html) parameter:

```kotlin
val evSearchOptions = OfflineEvSearchOptions(
    connectorTypes = listOf(
        EvConnectorType.CHADEMO,
        EvConnectorType.IEC_62196_T2_COMBO,
        EvConnectorType.IEC_62196_T2,
    ),
    operators = getOperatorsList(),
    minChargingPower = 10000f, // Minimum power of 10 kW
    maxChargingPower = 50000f, // Maximum power of 50 kW
)

val options = OfflineSearchOptions.Builder()
    .evSearchOptions(evSearchOptions)
    .proximity(location)
    .build()

searchRequestTask = searchEngine.search(
    "charging station",
    options,
    searchCallback
)
```

The search response may include additional metadata, such as the charging station's operating hours, nearby facilities, detailed information about the station, and more.

```kotlin
fun processSearchResult(searchResult: OfflineSearchResult) {
    searchResult.metadata?.let { metadata ->
        val website = metadata.website
        val openHours = metadata.openHours
        val operatorName = metadata.evMetadata?.evLocation?.operatorDetails?.name
        // ...
    }
}
```

Refer to the documentation for the [`OfflineSearchResultMetadata`](https://docs.mapbox.com/android/search/api/offline/2.28.2/offline/com.mapbox.search.offline/-offline-search-result-metadata/) and [`EvMetadata`](https://docs.mapbox.com/android/search/api/sdk-common/2.28.2/sdk-common/com.mapbox.search.common.ev/-ev-metadata/) types for more details on the data they provide.