REST API

By the end of this guide, you'll know every endpoint Plaza exposes and how to call each one.

All endpoints live under https://plaza.fyi/api/v1. Every request needs an x-api-key header. Responses are GeoJSON by default.

Elements

GET /elements

Query OSM elements by bounding box or H3 cell. You need at least one of bbox or h3.

Parameter	Required	Description
`bbox`	one of bbox/h3	Bounding box: `south,west,north,east`
`h3`	one of bbox/h3	H3 cell index (hex string)
`type`	no	Comma-separated: `node`, `way`, `relation`. Default: all
`tags[key]`	no	Filter by tag, e.g. `tags[amenity]=cafe`
`limit`	no	Max results (default 100, max 10,000)
`cursor`	no	Cursor for pagination

# All restaurants in a bounding box
curl "https://plaza.fyi/api/v1/elements?bbox=48.8,2.2,48.9,2.4&type=node&tags[amenity]=restaurant" \
  -H "x-api-key: pk_live_YOUR_KEY"

Tag filters support regex with the ~ prefix:

# Elements where "name" contains "park" (case-insensitive with regex)
curl "https://plaza.fyi/api/v1/elements?bbox=40.7,-74.0,40.8,-73.9&tags[name]=~[Pp]ark" \
  -H "x-api-key: pk_live_YOUR_KEY"

GET /elements/:type/:id

Fetch one element by its OSM type and ID.

curl "https://plaza.fyi/api/v1/elements/node/1234567" \
  -H "x-api-key: pk_live_YOUR_KEY"

Returns a single GeoJSON Feature:

{
  "type": "Feature",
  "geometry": { "type": "Point", "coordinates": [2.3522, 48.8566] },
  "properties": {
    "@type": "node",
    "@id": 1234567,
    "name": "Tour Eiffel",
    "tourism": "attraction"
  }
}

POST /elements/batch

Fetch up to 100 elements in one request.

curl -X POST "https://plaza.fyi/api/v1/elements/batch" \
  -H "x-api-key: pk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"elements": [{"type": "node", "id": 123}, {"type": "way", "id": 456}]}'

Nearby search

GET /nearby

Find elements near a point.

Parameter	Required	Description
`lat`	yes	Latitude
`lng`	yes	Longitude
`radius`	no	Search radius in meters
`tags`	no	Tag filter, e.g. `amenity=cafe`

curl "https://plaza.fyi/api/v1/nearby?lat=48.8584&lng=2.2945&radius=500&tags=amenity%3Dcafe" \
  -H "x-api-key: pk_live_YOUR_KEY"

Full-text search

GET /search

Search OSM features by name.

Parameter	Required	Description
`q`	yes	Search string
`limit`	no	Max results (default 25, max 100)
`cursor`	no	Cursor for pagination

curl "https://plaza.fyi/api/v1/search?q=Central+Park" \
  -H "x-api-key: pk_live_YOUR_KEY"

Geocoding

GET /geocode

Forward geocode an address or place name. See the geocoding guide for full details.

curl "https://plaza.fyi/api/v1/geocode?q=221B+Baker+Street+London" \
  -H "x-api-key: pk_live_YOUR_KEY"

GET /geocode/reverse

Reverse geocode coordinates to an address.

curl "https://plaza.fyi/api/v1/geocode/reverse?lat=48.8584&lng=2.2945" \
  -H "x-api-key: pk_live_YOUR_KEY"

GET /geocode/autocomplete

Typeahead suggestions from partial input.

curl "https://plaza.fyi/api/v1/geocode/autocomplete?q=starbuck&lat=40.7&lng=-74.0" \
  -H "x-api-key: pk_live_YOUR_KEY"

Routing

POST /route

Point-to-point routing. Modes: auto, foot, bicycle.

curl -X POST "https://plaza.fyi/api/v1/route" \
  -H "x-api-key: pk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"origin": {"lat": 48.8566, "lng": 2.3522}, "destination": {"lat": 48.8738, "lng": 2.2950}, "mode": "foot"}'

GET /isochrone

Area reachable from a point within a given time (in seconds).

curl "https://plaza.fyi/api/v1/isochrone?lat=48.8566&lng=2.3522&time=600&mode=foot" \
  -H "x-api-key: pk_live_YOUR_KEY"

POST /matrix

Distance matrix between multiple origins and destinations. Max 50 origins, 50 destinations, 2,500 total pairs.

curl -X POST "https://plaza.fyi/api/v1/matrix" \
  -H "x-api-key: pk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"origins": [{"lat": 48.8566, "lng": 2.3522}], "destinations": [{"lat": 48.8738, "lng": 2.2950}], "mode": "auto"}'

GET /nearest

Snap a coordinate to the nearest point on the road network.

curl "https://plaza.fyi/api/v1/nearest?lat=48.8566&lng=2.3522" \
  -H "x-api-key: pk_live_YOUR_KEY"

Query languages

POST /overpass

Run an Overpass QL query. See the Overpass QL guide.

curl -X POST "https://plaza.fyi/api/v1/overpass" \
  -H "x-api-key: pk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"data": "[out:json];node[amenity=pub](51.5,-0.1,51.52,0.1);out;"}'

POST /sparql

Run a SPARQL query. See the SPARQL guide.

curl -X POST "https://plaza.fyi/api/v1/sparql" \
  -H "x-api-key: pk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "PREFIX osm: <https://plaza.fyi/ns/osm#> SELECT ?s WHERE { ?s osm:amenity \"cafe\" } LIMIT 10"}'

Response format

Most endpoints return GeoJSON FeatureCollections:

{
  "type": "FeatureCollection",
  "features": [ ... ],
  "cursor": "eyJvc21faWQiOjEyMzQ1fQ=="
}

When cursor is present, there are more results. Pass it back as ?cursor=... to get the next page. When it's absent, you've reached the end.

Output formats

Use the format query parameter to change the response format:

Value	Content-Type	Description
`geojson`	`application/geo+json`	GeoJSON FeatureCollection (default)
`json`	`application/json`	Plain JSON objects
`csv`	`text/csv`	CSV with headers
`xml`	`application/xml`	OSM XML format

curl "https://plaza.fyi/api/v1/elements?bbox=48.8,2.2,48.9,2.4&format=csv" \
  -H "x-api-key: pk_live_YOUR_KEY"