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

# Building highlights

The Mapbox Navigation SDK provides logic to highlight a particular building footprint or extrude a footprint as a 3D building shape. You can use this functionality to enhance the navigation experience for your users by visually highlighting your user's stop or final destination. For example, a package delivery driver might want to see the exact building that's associated with a delivery address.

## Use the default building UI component

The buildings UI component consists of two main classes:

-   The [`MapboxBuildingsApi`](https://docs.mapbox.com/android/navigation/v2/api/2.22.2/libnavui-maps/com.mapbox.navigation.ui.maps.building.api/-mapbox-buildings-api/) has methods for retrieving the building you'd like to highlight in the form of a `QueriedFeature`.
    
-   The [`MapboxBuildingView`](https://docs.mapbox.com/android/navigation/v2/api/2.22.2/libnavui-maps/com.mapbox.navigation.ui.maps.building.view/-mapbox-building-view/) handles consuming the data produced by the `MapboxBuildingsApi` and rendering the results on the map.
    
    ![](https://docs.mapbox.com/android/ja/assets/ideal-img/navigation-overview-building-highlight.2a6ea2d.480.png)
    

### Point types

It's important to understand the difference between `location` point and `routable` point to make use of the buildings API:

-   **`location` point:** A point where the actual building is.
-   **`routable` point:** A point on a road snapped from the address.

### Create an instance of `MapboxBuildingsApi`

Instantiate `MapboxBuildingsApi` in your `Activity` or `Fragment`.

```kotlin
private val buildingsApi: MapboxBuildingsApi by lazy {
  MapboxBuildingsApi(mapboxMap)
}
```

Then you can get the building you'd like to highlight. `MapboxBuildingsApi` exposes three different methods that returns you one or more building(s):

-   **`queryBuildingToHighlight`:** This API takes `Point` as an argument and returns a list of building(s) as `QueriedFeature`. If the point passed is not a location point, the list returned will be empty.
-   **`queryBuildingOnWaypoint`:** This API takes [`RouteProgress`](https://docs.mapbox.com/android/navigation/v2/api/2.22.2/libnavigation-base/com.mapbox.navigation.base.trip.model/-route-progress/) as an argument and returns a list of building(s) as `QueriedFeature`. If `RouteProgress` doesn't contain a location point, the list returned will be empty.
-   **`queryBuildingOnFinalDestination`:** This API takes [`RouteProgress`](https://docs.mapbox.com/android/navigation/v2/api/2.22.2/libnavigation-base/com.mapbox.navigation.base.trip.model/-route-progress/) as an argument and returns a list of building(s) as `QueriedFeature`. If `RouteProgress` doesn't contain a location point, the list returned will be empty.

### Use location point in route request

When requesting a single- or multi-stop route, the simplest way is to invoke [`requestRoute`](https://docs.mapbox.com/android/ja/navigation/v2/guides/turn-by-turn-navigation/route-generation/#request-a-route) with [your already-instantiated `MapboxNavigation` object](https://docs.mapbox.com/android/ja/navigation/v2/guides/get-started/initialization/#create-the-mapboxnavigation-object). But, if you want to highlight buildings, you should use `RouteOptions#waypointTargetsList`.

In the snippet below, `coordinatesList` holds a list of three `routable` points that the Navigation SDK uses to navigate to your destination, and the `waypointTargetsList` holds a list of three `location` points that the SDK uses to return a list of buildings in the form of `QueriedFeature`.

```kotlin
val routeOptions = RouteOptions.builder()
  .applyDefaultNavigationOptions()
  .applyLanguageAndVoiceUnitOptions(this)
  .coordinatesList(
    listOf(
      Point.fromLngLat(-122.4192, 37.7627), // origin
      Point.fromLngLat(-122.4182, 37.7651), // waypoint destination
      Point.fromLngLat(-122.4145, 37.7653)  // final destination
    )
  )
  .waypointTargetsList(
    listOf(
      Point.fromLngLat(-122.4192, 37.7627), // origin
      Point.fromLngLat(-122.4183, 37.7653), // waypoint destination
      Point.fromLngLat(-122.4146, 37.7655)  // final destination
    )
  )
  .build()
```

> **Note: Highlight buildings without waypointTargetsList**
> 
> It is possible to highlight buildings without using `waypointTargetsList`, but you must use `location` points instead of `routable` points in `coordinateList`. If you use `routable` points, the SDK will query the snapped location on the road and will not return any building(s).

### Query buildings on arrival

Now that you have passed in location points and have your instance of `MapboxBuildingsApi` ready, you can use one or more of the query-related methods to query buildings.

To use building highlighting to visually emphasize the location of stops along a route or a final destination, you'll need to know when the user has arrived at a waypoint or destination. You can listen for arrival events using [`ArrivalObserver`](https://docs.mapbox.com/android/navigation/v2/api/2.22.2/libnavigation-core/com.mapbox.navigation.core.arrival/-arrival-observer/). Read more about how `ArrivalObserver` works in the [Arrival detection](https://docs.mapbox.com/android/ja/navigation/v2/guides/ui-components/arrival-detection/) guide.

To query the building upon reaching a waypoint, use `ArrivalObserver`'s `onWaypointArrival` and `MapboxBuildingsApi`'s `queryBuildingOnWaypoint`.

```kotlin
val arrivalObserver = object : ArrivalObserver() {
  override fun onWaypointArrival(routeProgress: RouteProgress) {
    buildingsApi.queryBuildingOnWaypoint(routeProgress, callback)
  }
}
```

To query the building upon reaching the final destination, add `onFinalDestinationArrival` to `ArrivalObserver` and then use `MapboxBuildingsApi`'s `queryBuildingOnFinalDestination`.

```kotlin
override fun onFinalDestinationArrival(routeProgress: RouteProgress) {
  buildingsApi.queryBuildingOnFinalDestination(routeProgress, callback)
}
```

The `callback` for both query methods can either be [`BuildingError`](https://docs.mapbox.com/android/navigation/v2/api/2.22.2/libnavui-maps/com.mapbox.navigation.ui.maps.building.model/-building-error/) containing an error message or [`BuildingValue`](https://docs.mapbox.com/android/navigation/v2/api/2.22.2/libnavui-maps/com.mapbox.navigation.ui.maps.building.model/-building-value/) containing a list of buildings in the form of `QueriedFeature`.

```kotlin
private val callback =
  MapboxNavigationConsumer<Expected<BuildingError, BuildingValue>> { expected ->
    expected.fold(
      {
        // handle errors        
      },
      { value ->
        // highlight the building using `MapboxBuildingView`
      }
    )
  }
```

Don't forget to cancel any potential in-flight `MapboxBuildingsApi` requests in `onStop` or `onDestroy`:

```kotlin
override fun onDestroy() {
  super.onDestroy()
  buildingsApi.cancel()
}
```

### Highlight buildings

Now that you have queried your buildings, you can highlight them by creating an instance of `MapboxBuildingView`.

```kotlin
private val buildingView = MapboxBuildingView()
```

Inside the callback you have defined above get the map style and highlight buildings.

```kotlin
{ value ->
  mapboxMap.getStyle { style ->
    buildingView.highlightBuilding(style, value.buildings)
  }  
}
```

After you have reached the waypoint and highlighted the building, you can clear the building highlight before starting the next leg.

```kotlin
override fun onNextRouteLegStart(routeLegProgress: RouteLegProgress) {
  mapboxMap.getStyle { style ->
    buildingView.removeBuildingHighlight(style)
  }
}
```