---
id: pgeocode
version: "0.5.0"
license: BSD
license_treatment: permissive
maintenance: dormant
---

# pgeocode — Postal code geocoding

License: permissive · Maintenance: dormant · Downloads: 1.6M/mo

## What it is and what it does

pgeocode is a Python library that performs offline geocoding by postal code using data from the GeoNames database. It converts postal codes into geographic coordinates (latitude/longitude), place names, and administrative subdivisions (state, county, community) for 83 countries. The library also supports reverse queries—finding postal codes by place name with fuzzy matching—and computing distances between postal codes.

The package wraps GeoNames data into pandas DataFrames, making results easy to filter and analyze. It depends on requests to download data, numpy for numerical operations, and pandas for tabular results. Queries are performed offline after initial data download, so repeated lookups are fast. However, the package only supports queries within a single country at a time, and maintenance has been dormant for over two years.

Use it for:

- Batch geocoding a list of postal codes to coordinates for mapping or geospatial analysis without external API calls.
- Finding the nearest city or administrative region for a given postal code in logistics or address validation workflows.
- Computing distances between postal codes for delivery route planning or proximity analysis.
- Fuzzy-matching place names to postal codes when user input is misspelled or incomplete.
- Building offline geocoding pipelines in data processing workflows where external APIs are unavailable or too slow.

## Worth the install?

AI-flagged interpretation of the facts above — verify before relying.

pgeocode queries postal codes to retrieve GPS coordinates, place names, and administrative regions from a GeoNames database covering 83 countries, and calculates distances between postal codes.

Yes, if you need offline postal code geocoding for one of the 83 supported countries and can accept dormant maintenance. The low install friction, permissive license, and lack of security vulnerabilities make it safe to use. However, verify that GeoNames data is current for your use case and be prepared to fork or patch if bugs arise, since the maintainer is not actively releasing updates.

## Install

pip install pgeocode
uv add pgeocode
poetry add pgeocode

## Installing pgeocode

Before you install: Installation is straightforward with low friction—a pure Python wheel with three common dependencies (requests, numpy, pandas). However, the package is dormant: last released 853 days ago with no recent commits visible, so expect no active maintenance or bug fixes.

License in practice: Distributed under the permissive 3-clause BSD license, so you can use, modify, and redistribute it freely in commercial or private projects without copyleft obligations.

Quickstart:

pip install pgeocode

import pgeocode
nomi = pgeocode.Nominatim('fr')
result = nomi.query_postal_code("75013")
print(result)

Requires Python 3.10 or later. Data is downloaded on first use to ~/.cache/pgeocode (configurable via PGEOCODE_DATA_DIR environment variable).

Verify before relying:

- Whether the GeoNames data source remains accessible and current for all 83 supported countries.
- Performance characteristics and memory footprint for large batch queries across multiple postal codes.
- Whether fuzzy matching and location search work reliably across non-Latin scripts or special characters.

## Package facts

- License: BSD (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: dormant
- Downloads: 1.6M/month (top 5,000 on PyPI)
- Known vulnerabilities: none known

## Tags

postal code to coordinates, geocoding by postal code, distance between zip codes, postal code lookup, reverse geocoding postal, place name from postal code, offline geocoding database, geocoding, offline-data, postal-codes

[View on SkillFed](https://skillfed.io/packages/pgeocode) · [View on PyPI](https://pypi.org/project/pgeocode/)