# Plaza API

> Geospatial data API serving the complete OpenStreetMap planet dataset.

Plaza provides geocoding, routing, search, isochrones, elevation, map matching,
route optimization, and raw OSM element queries — all from a single API. Spatial
data is indexed using a proprietary H3 hexagonal tiling system for fast lookups
at any scale.

**Authentication**: Pass your API key via `Authorization: Bearer <key>`, `x-api-key: <key>` header, or `api_key=<key>` query parameter.

**Response format**: Spatial endpoints return GeoJSON (`application/geo+json`). Paginated responses put metadata in HTTP headers (`X-Limit`, `X-Has-More`, `X-Next-Cursor`, `Link`), not the body.


## Endpoints
- Geocoding: Forward and reverse geocoding, autocomplete, and batch
- Routing & Directions: Point-to-point directions, isochrones, distance matrices, turn-by-turn
- Place Search: Full-text search across all OSM entities
- Spatial Predicates: Query features by spatial relationship: near, within, intersects, contains, crosses, touches (and negations)
- Output Shaping: Control response geometry: simplify, buffer, centroid, precision, field filtering, computed extras (bbox, distance, center)
- JSON Requests: Query endpoints take a POST with a JSON body; feature lookups by ID, tiles and optimize job status are GET
- Geometry Input: All spatial inputs are GeoJSON geometry objects (RFC 7946), coordinates in [longitude, latitude] order
- PlazaQL: Hosted PlazaQL for complex spatial queries against the full OSM dataset
- Elevation: Point lookups and path elevation profiles
- Map Matching: Snap GPS traces to the road network
- Route Optimization: Best visiting order for 2 to 50 waypoints for one vehicle, with optional time windows, service times and capacity
- EV Routing: Range-aware directions with charging stop planning
- Departure-Time Routing: ETAs for a given departure time from hourly weekday/weekend speed profiles per road class and urban density (no live traffic data)
- Reverse Geocoding: Convert coordinates to human-readable addresses
- Autocomplete: Type-ahead address suggestions with sub-100ms latency
- Distance Matrix: Travel times and distances between multiple origins and destinations
- Isochrone: Areas reachable from a point within one or more travel-time budgets
- Vector Tiles: Mapbox Vector Tiles of OSM in the Shortbread schema at GET /api/v1/tiles/{z}/{x}/{y}, filtered per request by tags, layers, properties and element types (PlazaQL: search(...).tile(z, x, y)); MapLibre style at /api/v1/tiles/style.json and TileJSON at /api/v1/tiles.json need no API key
- Custom Datasets: Upload GeoJSON feature collections, query alongside OSM data via REST or PlazaQL dataset() source

## Pricing
- Free: 500 standard/day + 50 premium/day, no credit card required
- Standard rate: $0.50/1K requests
- Premium rate: $1.50/1K requests
- Premium endpoints count as 4x against included allocation
- Custom data storage: Free 1MB, Pro 100K 1GB, Pro 300K 5GB, Pro 1M 20GB, overage $5/GB/month
- Free (free): $0/mo, 500 std/day + 50 prm/day included, 10 req/min
- Pro (pro_100k): $50/mo, 100K included, 300 req/min
- Pro (pro_300k): $150/mo, 300K included, 1000 req/min
- Pro (pro_1m): $500/mo, 1M included, 2000 req/min
- Enterprise (enterprise): Custom/mo, 100M included, 10000 req/min

## Key Facts
- Data: OpenStreetMap (ODbL) — cache and redistribute with attribution
- Formats: GeoJSON (default), NDJSON and CSV streaming via the format parameter, Mapbox Vector Tiles
- Query languages: REST and PlazaQL
- 8 billion nodes, 1 billion ways, 15 million relations
- Coverage: First region: North America, loading now. More regions on request. https://plaza.fyi/coverage

## Links
- Docs: https://docs.plaza.fyi
- API reference: https://docs.plaza.fyi/api
- OpenAPI spec (JSON): https://plaza.fyi/api/openapi
- Pricing: https://plaza.fyi/pricing
- Coverage: https://plaza.fyi/coverage
- Playground: https://plaza.fyi/playground

## SDKs
- TypeScript, Python and Go SDKs are generated from the OpenAPI spec above.
- Until they are published, point any OpenAPI client generator at https://plaza.fyi/api/openapi, or call the REST API directly with an API key in the x-api-key header.