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.

The Panama Postal CLI (panama_postal_cli.py) lets you decode, validate, and enrich postal codes directly from your terminal without writing any Python code. It supports two usage modes: an interactive prompt loop for exploratory work, and a non-interactive mode for scripting or batch lookups. No external dependencies are required beyond Python 3.10+.

​
Installation

git clone https://github.com/kass507/panama-postal.git
cd panama-postal
There is no pip install step. The CLI runs directly with the Python interpreter.

​
Available Flags

FlagEffect
--laxoUses the official site’s permissive bounding box (lat 6–11, lng −86 to −74) instead of the strict Panama territory bounding box
--no-locationSkips province/district/corregimiento/poblado/barrio lookup — faster and requires no network connection
Flags can be combined with any number of code arguments: 
python panama_postal_cli.py --laxo --no-location ACC99-PJ42W

​
Usage Modes

Interactive mode launches a prompt loop where you can enter codes one at a time. This is the default when no code arguments are provided.
1

Launch the interactive prompt

python panama_postal_cli.py
The CLI prints a header and, if estafeta.geojson.gz is present, reports how many estafeta polygons were loaded. If the file is missing, it shows the download command as a reminder.
2

Enter a postal code

At the código> prompt, type any valid Panama postal code and press Enter:
código> ACC99-PJ42W
The result is printed immediately below your input.
3

Review the output

The CLI displays coordinates, precision level, estafeta data (if available), and the full political division hierarchy. A Google Maps link is always included.
4

Look up additional codes

Continue entering codes at the prompt. Each result is printed and the prompt reappears.
5

Exit the session

Type any of salir, exit, quit, or q to end the session.
código> salir

​
Sample Output

A successful lookup for a valid code inside Panama looks like this: 
Código consultado: ACC99-PJ42W
──────────────────────────────────────────────────
✓ VÁLIDO
  Latitud:       8.1444461
  Longitud:      -79.1616711
  Precisión:     ~3.3 m
  Prefijo:       AC
  Estafeta:      Estafeta de Paraiso
  Zona postal:   A6199 = AC
  Área:          176.95  km²
  Provincia:     PANAMÁ
  Distrito:      PANAMÁ
  Corregimiento: ANCÓN
  Poblado:       ANCÓN
  Barrio:        AMADOR
  Ver en mapa:   https://www.google.com/maps?q=8.1444461,-79.1616711

​
ANSI Color Output

The CLI uses ANSI escape codes to color-code results at a glance:

Green — Valid

The code has a valid format and its coordinates fall inside Panama.

Yellow — Outside Panama

The format is valid but the decoded coordinates fall outside the Panama bounding box.

Red — Invalid

The code cannot be parsed: it contains illegal characters, has the wrong length, or is not a string.

​
Data File Enrichment

The CLI automatically detects which optional data files are present in the working directory and adjusts its output accordingly.
The estafeta name (Estafeta de Paraiso), internal zone code (A6199 = AC), and coverage area in km² are displayed for every valid code. The index is loaded once at startup.Download the file with:
curl -O https://codigospostalespanama.gob.pa/estafeta.geojson.gz
The Estafeta, Zona postal, and Área lines are omitted. Decoding, validation, and coordinate output still work normally. The CLI prints a reminder at startup with the download command.
When any of the five boundary files (PROVINCIAS.geojson.gz, DISTRITOS.geojson.gz, CORREGIMIENTOS.geojson.gz, POBLADOS.geojson.gz, BARRIOS.geojson.gz) are present, the corresponding division levels are resolved locally — no network request needed.
The CLI automatically calls the official remote endpoint (/api/location) to resolve province, district, corregimiento, poblado, and barrio. Pass --no-location to skip this lookup entirely.
Remote location lookups require an active internet connection to codigospostalespanama.gob.pa. In offline environments, either download the GeoJSON boundary files or use --no-location to avoid connection errors.

Build docs developers (and LLMs) love

Get started for freeTalk to us