Developer Documentation
Comprehensive ZIP code and postal code reference for developers, logistics professionals, and data analysts. Covers postal codes worldwide with geographic data, country postal systems, state/province breakdowns, statistics, interactive tools, glossary, and in-depth stories. 15 languages supported.
- Postal codes with latitude, longitude, city, state, and county data
- Countries with postal system format, regex patterns, and statistics
- States/provinces with postal code ranges and density
- Cities with postal code listings
- Postal code statistics — distribution, density, population coverage
- Country comparisons of postal systems
- Interactive tools for postal code lookup, validation, distance
- Postal terminology glossary
- In-depth stories on postal systems organized by series
Quick Start
curl -s "https://zipfyi.com/api/v1/countries/"
API Endpoints
| Method | Endpoint | Description |
|---|---|---|
| GET | /api/v1/countries/ | Countries with postal systems |
| GET | /api/v1/countries/{slug}/ | Country detail |
| GET | /api/v1/states/ | States/provinces |
| GET | /api/v1/cities/ | Cities |
| GET | /api/v1/postal-codes/ | Postal codes |
| GET | /api/v1/postal-codes/{code}/ | Postal code detail |
| GET | /api/v1/glossary/ | Glossary terms |
| GET | /api/v1/blog-series/ | Story series |
| GET | /api/v1/blog-posts/ | Story articles |
| GET | /api/v1/faqs/ | FAQs |
| GET | /api/v1/stats/ | Site statistics |
| GET | /api/v1/search/?q={query} | Search across all content |
URL Patterns
Use these patterns to construct URLs programmatically:
/countries/
Browse countries with postal data (e.g. /countries/)
/country/{slug}/
Country postal system detail (e.g. /country/united-states/)
/statistics/
Postal code statistics overview (e.g. /statistics/)
/zip/{code}/
US ZIP code detail (e.g. /zip/10001/)
/compare/{slug1}-vs-{slug2}/
Country postal comparison (e.g. /compare/united-states-vs-japan/)
/glossary/
Postal terminology glossary (e.g. /glossary/)
/glossary/{slug}/
Glossary term detail (e.g. /glossary/zip-code/)
/tools/
Interactive tools (e.g. /tools/)
/tool/{slug}/
Tool detail (e.g. /tool/zip-lookup/)
/stories/
In-depth stories (e.g. /stories/)
/series/{slug}/
Story series (e.g. /series/postal-history/)
/story/{slug}/
Story detail (e.g. /story/history-of-zip-codes/)
/nearby/
ZIP codes near me hub (e.g. /nearby/)
/nearby/{city-slug}/
ZIP codes near a specific city (e.g. /nearby/new-york/)
/search/
Search postal codes, countries (e.g. /search/?q=10001)
Response Format
All endpoints return JSON with pagination:
Example JSON response
{
"count": 636,
"next": "https://example.com/api/v1/items/?page=2",
"previous": null,
"results": [
{"slug": "example", "name": "Example Item", "...": "..."}
]
}
OpenAPI Specification
Full API schema available as OpenAPI 3.1.0 JSON. Import into Swagger UI, Postman, or any OpenAPI-compatible tool.
SDK Packages
PyPI
pip install zipfyi
ZIP and postal codes geocoding API client
Embed Widget
Embed data cards on your site:
https://widget.zipfyi.com
npm install zipfyi-embed
Format Support
- Markdown endpoints: Append
.mdto any page URL for LLM-friendly markdown output. - Internationalization: Content available in 14 languages: ko, ja, zh-hans, es, fr, de, pt, ru, vi, tr, ar, hi, th, id.