Skip to main content

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.

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 .md to 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.