Limits & policy
Authentication, quotas, pagination, payload limits, caching, versioning, and service targets.
Authentication
Pass the API key in the x-api-key header. These discovery and health routes are public:
/api/api/v1/health/api/openapi.json/api/policy.json/api/subscription-policy.json
Data and GraphQL routes fail closed when API-key configuration is absent. Keep keys in server-side environment variables; do not embed them in browser bundles.
Request limits
| Limit | Value |
|---|---|
| Per-key rate limit | 100 requests per minute |
| Free-plan monthly hypothesis | 50,000 requests |
| Default REST/GraphQL page size | 25 records |
| Maximum page size | 100 records |
| Hosted reverse-geocoding batch | 1,000 points and 128 KiB |
| GraphQL request body | 32 KiB |
Every authenticated request carries X-RateLimit-Limit, X-RateLimit-Remaining, and
X-RateLimit-Reset. Read the remaining budget from those headers instead of counting requests
locally — the window is enforced per key, so anything else sharing the key draws from the same
allowance. X-RateLimit-Reset is a Unix timestamp in seconds. See Errors for the
429 shape and a retry example.
Plan quotas are currently marked as a product hypothesis in the machine-readable policy. Treat them as the current operating contract, not a permanent pricing guarantee.
Caching
Cacheable responses use a 60-second private TTL and a 300-second stale-while-revalidate window.
Use ETag with If-None-Match for conditional requests. X-Cache reports cache behavior and
X-Data-Version identifies the exact dataset snapshot. X-Request-Id is unique per request —
include it when reporting a problem.
Versioning and deprecation
Breaking schema changes receive a new major URL version. Deprecated major versions receive at
least 180 days notice through documentation and the Deprecation, Sunset, and Link headers.
Every data response also includes meta.apiVersion, meta.dataVersion, and meta.source.
Service targets
The current 30-day targets are 99% availability, warm p95 latency at or below 250 ms, and an error rate below 1%. These are operating objectives rather than a contractual SLA.
The complete machine-readable policy is available at /api/policy.json.