As of today, you can add custom overlays to your static maps when making requests to the Static API. This is useful in situations where JavaScript is not available or if you’re trying to keep your UI light. Take for example a ride sharing app that sends a receipt to the user. In the receipt email they can show the route, pickup location, and dropoff location all with a single Static API request.

Mapbox Static API with encoded polyline path

Ride sharing receipt example. View request.

The Static API allows for 4 different types of overlays: GeoJSON styled with the simplestyle-spec, Maki marker, custom marker, or an encoded polyline. A single request can have a combination of overlay types and allows up to 100 features.

Since this is Mapbox GL under the hood, it’s possible to change where the overlay ends up in the style’s layer hierarchy. By specifying the query parameter before_layer, the overlays will be inserted before the specified layer in the style. This is great for putting data under labels.

Mapbox Static API with choropleth polygons

Choropleth map with polygons underneath the labels on. View request.

Mapbox Static API with live traffic showing users morning commute

Show a user their morning commute with live traffic.

Mapbox Static API with overlays showing parks in San Francisco, CA

Highlighting parks in San Francisco, CA. View request.

Mapbox Static API with overlays showing marker with Maki icons

Dark map with Maki markers icons, custom colors, and a custom rocket marker. View request.

To get started with overlays on your static maps, check out the Static API documentation.