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/places?q=Dallas&country=US | Search imported GeoNames populated places and alternate names. |
| GET | /api/v1/place/4684888/postal | Resolve a GeoNames place to matching active postal codes without merging the source datasets. |
| GET | /api/v1/health | Public service health; no key required. |
V3.1 gazetteer endpoints are available only after the optional enrichment dataset has been imported. Their metadata identifies the general gazetteer separately from the active postal snapshot.
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.