Mapbox Static Images API
HTTP API that generates static map images (PNG or JPEG) of any location at any zoom level, with optional overlays including GeoJSON features, markers, paths, and custom styles. Returns a rasterized image URL or binary suitable for embedding in emails, PDFs, reports, SMS messages, or any context where interactive maps cannot be rendered.
Score Breakdown
⚙ Agent Friendliness
🔒 Security
Access tokens can be URL-restricted to specific domains, limiting abuse if exposed in frontend code. No OAuth or per-user auth — single token per app. Tokens are revocable via Mapbox dashboard. Sensitive data should not be embedded in map URLs as they may appear in server access logs.
⚡ Reliability
Best When
You need a server-side generated, shareable map image for a fixed location with optional overlays, especially for email, PDF, or social sharing contexts where JavaScript-based interactive maps cannot run.
Avoid When
Your users need to interact with the map, you need real-time data overlays that update frequently, or your volume is high enough that per-request pricing becomes prohibitive.
Use Cases
- • Embedding location maps in transactional emails, order confirmations, or delivery notifications without JavaScript
- • Generating map thumbnails for location-based app listings, real estate portals, or event pages
- • Producing map images for PDF reports or exported documents requiring visual geographic context
- • Rendering route or polygon visualizations as images for sharing via SMS or social media
- • Server-side map image generation for OG preview images on location-tagged content
Not For
- • Interactive maps requiring pan, zoom, or click interaction (use Mapbox GL JS instead)
- • High-volume real-time tile fetching — this is an image API, not a tile server
- • Applications needing frequent dynamic updates (the static image must be regenerated for every change)
Interface
Authentication
Authentication is via a Mapbox access token appended as a `access_token` query parameter. Tokens can be scoped with URL restrictions (allowed URLs) to prevent abuse if exposed in client-side code. Public tokens are safe to embed in HTML; secret tokens must not be exposed in client requests.
Pricing
Each API call to generate a static image counts as one request. Caching generated images client-side or in CDN is strongly recommended to avoid redundant charges for the same location/zoom/style combination.
Agent Metadata
Known Gotchas
- ⚠ GeoJSON overlays in the URL must be URL-encoded and the total URL length cannot exceed 8,192 characters — complex GeoJSON geometries with many coordinates will silently get truncated or return a 414 error; use the `overlay` parameter with POST for large geometries
- ⚠ Longitude comes before latitude in all Mapbox APIs — this is the GeoJSON standard but opposite to many other mapping APIs and human-readable address formats; agents trained on Google Maps conventions may silently swap coordinates
- ⚠ Custom style IDs require the format `mapbox://styles/{username}/{style_id}` — using just the style ID without the full URI prefix returns a 404 with a non-obvious error message
- ⚠ The `@2x` suffix for retina/high-DPI images doubles the pixel dimensions but also counts as the same number of API requests — always request @2x for display use to avoid blurry images on modern screens
- ⚠ Marker overlays use a specific URL syntax (`pin-s-label+color(lon,lat)`) that is not JSON and cannot be constructed by concatenating standard GeoJSON properties; agents must understand the custom overlay DSL
- ⚠ Static images do not support animated features, clustering, or data-driven styling — these are only available in the interactive Mapbox GL JS library; building a feature that relies on these in static images will require a different approach
Alternatives
Full Evaluation Report
Detailed scoring breakdown, competitive positioning, security analysis, and improvement recommendations for Mapbox Static Images API.
Scores are editorial opinions as of 2026-03-06.