Skip to main content

User's location on the map

Additional Developer Resources

The Mapbox Maps SDK for Android's location component enables your application to observe, respond and display the user's location.

Before you can show the user's location on the map, users must grant your application permission to access their location. See previous section Permission handling for more details.

Location component​

To visualize the user's location on the map you should enable the location component. There are different ways to enable location:

  • Directly in your MapView XML component using the attribute mapbox_locationComponentEnabled:

<com.mapbox.maps.MapView
  android:id="@+id/mapView"
  android:layout_width="match_parent"
  android:layout_height="match_parent"
  app:mapbox_locationComponentEnabled="true"
  app:mapbox_locationComponentPuckBearing="heading" />
 
    setContentView(mapView)
 
    with(mapView) {
 
      location.locationPuck = createDefault2DPuck(withBearing = true)
 
      location.enabled = true
 
      location.puckBearing = PuckBearing.COURSE
 
      location.puckBearingEnabled = true
 
      viewport.transitionTo(
 
        targetState = viewport.makeFollowPuckViewportState(),
 
        transition = viewport.makeImmediateViewportTransition()
 
      )
 
    }

The location component makes use of two dedicated layers in the Maps SDK to display either a 2D device location icon (using layer ID LOCATION_INDICATOR_LAYER) or a 3D model (using layer ID MODEL_LAYER). These layers are displayed within the map rather than on top of the map as an Android view. Layers in Mapbox map styles give you precise control over how you show a device's location on the map.

By default, the Maps SDK for Android provides a two dimensional location puck with a blue dot and white circle.

EXAMPLE
Show the user's location on the map

Show the user's location on a map using the default location puck.

Puck style options​

There are several options to customize the appearance of the location puck. You can see the full list at LocationComponentSettings.

You can directly use the LocationComponentPlugin to change the settings. For example, the pulsing effect is disabled by default, but you can enable this effect by passing true to the pulsingEnabled property.

 
      location.pulsingEnabled = true

Use a custom image​

You can further customize the puck by using custom image drawables to display the user's location on a map. Set custom location puck styles in one of two ways: using XML attributes or programmatically using the LocationPuck class.

Here's an example using style XML attributes to customize the appearance of the location icon:


<com.mapbox.maps.MapView
    android:id="@+id/mapView"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    app:mapbox_locationComponentEnabled = "true"
    app:mapbox_locationComponentLocationPuck= "location_puck_2_d"
    app:mapbox_locationComponentLocationPuckLocationPuck2DTopImage= "@drawable/custom_user_icon"
    app:mapbox_locationComponentLocationPuckLocationPuck2DBearingImage= "@drawable/custom_user_arrow"
    app:mapbox_locationComponentLocationPuckLocationPuck2DShadowImage= "@drawable/custom_user_puck_icon"
    tools:context=".examples.LocationComponentActivity" />

Here's an example using the LocationPuck class to programmatically customize the appearance of the location icon. Create a LocationPuck2D or LocationPuck3D object and set it through LocationComponentPlugin#locationPuck method. The following example also specifies the size of the icon based on the map's zoom level using scaleExpression.

 
    mapView.location.locationPuck = LocationPuck2D(
 
      topImage = ImageHolder.from(R.drawable.mapbox_user_icon), // ImageHolder also accepts Bitmap
 
      bearingImage = ImageHolder.from(R.drawable.mapbox_user_bearing_icon),
 
      shadowImage = ImageHolder.from(R.drawable.mapbox_user_stroke_icon),
 
      scaleExpression = interpolate {
 
        linear()
 
        zoom()
 
        stop {
 
          literal(0.0)
 
          literal(0.6)
 
        }
 
        stop {
 
          literal(20.0)
 
          literal(1.0)
 
        }
 
      }.toJson()
 
    )

You can revert to the default 2D puck using createDefault2DPuck function.

Set Puck Bearing Source​

The user location can track bearing using the device heading or device course. This option is in LocationComponentSettings.

Example​

mapView.location.puckBearing = PuckBearing.HEADING
mapView.location.puckBearing = PuckBearing.COURSE

Location Tracking​

To make the camera follow the location puck, you can use ViewportPlugin, which is available at mapView.viewport.

ViewportPlugin is primarily used to track objects on a map, but it can be extended with custom states and transitions as well.

Viewport States​

ViewportState produces camera updates based on implementation-specific rules (For example: tracking a dynamic location data source or showing a static overview of a predefined region).

Two ViewportState implementations are provided by the SDK, both of which can be instantiated from the ViewportPlugin:

Besides using these built-in implementations, you can also create your own and use them with the ViewportPlugin.

Viewport Transitions​

ViewportTransition defines how to transition to a target ViewportState.

Two ViewportTransition implementations are also provided by the SDK, both of which can be instantiated from the ViewportPlugin:

Besides using these built-in implementations, you can also create your own and use them with the ViewportPlugin.

Example​

 
    val viewportPlugin = mapView.viewport
 
    // transition to followPuckViewportState with default transition
 
    val followPuckViewportState: FollowPuckViewportState = viewportPlugin.makeFollowPuckViewportState(
 
      FollowPuckViewportStateOptions.Builder()
 
        .bearing(FollowPuckViewportStateBearing.Constant(0.0))
 
        .padding(EdgeInsets(200.0 * resources.displayMetrics.density, 0.0, 0.0, 0.0))
 
        .build()
 
    )
 
    viewportPlugin.transitionTo(followPuckViewportState) { success ->
 
      // the transition has been completed with a flag indicating whether the transition succeeded
 
    }
 
    // transition to overviewViewportState with immediate transition
 
    val overviewViewportState: OverviewViewportState = viewportPlugin.makeOverviewViewportState(
 
      OverviewViewportStateOptions.Builder()
 
        .geometry(routePoints)
 
        .padding(EdgeInsets(100.0, 100.0, 100.0, 100.0))
 
        .build()
 
    )
 
    val immediateTransition = viewportPlugin.makeImmediateViewportTransition()
 
    viewportPlugin.transitionTo(overviewViewportState, immediateTransition) { success ->
 
      // the transition has been completed with a flag indicating whether the transition succeeded
 
    }

Location provider​

The LocationProvider is an interface of Mapbox Maps SDK, to provide location updates to the LocationComponentPlugin. The current location provider used in the location component can be accessed by calling getLocationProvider().

You can register your own LocationConsumer to process the same locations used for rendering the location puck on the map. If you need access to the raw device's location, see Accessing device location.

Use Google's Fused Location Provider
The Maps SDK also comes pre-compiled with support for the Google's Fused Location Provider. If your target devices support Google Play Services, add the Google Play Location Services dependency to your project, and the Maps SDK will use the Google's Fused Location Provider in your application automatically:implementation("com.google.android.gms:play-services-location:21.0.1")

Use a custom location provider​

You can also provide your own LocationProvider to use with LocationComponentPlugin. Use thesetLocationProvider(locationProvider: LocationProvider) API to replace the default implementation.

Additional Developer Resources
Was this page helpful?