Add markers
If you have some point data in GeoJSON format or in a vector tileset, then you are ready to put markers on a map. This guide explains the decisions you need to make to add markers to your map.
In this guide, you'll learn about:
- Marker images, which define what your markers look like.
- Data sources, which define where on the map your markers will appear.
- Marker approaches, and how to choose the right one for your project.
- Marker methods, which you use to add markers to your map.
Key terms
It can be helpful to understand key terms related to markers. In Mapbox, a marker is a visual representation of a specific coordinate or point feature on a map.
The capitalized word Marker
is reserved for default marker methods of that name, and the corresponding objects they create.
For more detailed definitions, click the terms below or visit the Glossary.
- annotation: in mobile development, a shape or icon added to a map
- canvas: in web development, an HTML element used to draw graphics
- custom image: in Mapbox, an image imported by a user
- DOM: an object representing the structure and content of a web document
- icon: in Mapbox, the visual part of a marker
- marker: an image on a map, representing a location
Marker
: in Mapbox GL JS, the defaultMarker
method and the object it creates- point: a geospatial feature defined by one pair of coordinates
- source: in Mapbox, any data referenced by a map style layer
- symbol layer: in Mapbox, a layer that renders icons or text on a map
Marker images
Each Mapbox SDK and API provides a default marker image that is used by its default Marker
method. Each also allows you to add and use a custom image instead of the default marker image.
Default marker images
In the table below, you can see the default marker images for Mapbox GL JS and the Static Images API and the default marker methods used to create them. You can learn more about default marker methods in marker methods, below.
Mapbox GL JS | Static Images API |
---|---|
If you are adding markers for custom data in Mapbox Studio, we recommend that you add a custom icon to your style. Mapbox template styles do not include default marker icons. All the icons included in a template style are assigned to represent existing map features.
Custom marker images
You can use any image as a custom marker image on a Mapbox map, as long as it meets the requirements of the SDK or API used to add it.
If you add a custom image to a map style with Mapbox Studio, it will be available in the sprite associated with that style. If you add custom images to your project programmatically, your SDK will determine how those images are stored in your application.
In the table below, you can see examples of custom images used as markers on Mapbox maps, and the methods used to add custom images to a style on different platforms.
Mapbox GL JS | Maps SDK for Android | Maps SDK for iOS | Static Images API |
---|---|---|---|
Generic marker images
Need a generic marker image? You can download these generic marker images to use as custom images in your Mapbox map. The package contains multicolored marker images in two formats:
- You can use the SVG vector images with Mapbox Studio.
- You can use the PNG raster images with Mapbox SDKs and APIs.
You can also add these markers to a style in your Mapbox account with this Add generic marker images Mapbox Studio example.
Download ZIPCreate custom icons with Maki
You can use the Maki icon editor to create your own marker images or other images to be used as custom icons. Maki is an open source icon set that includes over 180 unique and customizable images.
Add data
To define the locations where markers will appear on your map, you must add a source containing some point data to your map.
You can create a dataset with the Mapbox Studio dataset editor. You can also use free tools like geojson.io or QGIS to draw points on a map, then export your data as GeoJSON. These tools can help you get latitude and longitude coordinates.
If you are adding a single marker to a static, non-interactive map image, you can provide your point data as a single pair of {lon},{lat}
coordinates in your API request. Learn more in the Static Images API marker method section, below.
To add multiple markers, or to add markers to interactive web or mobile maps, you generally must provide point data in GeoJSON format or in a vector tileset.
You can add data to a map style before runtime by using the Mapbox Studio style editor to add a vector tileset as a source for a layer in a map style.
You can add GeoJSON data to a map at runtime by hard-coding the data inline or linking to an API endpoint that serves data as GeoJSON.
You can add data from a vector tileset to a map at runtime by providing a link to the tileset, which can be hosted on Mapbox, referenced within in a Mapbox style, or hosted externally.
The specific method you choose to add markers to your map will determine the workflow required to add your data source. Continue to the add markers section to choose a method for adding your markers.
Sample data
If you want some sample point data, you can download the GeoJSON data from our Add points to a web map tutorial, or link to the public Mapbox-hosted vector tileset by using its ID: examples.civir98a801cq2oo6w6mk1aor-9msik
. This data includes nine point features representing the locations of parks in Chicago, Illinois.
Add markers
Now that you've learned about marker images and source data, you are ready to combine the two to add a marker to your map.
There are two main approaches for this task:
- Adding markers inside a map, which offers performance advantages.
- Adding markers on top of a map, which offers styling advantages.
Continue reading to understand the two approaches, so you can reflect on the needs of your application and choose a marker method that best fits your project needs.
Approach #1: Adding markers inside a map
The first approach is to add markers inside a map, where they exist in a symbol layer. In web development, this approach is called the canvas method because it draws markers on the HTML canvas
element. In mobile development, this is sometimes called the sources and layers method.
Advantages
- Highly performant; recommended for maps with over 100 markers.
- Detailed styling options are available for markers inside symbol layers.
- Easier to style markers consistently across platforms.
- Markers are exposed to Mapbox APIs, enabling user interactions.
- In mobile development, reduces the need to synchronize multiple views.
- Symbol layers can be used in combined marker methods.
Disadvantages
- Can be more complex to implement than default marker methods that add markers on top of a map.
- Can be more difficult to change a marker image after it is associated with a marker object.
Methods to add markers inside a map | Web | Android | iOS | Static image |
---|---|---|---|---|
Use Mapbox Studio | ✓ | ✓ | ✓ | ✓ |
Use the Static Images API with style parameters | ✓ | ✓ | ✓ | ✓ |
Use Mapbox GL JS with a symbol layer | ✓ | |||
Use the Maps SDK with a symbol layer | ✓ | ✓ | ||
Use combined marker methods | ✓ | ✓ | ✓ | |
Use marker alternatives | ✓ | ✓ | ✓ | ✓ |
Approach #2: Adding markers on top of a map
The second approach is to add markers on top of a map, where each marker exists as an object outside of, and on top of the map. In web development, each marker object is an individual HTMLElement
that exists on the DOM. In mobile development, each marker object exists as a view which must be synchronized with the map view.
This approach is sometimes called the Marker method, because some Mapbox SDKs offer a default Marker
method that uses this approach to create marker objects.
Advantages
- Default marker methods can simplify marker implementation.
- Markers are exposed to Mapbox APIs, enabling user interactions.
- Adding markers outside the map canvas can offer more styling flexibility and control, including the ability to use CSS to style markers on a web map.
- Markers on top of a map can be used in combined marker methods.
- Mapbox GL JS markers can be used in combined marker methods.
Disadvantages
- Less performant for many markers; not recommended for more than 20 markers.
- Can make it more difficult to style markers consistently across platforms.
- Can make marker interactions more complex to synchronize.
- On Android,
SurfaceView
s can be hard to synchronize.
Methods to add markers on top of a map | Web | Android | iOS | Static image |
---|---|---|---|---|
Use the Static Images API with overlay options | ✓ | ✓ | ✓ | ✓ |
Use Mapbox GL JS with a default Marker | ✓ | |||
Add an annotation with the Maps SDK | ✓ | ✓ | ||
Use combined marker methods | ✓ | ✓ | ✓ |
Other approaches
For a simpler approach, you can use marker alternatives like circle
or heatmap
layers to visualize point data without markers.
For more advanced use cases, you can combine these two marker approaches to maximize the advantages and minimize the disadvantages of each.
Marker methods
Now that you understand the performance and styling tradeoffs of the two main approaches, you are ready to choose the marker method that best suits the needs of your project. This section describes different methods for adding markers, including platform information, documentation, use cases, and pros and cons for each method.
Use Mapbox Studio
To add markers to an interactive map without writing any code, you can use Mapbox Studio. If you choose this method, your end product will be a style that you can use with any Mapbox map on any platform. See an example style here. This method adds markers in a symbol layer inside a map.
Related resources
Pros |
|
---|---|
Cons |
|
Use cases |
|
Use the Static Images API
When you use the Static Images API, your end product will be a non-interactive raster image of a map that you can use on a webpage, in a mobile application, or for any other purpose. You can use the Static Images API with overlay options or style parameters.
- If you use overlay options, you will include your point data in your Static Images API request and the API will add markers on top of a map before creating a static image.
- If you have an existing style layer with markers on it, you can use style parameters in your Static Images API request to add that layer inside a map before creating a static image.
Related resources
- Static Images API documentation: Overlay options
- Static Images API documentation: Style parameters
- Tutorial: Using style parameters with the Static Images API
Pros |
|
---|---|
Cons |
|
Use cases |
|
Use Mapbox GL JS
When you add markers to a map with Mapbox GL JS, your end product will be an interactive web map with markers that are exposed to the API, available for popups or other interactions. There are two main approaches:
Use Mapbox GL JS with a default Marker
When you use the default Marker
with Mapbox GL JS, the API creates Marker
objects on top of a map. The default marker image will appear unless you specify a custom marker image. This Marker
is sometimes called an HTML marker because it is rendered as an HTMLElement
on the DOM.
Related resources
Pros |
|
---|---|
Cons |
|
Use cases |
|
Use Mapbox GL JS with a symbol layer
When you use a symbol layer with Mapbox GL JS, the API draws markers inside a map. This method requires the combined use of loadImage
and addImage
to add a custom marker image, addSource
to add a source, and addLayer
to add a symbol layer to the style.
Related resources
- Mapbox GL JS API documentation:
loadImage
,addImage
,addSource
,addLayer
- Mapbox Style Specification: Symbol layer
- Generic marker images
Pros |
|
---|---|
Cons |
|
Use cases |
|
Use the Mapbox Maps SDK
You can use a Mapbox Maps SDK for Android or iOS to add annotations to Mapbox maps in mobile and embedded applications. Click a method below to learn more:
Use the Maps SDK with annotations
If you are using the Mapbox Maps SDK for Android or iOS, you can use a PointAnnotation
to access convenient and performant map annotation methods for mobile and embedded applications. This will add marker annotations on top of a map by adding new elements to the style with runtime styling.
Related resources
Pros |
|
---|---|
Cons |
|
Use cases |
|
Use the Maps SDK with a symbol layer
If you are using the Mapbox Maps SDK for Android or iOS, you can use a symbol layer manually to add markers to a map in a mobile or embedded application. This method adds marker annotations inside a map by adding new elements to the style with runtime styling.
Related resources
- Maps SDK for Android guide: Work with symbol layers
- Maps SDK for iOS guide: Work with symbol layers
- Mapbox Style Specification: Symbol layer
Pros |
|
---|---|
Cons |
|
Use cases |
|
Combining marker methods
You can combine these methods by using a canvas method to add many points to a map, then using event bindings to add more complex HTMLElement
objects. This can be an efficient way to maximize the performance benefits of a symbol
or circle
layer while also using the styling power of CSS on your HTML markers. This method uses both marker approaches described above.
Pros |
|
---|---|
Cons |
|
Use cases |
|
Marker alternatives
You can visualize point data without icons or markers by using circle or heatmap layers. These layer types are well-suited for visualizing massive data sets including over 100,000 points. They can be combined with methods that add markers on top of a map.
Use a circle layer
To visualize points on a map with filled circles instead of marker images, you can use a circle layer. If you choose this method, when a client loads your map, it will draw your circles inside the map canvas. This method uses the canvas method to add circles inside a map.
Related resources
- Mapbox GL JS API documentation:
addLayer
- Maps SDK for Android guide: Work with circle layers
- Maps SDK for iOS guide: Work with circle layers
- Mapbox Style Specification: Circle layer
Pros |
|
---|---|
Cons |
|
Use cases |
|
Use a heatmap layer
To visualize points on a map with a heatmap, you can use a heatmap
layer. If you choose this method, when a client loads your map, it will draw your circles inside the map canvas. This method uses the canvas method to render a heatmap inside a map.
Related resources
- Mapbox GL JS API documentation:
addLayer
- Maps SDK for Android guide: Work with heatmap layers
- Maps SDK for iOS guide: Work with heatmap layers
- Mapbox Style Specification: Heatmap layer
Pros |
|
---|---|
Cons |
|
Use cases |
|