Resolving Coordinates to Panama's Political Divisions

Once you have a decoded coordinate pair, you can resolve it to Panama’s administrative geography: province, district, corregimiento (township), poblado (village), and barrio (neighborhood). The panama_postal_location module provides three locator classes that cover different tradeoffs between speed, offline capability, and simplicity.

HybridLocator is the recommended choice for most use cases. It automatically uses local GeoJSON files when they are present, and transparently falls back to the official remote API otherwise — giving you the best of both worlds without any extra configuration.

Political Division Levels

Panama uses a five-level administrative hierarchy. Each level in the result dict contains a nombre (name) and a codigo (identifier code):

{
    "provincia":     {"nombre": "PANAMÁ", "codigo": "08"},
    "distrito":      {"nombre": "PANAMÁ", "codigo": "01"},
    "corregimiento": {"nombre": "ANCÓN",  "codigo": "08"},
    "poblado":       {"nombre": "ANCÓN",  "codigo": "003"},
    "barrio":        {"nombre": "AMADOR", "codigo": "002"},
}

Levels for which no data is available return None rather than raising an error, so you can safely check each key independently.

The Three Locator Classes

RemoteLocator

Calls the official API endpoint https://codigospostalespanama.gob.pa/api/location. No local files required. Requires a network connection for every lookup.

LocalLocator

Does point-in-polygon against downloaded GeoJSON files. Works fully offline. Returns None for any level whose file is missing.

HybridLocator

Tries local first; falls back to remote if no local data is available. Supports a prefer parameter for explicit control.

Optional GeoJSON Files for Local Lookups

To enable offline resolution, download the boundary files for each political level you need. All files are hosted on the official government site.

File	Level	Name property	ID property
`PROVINCIAS.geojson.gz`	Province	`PROV_NOMB`	`PROV_ID`
`DISTRITOS.geojson.gz`	District	`DIST_NOMB`	`DIST_ID`
`CORREGIMIENTOS.geojson.gz`	Corregimiento	`CORR_NOMB`	`CORR_ID`
`POBLADOS.geojson.gz`	Village	`LUPO_NOMB`	`LUPO_ID`
`BARRIOS.geojson.gz`	Neighborhood	`BARR_NOMB`	`BARR_ID`

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

You do not need to download all five files. LocalLocator and HybridLocator resolve whichever levels have a corresponding file present and leave the rest as None.

Code Examples

HybridLocator (recommended)
RemoteLocator
LocalLocator

from panama_postal_location import HybridLocator

lat, lng = 8.94444609375, -79.56167109375001

hybrid = HybridLocator(".")

# auto: uses local if files are present, otherwise remote
r = hybrid.lookup(lat, lng)

# force remote regardless of local files
r = hybrid.lookup(lat, lng, prefer="remote")

# force local only (returns None if no local files exist)
r = hybrid.lookup(lat, lng, prefer="local")

if r:
    print(r["provincia"]["nombre"])      # PANAMÁ
    print(r["distrito"]["nombre"])       # PANAMÁ
    print(r["corregimiento"]["nombre"])  # ANCÓN
    print(r["poblado"]["nombre"])        # ANCÓN
    print(r["barrio"]["nombre"])         # AMADOR

from panama_postal_location import RemoteLocator

lat, lng = 8.94444609375, -79.56167109375001

# Default timeout is 10 seconds; adjust as needed
remote = RemoteLocator(timeout=10.0)
r = remote.lookup(lat, lng)

if r:
    print(r["provincia"]["nombre"])      # PANAMÁ
    print(r["corregimiento"]["nombre"])  # ANCÓN

from panama_postal_location import LocalLocator

lat, lng = 8.94444609375, -79.56167109375001

# Pass the directory that contains the .geojson.gz files
local = LocalLocator(".")
r = local.lookup(lat, lng)

if r:
    print(r["provincia"]["nombre"])      # PANAMÁ
    print(r["corregimiento"]["nombre"])  # ANCÓN

Checking for Local Data

HybridLocator.has_local_data() returns True if at least one of the five GeoJSON boundary files is present in the configured directory. Use this to report data availability to your users or to decide at startup which mode to announce:

from panama_postal_location import HybridLocator

hybrid = HybridLocator(".")

if hybrid.has_local_data():
    print("Local boundary files found — lookups will be offline.")
else:
    print("No local files — lookups will use the remote API.")

LocalLocator.has_any_data() exposes the same check directly on the lower-level class, which is useful when you are using LocalLocator on its own rather than through HybridLocator:

from panama_postal_location import LocalLocator

local = LocalLocator(".")

if local.has_any_data():
    result = local.lookup(lat, lng)
else:
    print("No GeoJSON boundary files found in the current directory.")

`RemoteLocator` Timeout

RemoteLocator defaults to a 10-second timeout per request. You can configure this via the constructor:

from panama_postal_location import RemoteLocator

# Short timeout for latency-sensitive applications
fast = RemoteLocator(timeout=3.0)

If the request times out or the endpoint returns an error, lookup() returns None rather than raising an exception.

The GeoJSON boundary files are data from Panama’s national statistics institute (INEC) and are not included in the Panama Postal repository. They must be downloaded from the official government site before local lookups are available.

Get Started

Guides

Resolving Coordinates to Panama's Political Divisions

Political Division Levels

The Three Locator Classes

RemoteLocator

LocalLocator

HybridLocator

Optional GeoJSON Files for Local Lookups

Code Examples

Checking for Local Data

`RemoteLocator` Timeout

Build docs developers (and LLMs) love

Get Started

Guides

Documentation Index

​Political Division Levels

​The Three Locator Classes

RemoteLocator

LocalLocator

HybridLocator

​Optional GeoJSON Files for Local Lookups

​Code Examples

​Checking for Local Data

​RemoteLocator Timeout

Build docs developers (and LLMs) love

Political Division Levels

The Three Locator Classes

Optional GeoJSON Files for Local Lookups

Code Examples

Checking for Local Data

`RemoteLocator` Timeout