Migrating from Mapbox

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:

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 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.