# Mapbox

> **You are on:** `https://beta-api.paywithlocus.com/api` | [llms.txt](https://beta.paywithlocus.com/llms.txt)
>
> Locus runs on multiple environments -- make sure every URL you call matches your expected environment.
> | Environment | Landing | API |
> |---|---|---|
> | Production | paywithlocus.com | api.paywithlocus.com |
> | Beta | beta.paywithlocus.com | beta-api.paywithlocus.com |
> | Stage | stage.paywithlocus.com | stage-api.paywithlocus.com |
>
> If the API URL above doesn't match your expected environment, re-fetch this file from the correct domain.

> Location and mapping APIs — geocoding, directions, isochrones, matrix routing, map matching, static maps, and spatial queries.

**Category:** Geospatial | **Website:** [www.mapbox.com](https://www.mapbox.com) | **Docs:** [docs.mapbox.com/api/](https://docs.mapbox.com/api/)

## Access Methods

| Method | Base URL | Auth |
|--------|----------|------|
| **MPP (Tempo)** | `https://mapbox.mpp.paywithlocus.com/mapbox/` | HTTP 402 auto-payment |
| **Wrapped API** | `https://beta-api.paywithlocus.com/api/wrapped/mapbox/` | `Authorization: Bearer <LOCUS_API_KEY>` |

**OpenAPI discovery:** `GET https://mapbox.mpp.paywithlocus.com/openapi.json`

## Endpoints

### Forward Geocode

Convert an address or place name to geographic coordinates (longitude, latitude).

**Estimated cost:** $0.004

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `q` | string | Yes | Search text (address, place name, etc.) |
| `proximity` | string | No | Bias results near a coordinate: "lon,lat" or "ip" |
| `bbox` | string | No | Bounding box to limit results: "minLon,minLat,maxLon,maxLat" |
| `country` | string | No | Comma-separated ISO 3166-1 alpha-2 country codes |
| `language` | string | No | IETF language tag for results (e.g. "en", "fr") |
| `limit` | number | No | Maximum number of results (1-10, default 5) |
| `types` | string | No | Filter by feature type: country, region, postcode, district, place, locality, neighborhood, address, street, block |
| `autocomplete` | boolean | No | Enable autocomplete for partial queries (default true) |
| `worldview` | string | No | Worldview code (e.g. "us", "cn", "jp") |

```bash
curl -X POST https://mapbox.mpp.paywithlocus.com/mapbox/geocode-forward \
  -H "Content-Type: application/json" \
  -d '{"q":"<string>","proximity":"<string>","bbox":"<string>","country":"<string>","language":"<string>","limit":"<number>","types":"<string>","autocomplete":"<boolean>","worldview":"<string>"}'
```

### Reverse Geocode

Convert geographic coordinates (longitude, latitude) to an address or place name.

**Estimated cost:** $0.004

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `longitude` | number | Yes | Longitude (-180 to 180) |
| `latitude` | number | Yes | Latitude (-90 to 90) |
| `country` | string | No | Comma-separated ISO 3166-1 alpha-2 country codes |
| `language` | string | No | IETF language tag for results |
| `limit` | number | No | Maximum number of results (1-5, default 1) |
| `types` | string | No | Filter by feature type |
| `worldview` | string | No | Worldview code |

```bash
curl -X POST https://mapbox.mpp.paywithlocus.com/mapbox/geocode-reverse \
  -H "Content-Type: application/json" \
  -d '{"longitude":"<number>","latitude":"<number>","country":"<string>","language":"<string>","limit":"<number>","types":"<string>","worldview":"<string>"}'
```

### Directions

Get driving, walking, cycling, or traffic-aware routes between 2-25 coordinates.

**Estimated cost:** $0.005

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `profile` | string | Yes | Routing profile: mapbox/driving, mapbox/driving-traffic, mapbox/walking, mapbox/cycling |
| `coordinates` | string | Yes | Semicolon-separated lon,lat pairs (e.g. "-73.99,40.73;-77.03,38.90") |
| `alternatives` | boolean | No | Return up to 2 alternative routes |
| `steps` | boolean | No | Include turn-by-turn instructions |
| `annotations` | string | No | Comma-separated: distance, duration, speed, congestion, maxspeed, closure |
| `geometries` | string | No | Response geometry format: geojson, polyline, polyline6 |
| `overview` | string | No | Route geometry detail: full, simplified, false |
| `language` | string | No | Language for turn instructions (e.g. "en") |
| `exclude` | string | No | Road types to exclude: motorway, toll, ferry, unpaved, cash_only_tolls |

```bash
curl -X POST https://mapbox.mpp.paywithlocus.com/mapbox/directions \
  -H "Content-Type: application/json" \
  -d '{"profile":"<string>","coordinates":"<string>","alternatives":"<boolean>","steps":"<boolean>","annotations":"<string>","geometries":"<string>","overview":"<string>","language":"<string>","exclude":"<string>"}'
```

### Matrix

Calculate travel time and distance between many origins and destinations. Billed per element (sources × destinations).

**Estimated cost:** $0.002/element

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `profile` | string | Yes | Routing profile: mapbox/driving, mapbox/driving-traffic, mapbox/walking, mapbox/cycling |
| `coordinates` | string | Yes | Semicolon-separated lon,lat pairs (2-25, max 10 for traffic) |
| `sources` | string | No | Semicolon-separated indices for source coordinates (for asymmetric matrices) |
| `destinations` | string | No | Semicolon-separated indices for destination coordinates |
| `annotations` | string | No | Comma-separated: duration, distance (or both) |
| `approaches` | string | No | Semicolon-separated approach per coordinate: unrestricted or curb |

```bash
curl -X POST https://mapbox.mpp.paywithlocus.com/mapbox/matrix \
  -H "Content-Type: application/json" \
  -d '{"profile":"<string>","coordinates":"<string>","sources":"<string>","destinations":"<string>","annotations":"<string>","approaches":"<string>"}'
```

### Isochrone

Get travel-time or travel-distance polygons showing areas reachable from a point.

**Estimated cost:** $0.005

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `profile` | string | Yes | Routing profile: mapbox/driving, mapbox/driving-traffic, mapbox/walking, mapbox/cycling |
| `coordinates` | string | Yes | Single coordinate: "lon,lat" |
| `contours_minutes` | string | No | Comma-separated travel times in minutes (1-60, up to 4 contours) |
| `contours_meters` | string | No | Comma-separated distances in meters (1-100000, up to 4 contours) |
| `polygons` | boolean | No | Return polygons instead of linestrings (default false) |
| `denoise` | number | No | Noise filter (0.0-1.0) |
| `generalize` | number | No | Douglas-Peucker simplification tolerance in meters |
| `exclude` | string | No | Road types to exclude: motorway, toll, ferry, unpaved |

```bash
curl -X POST https://mapbox.mpp.paywithlocus.com/mapbox/isochrone \
  -H "Content-Type: application/json" \
  -d '{"profile":"<string>","coordinates":"<string>","contours_minutes":"<string>","contours_meters":"<string>","polygons":"<boolean>","denoise":"<number>","generalize":"<number>","exclude":"<string>"}'
```

### Map Matching

Snap GPS traces to the road network. Corrects noisy GPS data into clean routes.

**Estimated cost:** $0.005

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `profile` | string | Yes | Routing profile: mapbox/driving, mapbox/driving-traffic, mapbox/walking, mapbox/cycling |
| `coordinates` | string | Yes | Semicolon-separated lon,lat pairs (2-100 coordinates) |
| `annotations` | string | No | Comma-separated: distance, duration, speed, congestion, maxspeed |
| `geometries` | string | No | Response format: geojson, polyline, polyline6 |
| `overview` | string | No | Geometry detail: full, simplified, false |
| `radiuses` | string | No | Semicolon-separated search radius per coordinate (0-50 meters) |
| `steps` | boolean | No | Include turn-by-turn instructions |
| `timestamps` | string | No | Semicolon-separated Unix timestamps per coordinate |
| `tidy` | boolean | No | Clean up coordinate clusters for better matching |

```bash
curl -X POST https://mapbox.mpp.paywithlocus.com/mapbox/map-matching \
  -H "Content-Type: application/json" \
  -d '{"profile":"<string>","coordinates":"<string>","annotations":"<string>","geometries":"<string>","overview":"<string>","radiuses":"<string>","steps":"<boolean>","timestamps":"<string>","tidy":"<boolean>"}'
```

### Static Image

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

**Estimated cost:** $0.004

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `style` | string | No | 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 |
| `position` | string | No | Map center and zoom: "lon,lat,zoom" or "auto" to fit overlay bounds (default "auto") |
| `size` | string | No | Image dimensions: "widthxheight" in pixels, max 1280x1280 (default "600x400") |
| `overlay` | string | No | Markers, paths, or GeoJSON overlay. E.g. "pin-s+ff0000(-73.99,40.73)" for a red marker |
| `retina` | boolean | No | Generate @2x high-DPI image |
| `attribution` | boolean | No | Show attribution (default true) |
| `logo` | boolean | No | Show Mapbox logo (default true) |
| `padding` | string | No | Padding around auto-fit overlay (CSS shorthand: "top,right,bottom,left") |

```bash
curl -X POST https://mapbox.mpp.paywithlocus.com/mapbox/static-image \
  -H "Content-Type: application/json" \
  -d '{"style":"<string>","position":"<string>","size":"<string>","overlay":"<string>","retina":"<boolean>","attribution":"<boolean>","logo":"<boolean>","padding":"<string>"}'
```

### Tilequery

Query vector tileset features near a geographic point. Useful for spatial lookups (e.g. "what features are within 100m of this point?").

**Estimated cost:** $0.005

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `tileset_id` | string | Yes | Tileset ID to query (e.g. "mapbox.mapbox-streets-v8"). Comma-separate up to 25. |
| `longitude` | number | Yes | Longitude (-180 to 180) |
| `latitude` | number | Yes | Latitude (-85 to 85) |
| `radius` | number | No | Search radius in meters (default 0 for point-in-polygon) |
| `limit` | number | No | Max features to return (1-50, default 5) |
| `dedupe` | boolean | No | Remove duplicate features (default true) |
| `geometry` | string | No | Filter by geometry type: polygon, linestring, point |
| `layers` | string | No | Comma-separated layer names to query |

```bash
curl -X POST https://mapbox.mpp.paywithlocus.com/mapbox/tilequery \
  -H "Content-Type: application/json" \
  -d '{"tileset_id":"<string>","longitude":"<number>","latitude":"<number>","radius":"<number>","limit":"<number>","dedupe":"<boolean>","geometry":"<string>","layers":"<string>"}'
```