Annotations

Join the Mapbox Developers Discord Communityarrow-right

A newer version of the Maps SDK is available

This page uses v9.7.1 of the Mapbox Maps SDK. A newer version of the SDK is available. Learn about the latest version, v11.3.0, in the Maps SDK documentation.

Annotations have been deprecated and replaced by the Mapbox Annotation Plugin for Android

As of the 7.0.0 release of the Mapbox Maps SDK for Android, Annotations have been deprecated. To add icons, text, lines, or polygons to the map, use the Mapbox Annotation Plugin for Android. The Annotation Plugin simplifies annotations and provides additional flexibility for displaying data.Classes such as Polygon, Polyline, and Marker will no longer be maintained. Classes such as PolygonOptions and PolylineOptions and methods such as addPolygon(), addPolyline(), or addMarker() should also not be used.

Click to expand details on deprecated methods.

Source and layer

Using data sources and map layers together is the most performant option for showing data on a Mapbox map. This combination also gives you much more fine-grain control over:

• Icons that represent individual points
• Lines
• Polygons

See data-driven styling for more information. You can explore the source and layer combination for creating annotations. Below, you'll find information about less complex (and less performant) ways to show annotations.

Markers

Markers are useful when identifying a single point on the map. The SDK comes with a default marker icon which can be configured to fit your specific needs. APIs are exposed to optionally change this icon to any bitmap image you wish. To create a marker for you map, you are only required to provide a LatLng position which defines where the marker will be placed on the map. Call mapboxMap.addMarker() to add the marker to the map.

Java

Kotlin

mapboxMap?.addMarker(MarkerOptions()
	.position(LatLng(48.85819, 2.29458))
	.title("Eiffel Tower"))

Besides providing the position, you can also add a title and snippet which display inside of an info window. The info window is displayed when users tap on the marker and close when they tap outside of the info window. Add a list of markers using mapboxMap.addMarkers() if you have many markers or are loading them from a GeoJSON file.

playground

Mapbox Marker Playground

Use the Marker Playground to generate sample code for adding a single marker to a map using the Maps SDK for Android.

chevron-right

Removing markers

The Mapbox Android SDK comes with two methods for removing markers. If you'd like to remove a particular marker, use mapboxMap.removeMarker() while passing in the marker object to be removed. If you would like to remove all markers, call the mapboxMap.clear() method. Note that this will also remove any polylines and polygons you’ve added to your map.

Customize marker icon

You can specify a custom icon by using the IconFactory object and passing it to the marker. The default marker icon's used if you don’t specify an icon while creating your marker. The anchoring of the marker will be in the center, meaning if you have an icon with a point, you'll need to add padding to the bottom of the image. Place your custom marker image in your project’s drawable folder and note its file name. In the example below, the custom icon’s image file's called blue_marker.png

Java

Kotlin

// Create an Icon object for the marker to use
val icon = IconFactory.getInstance(this)
icon.fromResource(R.drawable.blue_marker)

// Add the marker to the map
mapboxMap?.addMarker(MarkerViewOptions()
	.position(LatLng(-37.821648, 144.978594))
	.icon(icon))

Capturing marker events

The Mapbox Maps SDK for Android provides a handy listener for capturing when a user taps on a marker. By default, all markers come with an onMarkerClick event listener for displaying and hiding info windows. You can override this default event listener and set your own with the setOnMarkerClickListener method. To display a toast message with the clicked marker’s title, listen for a click event with setOnMarkerClickListener and finally call Toast.makeText(). To prevent displaying a toast message and an info window at the same time, return true at the end:

Java

Kotlin

mapboxMap.setOnMarkerClickListener { marker ->

// Show a toast with the title of the selected marker
Toast.makeText(this, marker.getTitle(), Toast.LENGTH_LONG).show()
}

Update a marker

If you have intentions to update a marker rather than completely removing it, the SDK provides a few update methods. Using these mean less boilerplate code and an increase in performance since you are only updating the marker. Using these update APIs, you can create animating markers using a ValueAnimator for example. You can find the APIs for updating either the marker position or icon bitmap inside your marker object reference.

Java

Kotlin

// Change the marker location
marker.setPosition(new LatLng(-37.822884, 144.981916));

// Update the marker icon
marker.setIcon(icon);

example

Animate marker

Use a ValueAnimator to animate a marker between two positions.

chevron-right

Polyline and polygons

Adding a line or polygon to your map is like adding a marker. Due to the nature of these objects, different APIs are exposed, such as polygon color or line width. Instead of taking in a single position, bundle all your LatLng objects inside of a List and then pass them in using the addAll() method.

Draw a polyline on the map

Make sure that the first and last Point locations are the same.

Java

Kotlin

mapboxMap.addPolyline(PolylineOptions()
	.addAll(points)
	.color(Color.parseColor("#3bb2d0"))
	.width(2));

Draw a polygon on the map

Make sure that the first and last Point locations are the same.

Java

Kotlin

val polygonLatLngList = ArrayList<LatLng>()

polygonLatLngList.add(LatLng(45.522585, -122.685699))
polygonLatLngList.add(LatLng(45.534611, -122.708873))
polygonLatLngList.add(LatLng(45.530883, -122.678833))
polygonLatLngList.add(LatLng(45.547115, -122.667503))
polygonLatLngList.add(LatLng(45.530643, -122.660121))
polygonLatLngList.add(LatLng(45.533529, -122.636260))
polygonLatLngList.add(LatLng(45.521743, -122.659091))
polygonLatLngList.add(LatLng(45.510677, -122.648792))
polygonLatLngList.add(LatLng(45.515008, -122.664070))
polygonLatLngList.add(LatLng(45.502496, -122.669048))
polygonLatLngList.add(LatLng(45.515369, -122.678489))
polygonLatLngList.add(LatLng(45.506346, -122.702007))
polygonLatLngList.add(LatLng(45.522585, -122.685699))

mapboxMap.addPolygon(PolygonOptions()
	.addAll(polygonLatLngList)
	.fillColor(Color.parseColor("#3bb2d0")))

Use line and fill layers

To use the addPolyline() or addPolygon() methods in the code above, you'll have a list of LatLng objects which represent the line or the polygon area. As explained at the top of this page, using sources and layers gives you much more flexibility to show geographic data on your map. With your list of LatLng objects, you could create a FeatureCollection and use that FeatureCollection to create a GeoJsonSource. Feed the GeoJsonSource to:

• a LineLayer to show the line that you'd otherwise draw via addPolyline().
• a FillLayer to show the area that you'd otherwise draw via addPolygon().

Join the Mapbox Developers Discord Communityarrow-right