Python API client for zipfyi.com -- the comprehensive postal code and geocoding database covering ZIP codes, cities, states, and countries worldwide. Look up postal code boundaries, geographic coordinates, and area demographics through a free REST API, CLI, or MCP server for AI assistants.
ZipFYI maps postal codes to geographic locations with city, state, and country associations -- built for developers, logistics engineers, and data analysts who need structured address and geocoding data.
Explore postal codes at zipfyi.com -- look up ZIP codes, browse cities, and explore postal systems by country.
- Install
- Quick Start
- What You Can Do
- Command-Line Interface
- MCP Server (Claude, Cursor, Windsurf)
- REST API Client
- API Reference
- Learn More About Postal Codes
- Geo FYI Family
- FYIPedia Developer Tools
- License
pip install zipfyi # Core (zero deps)
pip install "zipfyi[cli]" # + Command-line interface
pip install "zipfyi[mcp]" # + MCP server for AI assistants
pip install "zipfyi[api]" # + HTTP client for zipfyi.com API
pip install "zipfyi[all]" # Everythingfrom zipfyi.api import ZipFYI
with ZipFYI() as api:
# Look up a postal code
postal_codes = api.list_postal_codes()
# Get details for a specific postal code
zipcode = api.get_postal_code("10001")
# Browse cities and states
cities = api.list_cities()
nyc = api.get_city("new-york")
# Search across all postal code content
results = api.search("Manhattan")A postal code (ZIP code in the United States) is a series of letters, digits, or both that is appended to a mailing address to assist mail sorting. The term "ZIP" stands for Zone Improvement Plan, introduced by the United States Postal Service in 1963. ZIP+4 codes add four additional digits for more precise delivery routing.
| US ZIP Code Format | Structure | Example | Coverage |
|---|---|---|---|
| ZIP (5-digit) | NNNNN | 10001 | General delivery area |
| ZIP+4 | NNNNN-NNNN | 10001-1234 | Specific block or building |
| ZIP Code Prefix | NNN | 100 | Regional processing center |
from zipfyi.api import ZipFYI
# Look up postal code with geographic coordinates and area info
with ZipFYI() as api:
zipcode = api.get_postal_code("10001")
print(zipcode["name"]) # Postal code details
# Browse by state
states = api.list_states()
ny = api.get_state("new-york")Learn more: Browse Postal Codes · Glossary · Guides
Different countries use different postal code formats. Some use purely numeric codes (US, Germany), others use alphanumeric (UK, Canada), and a few countries have no postal code system at all. The format length varies from 3 digits (Iceland) to 10 characters (Iran).
| Country | Format | Example | Name |
|---|---|---|---|
| United States | NNNNN | 10001 | ZIP Code |
| United Kingdom | A9 9AA | SW1A 1AA | Postcode |
| Canada | A9A 9A9 | K1A 0B1 | Postal Code |
| Germany | NNNNN | 10115 | Postleitzahl (PLZ) |
| Japan | NNN-NNNN | 100-0001 | Yubin Bango |
| Australia | NNNN | 2000 | Postcode |
| India | NNNNNN | 110001 | PIN Code |
| Brazil | NNNNN-NNN | 01001-000 | CEP |
from zipfyi.api import ZipFYI
# Browse postal systems by country
with ZipFYI() as api:
countries = api.list_countries()
japan = api.get_country("japan")
# Read blog posts about postal code systems
posts = api.list_blog_posts()
series = api.list_blog_series()Learn more: Browse Countries · Blog · API Docs
Geocoding is the process of converting an address or postal code into geographic coordinates (latitude and longitude). Reverse geocoding does the opposite -- converting coordinates into a human-readable address. Postal code geocoding provides the centroid coordinates of the delivery area.
| Geocoding Type | Input | Output | Use Case |
|---|---|---|---|
| Forward | Address or postal code | Lat/Lon coordinates | Map plotting, routing |
| Reverse | Lat/Lon coordinates | Address or postal code | Location-based services |
| Batch | Multiple addresses | Multiple coordinates | Data enrichment, ETL |
from zipfyi.api import ZipFYI
# Explore cities and their associated postal codes
with ZipFYI() as api:
cities = api.list_cities()
city = api.get_city("san-francisco")
# Access glossary terms for postal terminology
glossary = api.list_glossary()
term = api.get_term("geocoding")Learn more: Browse Cities · States · Glossary
pip install "zipfyi[cli]"
# Search for postal codes
zipfyi search "90210"
# Output is JSON for easy piping
zipfyi search "Beverly Hills" | jq '.results[0]'Add postal code data tools to any AI assistant that supports Model Context Protocol.
pip install "zipfyi[mcp]"Add to your claude_desktop_config.json:
{
"mcpServers": {
"zipfyi": {
"command": "python",
"args": ["-m", "zipfyi.mcp_server"]
}
}
}Available tools: search_zipfyi
from zipfyi.api import ZipFYI
with ZipFYI() as api:
# List endpoints
postal_codes = api.list_postal_codes()
cities = api.list_cities()
states = api.list_states()
countries = api.list_countries()
glossary = api.list_glossary()
# Detail endpoints
zipcode = api.get_postal_code("10001")
city = api.get_city("chicago")
# Search
results = api.search("downtown")| Method | Description |
|---|---|
list_postal_codes(**params) |
List all postal codes |
get_postal_code(slug) |
Get postal code detail |
list_cities(**params) |
List all cities |
get_city(slug) |
Get city detail |
list_states(**params) |
List all states/provinces |
get_state(slug) |
Get state detail |
list_countries(**params) |
List all countries |
get_country(slug) |
Get country detail |
list_glossary(**params) |
List glossary terms |
get_term(slug) |
Get glossary term detail |
list_blog_posts(**params) |
List all blog posts |
get_blog_post(slug) |
Get blog post detail |
list_blog_series(**params) |
List all blog series |
get_blog_sery(slug) |
Get blog series detail |
list_faqs(**params) |
List all FAQs |
get_faq(slug) |
Get FAQ detail |
search(query) |
Search across all content |
Full API documentation at zipfyi.com/developers/.
- Browse: Postal Codes · Cities · Countries
- Guides: Glossary · Blog
- API: REST API Docs · OpenAPI Spec
Part of the FYIPedia open-source developer tools ecosystem -- geography, distance, elevation, and natural events.
| Package | PyPI | Description |
|---|---|---|
| distancefyi | PyPI | Haversine distance & travel times -- distancefyi.com |
| mountainfyi | PyPI | Mountains, peaks, elevation, climbing routes -- mountainfyi.com |
| quakefyi | PyPI | Earthquakes, seismic data, tectonic plates -- quakefyi.com |
| zipfyi | PyPI | ZIP/postal codes, geocoding, area lookup -- zipfyi.com |
| Package | PyPI | npm | Description |
|---|---|---|---|
| colorfyi | PyPI | npm | Color conversion, WCAG contrast, harmonies -- colorfyi.com |
| emojifyi | PyPI | npm | Emoji encoding & metadata -- emojifyi.com |
| symbolfyi | PyPI | npm | Symbol encoding in 11 formats -- symbolfyi.com |
| unicodefyi | PyPI | npm | Unicode lookup with 17 encodings -- unicodefyi.com |
| fontfyi | PyPI | npm | Google Fonts metadata & CSS -- fontfyi.com |
| distancefyi | PyPI | npm | Haversine distance & travel times -- distancefyi.com |
| timefyi | PyPI | npm | Timezone ops & business hours -- timefyi.com |
| namefyi | PyPI | npm | Korean romanization & Five Elements -- namefyi.com |
| unitfyi | PyPI | npm | Unit conversion, 220 units -- unitfyi.com |
| holidayfyi | PyPI | npm | Holiday dates & Easter calculation -- holidayfyi.com |
| zipfyi | PyPI | -- | ZIP/postal codes, geocoding, area lookup -- zipfyi.com |
| cocktailfyi | PyPI | -- | Cocktail ABV, calories, flavor -- cocktailfyi.com |
| fyipedia | PyPI | -- | Unified CLI for all FYI tools -- fyipedia.com |
MIT