Panama Postal ships as a set of plain Python source files — no package index, no build step, no virtual environment required. The only prerequisite is Python 3.10 or later. Everything else is Python standard library.Documentation Index
Fetch the complete documentation index at: https://mintlify.com/kass507/panama-postal/llms.txt
Use this file to discover all available pages before exploring further.
There is no
pip install panama-postal. Setup is a single git clone. If Python 3.10+ is available on your system, the library and CLI are ready to use immediately after cloning.Installation Steps
The four source files —
panama_postal.py, panama_postal_estafeta.py, panama_postal_location.py, and panama_postal_cli.py — are all you need to decode, encode, and validate postal codes.Panama Postal uses
match statements and union type hints (X | Y) introduced in Python 3.10. Confirm your version:For offline estafeta lookups and political division resolution, download the government-published GeoJSON files into the project directory:
curl -O https://codigospostalespanama.gob.pa/estafeta.geojson.gz
curl -O https://codigospostalespanama.gob.pa/PROVINCIAS.geojson.gz
curl -O https://codigospostalespanama.gob.pa/DISTRITOS.geojson.gz
curl -O https://codigospostalespanama.gob.pa/CORREGIMIENTOS.geojson.gz
curl -O https://codigospostalespanama.gob.pa/POBLADOS.geojson.gz
curl -O https://codigospostalespanama.gob.pa/BARRIOS.geojson.gz
Place these files in the same directory as the Python scripts so the library can find them automatically.
GeoJSON Data Files Explained
Each.geojson.gz file serves a distinct enrichment purpose:
| File | Enables |
|---|---|
estafeta.geojson.gz | Estafeta name (ESTAF_NAME), postal zone (VM_LEVEL, VM_LEVEL2D), and service area (AREA) via point-in-polygon lookup |
PROVINCIAS.geojson.gz | Province name and code (e.g. PANAMÁ) |
DISTRITOS.geojson.gz | District name and code (e.g. PANAMÁ) |
CORREGIMIENTOS.geojson.gz | Corregimiento name and code (e.g. ANCÓN) |
POBLADOS.geojson.gz | Village (poblado) name and code |
BARRIOS.geojson.gz | Neighborhood (barrio) name and code |
These files are not bundled in the repository. They are public data published by INEC Panama and downloaded directly from the official government site. Panama Postal does not redistribute them.
What Happens Without the GeoJSON Files
The core codec —decode(), encode(), and validate() — works entirely without GeoJSON files since it is pure arithmetic over a geographic grid. For enrichment data:
- Estafeta lookups (
EstafetaIndex) requireestafeta.geojson.gzand will not produce results without it. - Political division lookups (
HybridLocator) automatically fall back to the officialcodigospostalespanama.gob.pa/api/locationendpoint when local files are absent. An active internet connection is required for the fallback to succeed.
Project File Overview
| File | Description |
|---|---|
panama_postal.py | Core codec: decode, encode, validate, is_in_panama |
panama_postal_estafeta.py | Estafeta lookup via point-in-polygon against estafeta.geojson.gz |
panama_postal_location.py | Political division lookup — local GeoJSON or remote API fallback |
panama_postal_cli.py | Command-line interface with interactive and batch modes |
CLI Flags Reference
| Flag | Effect |
|---|---|
--no-location | Skips province/district lookup — faster, requires no network |
--laxo | Uses the official site’s permissive bounding box for validation instead of the strict territory bbox |