Authentication

Every request to Plaza requires an API key. You can pass it in any of three ways:

1. X-API-Key header (recommended):

curl https://plaza.fyi/api/v1/features?around=48.85,2.34&radius=500 \
  -H "x-api-key: pk_live_abc123"

2. Authorization: Bearer header:

curl https://plaza.fyi/api/v1/features?around=48.85,2.34&radius=500 \
  -H "Authorization: Bearer pk_live_abc123"

3. api_key query parameter (not recommended for production — keys may appear in logs):

curl "https://plaza.fyi/api/v1/features?around=48.85,2.34&radius=500&api_key=pk_live_abc123"

All SDK clients accept the key at initialization:

import Plaza from "@plazafyi/sdk";

// Reads PLAZA_API_KEY from environment automatically
const client = new Plaza();

// Or pass explicitly
const client = new Plaza({ apiKey: "pk_live_abc123" });

import plaza

# Reads PLAZA_API_KEY from environment automatically
client = plaza.Client()

# Or pass explicitly
client = plaza.Client(api_key="pk_live_abc123")

import "github.com/plazafyi/plaza-go"

// Reads PLAZA_API_KEY from environment automatically
client := plaza.NewClient()

// Or pass explicitly
client := plaza.NewClient(plaza.WithAPIKey("pk_live_abc123"))

API key format

Keys are prefixed pk_live_ for production and pk_test_ for sandbox. The prefix indicates the environment — there’s no other difference.

Getting a key

Sign up at plaza.fyi and grab a key from the dashboard. Free accounts get a key immediately. No credit card required.

Rate limits

Rate limits are per account (shared across all keys for the same user), enforced with a sliding window.

Plan	Requests/min	Included	Price
Free	10	500 standard/day + 10 premium/day	$0
Pro 100K	300	100,000/month	$50/mo
Pro 300K	1,000	300,000/month	$150/mo
Pro 1M	2,000	1,000,000/month	$500/mo
Enterprise	10,000	Custom	Custom

The free tier has a hard daily cap: 500 standard requests and 10 premium requests per day, resetting at midnight UTC. Once you hit the limit, requests return 429 daily_limit_exceeded until the next reset. No surprise bills.

Standard on-demand overage for Pro plans is $0.50 per 1,000 requests.

Premium endpoints

Routing, isochrone, distance matrix, map matching, route optimization, elevation, and nearest-snap endpoints count as 4x against your monthly allocation. A single routing request uses 4 of your included requests. Rate-per-minute limits are unaffected — only the monthly count multiplies.

Premium on-demand overage is $1.50 per 1,000 requests.

Rate limit headers

Every response includes these headers:

X-RateLimit-Limit: 300
X-RateLimit-Remaining: 297

When you hit the limit, you get a 429 with a Retry-After header (in seconds). Respect it.

Key rotation

You can have up to 3 active keys per account. The intended workflow for rotation:

1. Create a new key in the dashboard.
2. Deploy it to your application.
3. Verify traffic is flowing on the new key.
4. Revoke the old key.

Old and new keys work simultaneously until you revoke one.

Security

Do not ship your API key in client-side code. Plaza keys are secret. If you need to call Plaza from a browser, proxy through your own backend.

• Store keys in environment variables or a secrets manager, never in source code.
• Use separate keys for staging and production.
• Rotate keys if you suspect a leak. Revocation is instant.
• Monitor usage on the dashboard. Unusual spikes may indicate a compromised key.

If a key is compromised, revoke it immediately from the dashboard. There’s no undo — revoked keys stop working within seconds.