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.

EstafetaIndex is a spatial index that loads Panama’s estafeta boundary polygons from a GeoJSON file and resolves any geographic coordinate to the estafeta that contains it. Internally it combines a bounding-box pre-filter with a ray-casting point-in-polygon algorithm to keep lookups fast even when hundreds of polygon features are loaded.
estafeta.geojson.gz is not bundled in the repository. Download it from the official government endpoint before use:
curl -O https://codigospostalespanama.gob.pa/estafeta.geojson.gz

​
Constructor

EstafetaIndex(features: list[dict])
Build an index directly from a list of GeoJSON feature dicts (each with "geometry" and "properties" keys). Features missing a geometry or whose bounding box cannot be computed are silently skipped.
​
features
list[dict]
required
A list of GeoJSON feature objects. Each entry must contain a "geometry" key with a Polygon or MultiPolygon geometry and an optional "properties" dict. Pass an empty list to create an empty index.

​
Class Methods

​
EstafetaIndex.from_file()

@classmethod
def from_file(cls, path: str | Path) -> EstafetaIndex
Load an estafeta index from disk. This is the recommended entry point for most use cases.
​
path
str | Path
required
Path to the GeoJSON data file. Files ending in .gz are transparently decompressed with gzip; any other extension is read as plain UTF-8 JSON.
​
return
EstafetaIndex
A fully populated EstafetaIndex instance ready for lookup() calls.

​
Instance Methods

​
lookup()

def lookup(self, lat: float, lng: float) -> dict[str, Any] | None
Return the properties dict of the estafeta polygon that contains the given point. The search runs in two stages:
  1. Bounding-box pre-filter — only features whose (min_lng, min_lat, max_lng, max_lat) envelope contains the point proceed to the next stage.
  2. Ray-casting point-in-polygon — each candidate polygon (or MultiPolygon component) is tested with the ray-casting algorithm. Exterior rings determine containment; interior rings (holes) exclude the point.
When multiple estafeta polygons overlap at the given coordinate, the one with the smallest AREA value is returned.
GeoJSON coordinates are stored as [lng, lat] internally. The lookup() method accepts arguments in the natural Python/geographic convention (lat, lng) and reverses the order before passing values to the polygon engine.
​
lat
float
required
Latitude of the point to look up, in decimal degrees (WGS 84).
​
lng
float
required
Longitude of the point to look up, in decimal degrees (WGS 84).
​
return
dict[str, Any] | None
The "properties" dict of the matching estafeta feature, or None if the point falls outside every loaded polygon.

​
len() Support

len(idx)  # → int
Returns the number of estafeta polygon features successfully loaded into the index (features that lacked a valid geometry are excluded from this count).

​
Usage Example

from panama_postal import decode
from panama_postal_estafeta import EstafetaIndex

idx = EstafetaIndex.from_file("estafeta.geojson.gz")
print(f"Loaded {len(idx)} estafetas")

d = decode("ACC99-PJ42W")
info = idx.lookup(d.lat, d.lng)
if info:
    print(info["ESTAF_NAME"])          # Estafeta de paraiso
    print(info["VM_LEVEL2D"])          # AC
    area_m2 = float(info["AREA"])
    print(f"{area_m2:.2f} m²")        # 176.95 m²
else:
    print("No estafeta found for this point")
Pair EstafetaIndex with panama_postal.decode() to go from a raw postal code string all the way to a named estafeta in two lines of code.

​
Internal Helpers

The following module-level functions implement the geometry engine. They are used internally by EstafetaIndex and do not need to be called directly.
FunctionDescription
_point_in_ring(lng, lat, ring)Ray-casting test for a single closed ring ([lng, lat] coordinate pairs). Applies the parity rule: each ray crossing toggles inside/outside.
_point_in_polygon(lng, lat, polygon)Tests a full GeoJSON Polygon (list of rings). The point must be inside the outer ring and outside every hole ring.
_feature_contains(lng, lat, geom)Dispatches to _point_in_polygon for Polygon geometries and iterates over parts for MultiPolygon.
_feature_bbox(geom)Computes the (min_lng, min_lat, max_lng, max_lat) bounding box for a Polygon or MultiPolygon geometry; returns None for empty or unsupported geometries.
Together, _point_in_ring and _point_in_polygon implement the standard ray-casting algorithm: for a query point a horizontal ray is cast toward +∞, and the number of polygon-edge crossings determines whether the point is inside (odd count) or outside (even count).

Build docs developers (and LLMs) love

Get started for freeTalk to us