How to Use the Mapbox Snapshot API to Generate Map Images

Direct answer: Mapbox’s “Snapshot API” is documented as the Static Images API. It returns a standalone, non-interactive image generated from a Mapbox Studio style. Send a GET request to the style’s /static/ endpoint with an access token, viewport or bounds, image dimensions, and optional overlays such as markers or GeoJSON.

The general URL shape is:

https://api.mapbox.com/styles/v1/{username}/{style_id}/static/{overlay}/{viewport}/{width}x{height}{@2x}{.format}?access_token=YOUR_TOKEN

For example, this request renders a 900 by 600 image centered on New York:

curl "https://api.mapbox.com/styles/v1/mapbox/streets-v12/static/-74.006,40.7128,10/900x600?access_token=YOUR_TOKEN" -o map.png

Mapbox calls the result a static map because it is a rendered image, not an interactive map. The service returns PNG for styles with vector layers and JPEG for styles containing only raster layers; PNG, JPEG, and WebP can be requested where supported. See the official Static Images API reference for the complete parameter syntax.

1. Prepare a Mapbox Static Images request

Choose the style owner and style ID, such as mapbox/streets-v12.
Create an access token with the documented styles:tiles scope.
Choose one extent method: a center plus zoom, a bounding box, or auto to fit an overlay.
Set width and height from 1 to 1,280 pixels each.
Add @2x when you need a high-density image.
Save the response as an image or use the request URL in an HTML <img> element.

Do not combine auto or a bounding box with center and zoom values. When using auto, Mapbox can calculate an extent from the overlay and applies default padding when you do not provide padding.

Center and zoom

Use longitude, latitude, and zoom when the map should always show a known viewpoint:

curl "https://api.mapbox.com/styles/v1/mapbox/streets-v12/static/-73.9857,40.7484,12/1000x700.png?access_token=YOUR_TOKEN" -o manhattan.png

Bounding box

Use a bounding box when you know the western, southern, eastern, and northern limits. The exact bounding-box form is documented by Mapbox:

curl "https://api.mapbox.com/styles/v1/mapbox/streets-v12/static/-74.26,40.49,-73.68,40.93/1000x700?access_token=YOUR_TOKEN" -o region.png

A bounding box is useful for reports and thumbnails where every feature must fit inside a known geographic area. Keep the four coordinates in west, south, east, north order.

Fit an overlay with `auto`

When the visible extent should be calculated from GeoJSON, a marker collection, or another supported overlay, use auto in place of the viewport. Do not also send a center and zoom.

2. Add markers, GeoJSON, and paths

Static Images requests can include markers, GeoJSON, a custom marker image, or an encoded path. Overlay order controls which feature appears on top. URI-encode overlay values because GeoJSON and style parameters commonly contain reserved characters.

GeoJSON overlay example

This Python example builds a small point feature, URL-encodes it, and asks Mapbox to fit the result automatically:

import json
import urllib.parse
import requests

feature = {
    "type": "Feature",
    "geometry": {"type": "Point", "coordinates": [-73.9857, 40.7484]},
    "properties": {}
}
geojson = urllib.parse.quote(json.dumps(feature, separators=(",", ":")))
url = (
    "https://api.mapbox.com/styles/v1/mapbox/streets-v12/static/"
    f"geojson({geojson})/auto/900x600?access_token=YOUR_TOKEN"
)
response = requests.get(url, timeout=30)
response.raise_for_status()
with open("point-map.png", "wb") as image:
    image.write(response.content)

For large GeoJSON, simplify the geometry or move the data into a custom Mapbox Studio style and reference that style. Mapbox documents an 8,192-character maximum request URL, so a detailed geometry can exceed the limit before rendering begins.

Markers and custom marker images

Use the marker overlay syntax from the Mapbox reference when you need a point marker. You can also provide a custom marker image. If more than one overlay is present, place the overlay that should appear on top later in the overlay expression.

Encoded paths

Encoded paths are useful for routes and lines. Encode reserved characters before inserting the path into the URL, and use auto when the route should determine the viewport.

3. Choose image dimensions and format

Choice	Use it when	Constraint
Fixed center and zoom	Every image uses the same viewpoint	You must choose suitable coordinates and zoom
Bounding box	A known region must fit exactly	Do not combine with center and zoom
`auto`	An overlay should determine the extent	Requires a supported overlay
Normal dimensions	Web thumbnails and standard reports	Each dimension is 1–1,280 pixels
`@2x`	High-density or retina displays	Increases the rendered pixel density and file size
PNG	Vector styles or transparency-sensitive workflows	Availability depends on the style and request
JPEG	Raster-only styles or smaller photographic output	Lossy compression
WebP	Supported clients that benefit from compact images	Confirm support for your selected style and request

Mapbox documents a maximum of 1,280 pixels for both width and height. A 1,280 by 1,280 request with @2x produces a high-density asset, so check memory and downstream file-size limits before using it at scale.

4. Complete runnable examples

cURL

curl -G "https://api.mapbox.com/styles/v1/mapbox/streets-v12/static/-74.006,40.7128,10/900x600.webp" \
  --data-urlencode "access_token=YOUR_TOKEN" \
  -o new-york.webp

Python

import requests

url = "https://api.mapbox.com/styles/v1/mapbox/streets-v12/static/-74.006,40.7128,10/900x600.png"
response = requests.get(url, params={"access_token": "YOUR_TOKEN"}, timeout=30)
response.raise_for_status()
with open("new-york.png", "wb") as image:
    image.write(response.content)

