Authentication
Authorization: Bearer zcg_your_secret_keyThe full secret is shown once. ZipCodeGlobe stores only an HMAC hash and short prefix. Daily quotas are returned in rate-limit headers.
Response envelope
{
"data": {},
"meta": {"request_id":"…","source":"GeoNames","source_checked_at":"2026-07-18"},
"error": null
}Endpoints
| Method | Endpoint | Purpose |
|---|---|---|
| GET | /api/v1/postal/US/10001 | Every matching active record, capped at 100 per response. |
| GET | /api/v1/country/US | Country reference and precomputed coverage statistics. |
| GET | /api/v1/suggest?q=Berlin | Ranked search suggestions. |
| GET | /api/v1/distance?from=US:10001&to=IN:410101 | Great-circle distance using source coordinates. |
| GET | /api/v1/health | Public service health; no key required. |
Errors and quotas
Incorrect input returns 4xx status codes. Quota exhaustion returns 429. Server errors use a request ID without exposing SQL, filesystem paths or stack traces.
CORS
Server keys default to no cross-origin browser access. A key can list exact allowed origins. Widget keys use a dedicated, five-result endpoint and cannot call server endpoints.