# Mapbox Static Image

> Mapbox Static Image is a paid API for AI agents from Mapbox at mapbox.mpp.paywithlocus.com, paid per call via MPP, $0.004/call, status healthy (last checked 2026-10-09, last successful call 2026-09-19).

Generates a static PNG map image from Mapbox tiles with optional markers, paths, and GeoJSON overlays

## Facts

- Endpoint: POST https://mapbox.mpp.paywithlocus.com/mapbox/static-image?utm_source=zero.xyz
- Price: $0.004/call
- Payment: MPP
- Status: healthy
- Last checked: 2026-10-09
- Last successful call: 2026-09-19
- Success rate: 94% of calls made through Zero
- Rating: 5.0 / 5 from 2 reviews
- Activations on Zero: 18
- Provider: Mapbox
- Docs: https://docs.mapbox.com/api/
- Website: https://www.mapbox.com
- Tags: maps, geocoding, directions, routing, geospatial, data
- Canonical page: https://www.zero.xyz/c/mapbox-static-image-10456d81
- Structured record (JSON): https://api.zero.xyz/v1/capabilities/cap_jR9_9gI7-yLCGZHiKVqdP

Status and success rate cover calls made through Zero and Zero's own probes. Third-party monitors may report differently.

## How to call it through Zero

Zero handles the 402 payment challenge and records the run. With the Zero CLI installed (`npm i -g @zeroxyz/cli`):

```sh
zero fetch --capability mapbox-static-image-10456d81 -d '<json body>'
```

Example prompt: Generate an 800x600 Mapbox streets map image centered on Times Square in New York (lon -73.9857, lat 40.7484, zoom 14) with a red pin marker at that location.

## When to prefer this

Use this endpoint when you need a ready-to-display raster map image (PNG) for a specific location — ideal for embedding in emails, reports, UI previews, or social cards. Prefer this over interactive tile endpoints when a static snapshot is sufficient and interactivity is not required. Best when you need marker overlays or custom map styles in a single image output.

## Known failure modes

- Invalid or unsupported map style returns an error
- Image dimensions exceed 1280x1280 limit causing rejection
- Malformed overlay string (e.g. bad GeoJSON or pin syntax) returns a 422 error
- Invalid coordinate values (out of range lon/lat or zoom) cause request failure
- Auto-position with no overlay specified may produce unexpected framing

## How this service works

Generate a static map image (PNG/JPEG) with optional markers, lines, and polygons. Returns base64-encoded image data.

## Output

A binary PNG image of the rendered map (up to 1280x1280px), optionally at @2x retina resolution, showing the requested map style, center position, zoom level, and any specified markers or GeoJSON overlays.

## Example request

```json
{
 "logo": true,
 "size": "800x600",
 "style": "mapbox/streets-v12",
 "overlay": "pin-s+ff0000(-73.9857,40.7484)",
 "position": "auto",
 "attribution": true
}
```

## Request schema (JSON Schema)

```json
{
 "type": "object",
 "allOf": [
  {
   "anyOf": [
    {
     "required": [
      "position"
     ]
    },
    {
     "required": [
      "overlay"
     ]
    }
   ],
   "description": "position or overlay is required"
  }
 ],
 "properties": {
  "logo": {
   "type": "boolean",
   "description": "Show Mapbox logo (default true)"
  },
  "size": {
   "type": "string",
   "description": "Image dimensions: \"widthxheight\" in pixels, max 1280x1280 (default \"600x400\")"
  },
  "style": {
   "type": "string",
   "description": "Map style (default \"mapbox/streets-v12\"). Options: mapbox/streets-v12, mapbox/outdoors-v12, mapbox/light-v11, mapbox/dark-v11, mapbox/satellite-v9, mapbox/satellite-streets-v12"
  },
  "retina": {
   "type": "boolean",
   "description": "Generate @2x high-DPI image"
  },
  "overlay": {
   "type": "string",
   "description": "Markers, paths, or GeoJSON overlay. E.g. \"pin-s+ff0000(-73.99,40.73)\" for a red marker"
  },
  "padding": {
   "type": "string",
   "description": "Padding around auto-fit overlay (CSS shorthand: \"top,right,bottom,left\")"
  },
  "position": {
   "type": "string",
   "description": "Map center and zoom: \"lon,lat,zoom\" or \"auto\" to fit overlay bounds (default \"auto\")"
  },
  "attribution": {
   "type": "boolean",
   "description": "Show attribution (default true)"
  }
 },
 "additionalProperties": true
}
```

## More

- Live health (JSON, refreshed every minute): https://www.zero.xyz/c/mapbox-static-image-10456d81/health.json
- [Zero catalog index](https://www.zero.xyz/llms.txt)
- [Other services from mapbox.mpp.paywithlocus.com](https://www.zero.xyz/host/mapbox.mpp.paywithlocus.com/llms.txt)