Node.js

const url = new URL(
  "https://api.mapbox.com/styles/v1/mapbox/streets-v12/static/-74.006,40.7128,10/900x600.png"
);
url.searchParams.set("access_token", process.env.MAPBOX_TOKEN);

const response = await fetch(url);
if (!response.ok) {
  throw new Error(`Mapbox returned ${response.status}`);
}
const buffer = Buffer.from(await response.arrayBuffer());
await import("node:fs/promises").then(fs => fs.writeFile("new-york.png", buffer));

Display the result in HTML

<img
  src="https://api.mapbox.com/styles/v1/mapbox/streets-v12/static/-74.006,40.7128,10/900x600.png?access_token=YOUR_TOKEN"
  width="900"
  height="600"
  alt="Map of New York"
>

Keep access tokens out of public source when your deployment model requires a server-side proxy. Restrict tokens according to your Mapbox account controls and avoid placing long-lived secrets in logs.

5. Attribution and style compatibility

The result uses Web Mercator and is non-interactive. Mapbox Standard and Mapbox Standard Satellite are not supported by this API according to the reference documentation.

Attribution remains your responsibility. Setting attribution=false only disables attribution in the generated image; it does not remove the legal requirement to provide proper attribution elsewhere. Mapbox states that maps using OpenStreetMap data, which includes most Mapbox maps, require that attribution.

Decide where attribution will appear before shipping: in the surrounding webpage, a report footer, or another nearby document location that meets the applicable requirements.

6. Reliability, limits, and cost planning

Rate limit: the documented default limit is 1,250 requests per minute. Exceeding it returns HTTP 429. Contact Mapbox if you need a higher limit.
URL length: requests are limited to 8,192 characters. Simplify large GeoJSON or use a custom Studio style when necessary.
Style caching: a style change can take up to 12 hours to appear in a static map. Do not assume an edited style is visible immediately.
Billing: Mapbox measures usage in API requests. Verify the current included volume and rates on the Mapbox pricing documentation before estimating production cost.
Retries: retry transient network failures and 5xx responses with exponential backoff. Do not blindly retry 4xx errors such as an invalid token or malformed URL.
Validation: check the HTTP status and content type before writing the response to an image file. An error document saved as .png will look like a broken image later.

For batch generation, queue requests below the documented rate limit, cache identical URLs, and record the request URL, status code, response time, and output dimensions. If a style is updated, plan for the documented cache delay in release schedules.

7. Troubleshooting

Symptom	Likely cause	Fix
401 or 403 response	Missing, invalid, expired, or insufficiently scoped token	Check the token and ensure it has the documented `styles:tiles` scope.
404 response	Incorrect style owner, style ID, or endpoint path	Copy the style URL from Mapbox Studio and verify the owner, ID, and `/static/` path.
422 or malformed image	Invalid viewport, overlay, or unencoded reserved characters	Test without overlays, then URL-encode GeoJSON, paths, and other parameter values.
HTTP 429	Rate limit exceeded	Slow the queue, add exponential backoff, and contact Mapbox for a higher limit if needed.
Overlay is missing	Incorrect overlay syntax, order, or coordinates	Validate the overlay against the official syntax and remember that later overlays render above earlier ones.
Map is cropped	Center and zoom do not cover the intended region	Use a bounding box or `auto` with the overlay instead of guessing zoom.
Updated style is not visible	Static map cache still contains the prior style	Allow up to 12 hours for the documented cache delay.
Attribution complaint	Attribution was disabled in the image without replacement	Add proper attribution elsewhere; `attribution=false` does not remove that obligation.
Request exceeds URL length	GeoJSON or encoded path is too large	Simplify geometry or move it into a custom Studio style.

8. Or skip the browser setup

If you need a screenshot of a map page, dashboard, or documentation page rather than a Mapbox-rendered map image, ScreenshotNeo provides a website screenshot API. It accepts one GET request and returns PNG, JPEG, WebP, or PDF. The API can remove cookie and consent banners, newsletter popups, and chat widgets before capture. Bot checks, blank pages, failed loads, timeouts, and cache hits are not billed, and the response identifies the result with X-Page-Verdict and X-Billed headers. ScreenshotNeo also provides an MCP server for AI agents with take_screenshot, get_page_info, and capture_pdf.

See the ScreenshotNeo API documentation for all options. A one-call capture looks like this:

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp

import requests
r = requests.get("https://api.screenshotneo.com/v1/shot", params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"}, timeout=90)
open("shot.webp", "wb").write(r.content)

const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);

There are 1,000 free screenshots each month with no card. Paid plans start at $5 for 3,000 screenshots. Create a free ScreenshotNeo account.

9. FAQ

Is the Mapbox Static Images API interactive?

No. It returns a standalone, non-interactive image generated from a Mapbox Studio style.

Can I use a custom map style?

Yes. Supply the style owner and style ID in the documented URL path. A custom Studio style can also be a practical way to keep large geographic data out of the request URL.

Should I use `auto` or a bounding box?

Use auto when an overlay should determine the extent. Use a bounding box when the geographic limits are already known and must be consistent.

Why did my style update take so long?

Mapbox documents that caching can delay a style change by up to 12 hours.

Where do I verify current Mapbox pricing?

Check Mapbox’s current pricing documentation; rates and included usage can change.