zipfyi 0.1.1

ZIP and postal codes geocoding API client — zipfyi.com

zipfyi

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.

Table of Contents

• Install
• Quick Start
• What You Can Do
  • Look Up Postal Codes
  • Postal Code Systems Worldwide
  • Geocoding and Area Lookup
• 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

Install

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]"       # Everything

Quick Start

from 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")

What You Can Do

Look Up Postal Codes

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

Postal Code Systems Worldwide

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 and Area Lookup

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

Command-Line Interface

pip install "zipfyi[cli]"

# Search for postal codes
zipfyi search "90210"

# Output is JSON for easy piping
zipfyi search "Beverly Hills" | jq '.results[0]'

MCP Server (Claude, Cursor, Windsurf)

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

REST API Client

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")

API Reference

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/.

Learn More About Postal Codes

• Browse: Postal Codes · Cities · Countries
• Guides: Glossary · Blog
• API: REST API Docs · OpenAPI Spec

Geo FYI Family

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

FYIPedia Developer Tools

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

License

MIT