Skip to main content

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.

Panama Postal is a pure-Python toolkit for working with the Panama postal code system. Given a code like ACC99-PJ42W, it instantly returns precise GPS coordinates, the responsible postal office (estafeta), and the full political subdivision hierarchy — all without calling any external service.

Quickstart

Decode your first postal code and get GPS coordinates in under two minutes.

Installation

Clone the repo and set up optional GeoJSON data files.

Postal System Guide

Understand Panama’s 4-level geospatial grid and how codes are structured.

API Reference

Full reference for decode, encode, validate, and all lookup classes.

​
What Panama Postal Does

Panama’s postal system encodes geographic coordinates into a compact alphanumeric code using a hierarchical grid anchored at (10°N, 83.5°W). Panama Postal reverse-engineered this algorithm to give you:

Decode

Convert any postal code to latitude/longitude with ~3.3 m precision.

Encode

Turn GPS coordinates back into the geographic body of a postal code.

Validate

Check format correctness and confirm coordinates fall inside Panama.

Estafeta Lookup

Find the postal office, zone code, and coverage area for any point.

Political Division

Resolve province, district, corregimiento, village, and neighborhood.

CLI Tool

Interactive and batch-mode command-line interface with color output.

​
Key Properties

Panama Postal has zero external dependencies — it runs on Python 3.10+ using only the standard library. No pip install required.
  • Bit-for-bit accurate — the decoding algorithm was reverse-engineered from the official JavaScript bundle and verified against ~1,000 real codes.
  • Offline capable — download the optional GeoJSON files from the official government site once, and all lookups run entirely locally.
  • Hybrid fallback — when local GeoJSON files are absent, the library transparently falls back to the official API endpoint.
  • MIT licensed — free for personal and educational use.

​
Get Started in 30 Seconds

git clone https://github.com/kass507/panama-postal.git
cd panama-postal
python panama_postal_cli.py ACC99-PJ42W
Continue to the Installation guide for the full setup, including the optional GeoJSON data files that enable fully offline lookups.

Build docs developers (and LLMs) love

Get started for freeTalk to us