# zipfyi

[![PyPI version](https://agentgif.com/badge/pypi/zipfyi/version.svg)](https://pypi.org/project/zipfyi/)
[![Python](https://img.shields.io/pypi/pyversions/zipfyi)](https://pypi.org/project/zipfyi/)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
[![Zero Dependencies](https://img.shields.io/badge/dependencies-0-brightgreen)](https://pypi.org/project/zipfyi/)

Python API client for [zipfyi.com](https://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](https://zipfyi.com/) 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](https://zipfyi.com/)** -- look up ZIP codes, browse cities, and explore postal systems by country.

<p align="center">
  <img src="https://raw.githubusercontent.com/fyipedia/zipfyi/main/demo.gif" alt="zipfyi demo -- ZIP and postal code geocoding API client for Python" width="800">
</p>

## Table of Contents

- [Install](#install)
- [Quick Start](#quick-start)
- [What You Can Do](#what-you-can-do)
  - [Look Up Postal Codes](#look-up-postal-codes)
  - [Postal Code Systems Worldwide](#postal-code-systems-worldwide)
  - [Geocoding and Area Lookup](#geocoding-and-area-lookup)
- [Command-Line Interface](#command-line-interface)
- [MCP Server (Claude, Cursor, Windsurf)](#mcp-server-claude-cursor-windsurf)
- [REST API Client](#rest-api-client)
- [API Reference](#api-reference)
- [Learn More About Postal Codes](#learn-more-about-postal-codes)
- [Geo FYI Family](#geo-fyi-family)
- [FYIPedia Developer Tools](#fyipedia-developer-tools)
- [License](#license)

## Install

```bash
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

```python
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 |

```python
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](https://zipfyi.com/) · [Glossary](https://zipfyi.com/glossary/) · [Guides](https://zipfyi.com/)

### 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 |

```python
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](https://zipfyi.com/) · [Blog](https://zipfyi.com/) · [API Docs](https://zipfyi.com/developers/)

### 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 |

```python
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](https://zipfyi.com/) · [States](https://zipfyi.com/) · [Glossary](https://zipfyi.com/glossary/)

## Command-Line Interface

```bash
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](https://modelcontextprotocol.io/).

```bash
pip install "zipfyi[mcp]"
```

Add to your `claude_desktop_config.json`:

```json
{
    "mcpServers": {
        "zipfyi": {
            "command": "python",
            "args": ["-m", "zipfyi.mcp_server"]
        }
    }
}
```

**Available tools**: `search_zipfyi`

## REST API Client

```python
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/](https://zipfyi.com/developers/).

## Learn More About Postal Codes

- **Browse**: [Postal Codes](https://zipfyi.com/) · [Cities](https://zipfyi.com/) · [Countries](https://zipfyi.com/)
- **Guides**: [Glossary](https://zipfyi.com/glossary/) · [Blog](https://zipfyi.com/)
- **API**: [REST API Docs](https://zipfyi.com/developers/) · [OpenAPI Spec](https://zipfyi.com/api/openapi.json)

## Geo FYI Family

Part of the [FYIPedia](https://fyipedia.com) open-source developer tools ecosystem -- geography, distance, elevation, and natural events.

| Package | PyPI | Description |
|---------|------|-------------|
| distancefyi | [PyPI](https://pypi.org/project/distancefyi/) | Haversine distance & travel times -- [distancefyi.com](https://distancefyi.com/) |
| mountainfyi | [PyPI](https://pypi.org/project/mountainfyi/) | Mountains, peaks, elevation, climbing routes -- [mountainfyi.com](https://mountainfyi.com/) |
| quakefyi | [PyPI](https://pypi.org/project/quakefyi/) | Earthquakes, seismic data, tectonic plates -- [quakefyi.com](https://quakefyi.com/) |
| **zipfyi** | [PyPI](https://pypi.org/project/zipfyi/) | **ZIP/postal codes, geocoding, area lookup -- [zipfyi.com](https://zipfyi.com/)** |

## FYIPedia Developer Tools

| Package | PyPI | npm | Description |
|---------|------|-----|-------------|
| colorfyi | [PyPI](https://pypi.org/project/colorfyi/) | [npm](https://www.npmjs.com/package/@fyipedia/colorfyi) | Color conversion, WCAG contrast, harmonies -- [colorfyi.com](https://colorfyi.com/) |
| emojifyi | [PyPI](https://pypi.org/project/emojifyi/) | [npm](https://www.npmjs.com/package/emojifyi) | Emoji encoding & metadata -- [emojifyi.com](https://emojifyi.com/) |
| symbolfyi | [PyPI](https://pypi.org/project/symbolfyi/) | [npm](https://www.npmjs.com/package/symbolfyi) | Symbol encoding in 11 formats -- [symbolfyi.com](https://symbolfyi.com/) |
| unicodefyi | [PyPI](https://pypi.org/project/unicodefyi/) | [npm](https://www.npmjs.com/package/unicodefyi) | Unicode lookup with 17 encodings -- [unicodefyi.com](https://unicodefyi.com/) |
| fontfyi | [PyPI](https://pypi.org/project/fontfyi/) | [npm](https://www.npmjs.com/package/fontfyi) | Google Fonts metadata & CSS -- [fontfyi.com](https://fontfyi.com/) |
| distancefyi | [PyPI](https://pypi.org/project/distancefyi/) | [npm](https://www.npmjs.com/package/distancefyi) | Haversine distance & travel times -- [distancefyi.com](https://distancefyi.com/) |
| timefyi | [PyPI](https://pypi.org/project/timefyi/) | [npm](https://www.npmjs.com/package/timefyi) | Timezone ops & business hours -- [timefyi.com](https://timefyi.com/) |
| namefyi | [PyPI](https://pypi.org/project/namefyi/) | [npm](https://www.npmjs.com/package/namefyi) | Korean romanization & Five Elements -- [namefyi.com](https://namefyi.com/) |
| unitfyi | [PyPI](https://pypi.org/project/unitfyi/) | [npm](https://www.npmjs.com/package/unitfyi) | Unit conversion, 220 units -- [unitfyi.com](https://unitfyi.com/) |
| holidayfyi | [PyPI](https://pypi.org/project/holidayfyi/) | [npm](https://www.npmjs.com/package/holidayfyi) | Holiday dates & Easter calculation -- [holidayfyi.com](https://holidayfyi.com/) |
| **zipfyi** | [PyPI](https://pypi.org/project/zipfyi/) | -- | **ZIP/postal codes, geocoding, area lookup -- [zipfyi.com](https://zipfyi.com/)** |
| cocktailfyi | [PyPI](https://pypi.org/project/cocktailfyi/) | -- | Cocktail ABV, calories, flavor -- [cocktailfyi.com](https://cocktailfyi.com/) |
| fyipedia | [PyPI](https://pypi.org/project/fyipedia/) | -- | Unified CLI for all FYI tools -- [fyipedia.com](https://fyipedia.com/) |

## License

MIT
