---
title: Migrating from Mapbox | Plaza Docs
description: Switch from Mapbox APIs to Plaza for geocoding, routing, and spatial queries.
---

Plaza is a drop-in replacement for Mapbox’s API layer. Both use GeoJSON and `[lng, lat]` coordinate order. The differences are auth, endpoint paths, and a few parameter names.

## API mapping

| Mapbox API          | Mapbox endpoint                                   | Plaza endpoint         |
| ------------------- | ------------------------------------------------- | ---------------------- |
| Geocoding (forward) | `/geocoding/v5/mapbox.places/{query}.json`        | `GET /geocode`         |
| Geocoding (reverse) | `/geocoding/v5/mapbox.places/{lng},{lat}.json`    | `GET /geocode/reverse` |
| Directions          | `/directions/v5/mapbox/{profile}/{coords}`        | `POST /route`          |
| Isochrone           | `/isochrone/v1/mapbox/{profile}/{lng},{lat}`      | `GET /isochrone`       |
| Matrix              | `/directions-matrix/v1/mapbox/{profile}/{coords}` | `POST /matrix`         |

All Plaza endpoints are under `https://plaza.fyi/api/v1`.

## Auth change

Mapbox uses a query parameter:

```
https://api.mapbox.com/geocoding/v5/mapbox.places/Paris.json?access_token=pk.eyJ1...
```

Plaza uses a header:

Terminal window

```
curl -H "x-api-key: pk_live_abc123" \
  "https://plaza.fyi/api/v1/geocode?q=Paris"
```

## Coordinate order

Both use `[lng, lat]`. No changes needed.

## Travel modes

| Mapbox                   | Plaza     |
| ------------------------ | --------- |
| `mapbox/driving`         | `auto`    |
| `mapbox/driving-traffic` | `auto`    |
| `mapbox/walking`         | `foot`    |
| `mapbox/cycling`         | `bicycle` |

No traffic-aware profile — routing uses OSM road data without real-time traffic.

## Side-by-side code examples

### Geocoding

**Mapbox (Python)**

```
import httpx


response = httpx.get(
    "https://api.mapbox.com/geocoding/v5/mapbox.places/Berlin.json",
    params={"access_token": "pk.eyJ1...", "limit": 3},
)
data = response.json()
for feature in data["features"]:
    print(feature["place_name"], feature["center"])
```

**Plaza (Python)**

```
import plaza


client = plaza.Client()
results = client.v1.geocode.forward(q="Berlin", limit=3)


for feature in results.features:
    print(feature.properties["name"], feature.geometry.coordinates)
```

### Directions

**Mapbox (Python)**

```
coords = "-73.989,40.733;-73.985,40.758"
response = httpx.get(
    f"https://api.mapbox.com/directions/v5/mapbox/driving/{coords}",
    params={
        "access_token": "pk.eyJ1...",
        "geometries": "geojson",
        "overview": "full",
    },
)
route = response.json()["routes"][0]
print(f"Distance: {route['distance']}m, Duration: {route['duration']}s")
```

**Plaza (Python)**

```
route = client.v1.route(
    origin={"type": "Point", "coordinates": [-73.989, 40.733]},
    destination={"type": "Point", "coordinates": [-73.985, 40.758]},
    mode="auto",
)
print(f"Distance: {route.properties['distance_m']}m, Duration: {route.properties['duration_s']}s")
```

### Isochrone

**Mapbox (Python)**

```
response = httpx.get(
    "https://api.mapbox.com/isochrone/v1/mapbox/cycling/-73.989,40.733",
    params={
        "access_token": "pk.eyJ1...",
        "contours_minutes": "5,10,15",
        "polygons": "true",
    },
)
for feature in response.json()["features"]:
    minutes = feature["properties"]["contour"]
    print(f"{minutes} min isochrone")
```

**Plaza (Python)**

```
isochrone = client.v1.isochrone(
    location={"type": "Point", "coordinates": [-73.989, 40.733]},
    mode="bicycle",
    time="300,600,900",
)
for feature in isochrone.features:
    seconds = feature.properties["contour"]
    print(f"{seconds}s isochrone")
```

## Response differences

Both return GeoJSON, but property names differ.

### Geocoding

| Mapbox property | Plaza property                               |
| --------------- | -------------------------------------------- |
| `place_name`    | `name`                                       |
| `center`        | `geometry.coordinates`                       |
| `relevance`     | `confidence`                                 |
| `context`       | Flat properties (`city`, `state`, `country`) |

### Directions

| Mapbox property     | Plaza property          |
| ------------------- | ----------------------- |
| `routes[].distance` | `properties.distance_m` |
| `routes[].duration` | `properties.duration_s` |
| `routes[].geometry` | `geometry`              |
| `routes[].legs`     | `properties.legs`       |

## What Plaza adds

**PlazaQL.** “All pubs within 500m of a tube station” — one query. No Mapbox equivalent.

**Feature queries.** Search OSM by tag combinations, bounding box, or spatial relationships. Mapbox’s geocoder only does address/place search.

**Route optimization.** Traveling salesman across multiple stops via `POST /optimize`.

**Elevation profiles.** Altitude along a path via `POST /elevation` with a GeoJSON LineString.

## Tiles

Plaza also serves MVT tiles. See the [Vector Tiles guide](/guides/vector-tiles/index.md) for setup. Layer names and schema differ from Mapbox’s tileset, so update your style configuration.

## Pricing

| API        | Mapbox (per 1K) | Plaza (per 1K) |
| ---------- | --------------- | -------------- |
| Geocoding  | $5.00           | $0.50          |
| Directions | $5.00           | $1.50          |
| Isochrone  | $5.00           | $1.50          |
| Matrix     | $5.00           | $1.50          |

Plaza’s free tier includes 500 standard requests/day and 10 premium requests/day. Paid plans start at $50/month for 100K requests across all endpoints.