Postali API — examples

Code samples for the Postali API — a free public REST API for postal codes (códigos postales) in Mexico, Colombia, and Spain.

No API key. No signup. No monthly quota.

curl https://postali.app/api/v1/mx/cp/06700

{
  "cp": "06700",
  "estado": "Ciudad de México",
  "estado_slug": "ciudad-de-mexico",
  "municipio": "Cuauhtémoc",
  "municipio_slug": "cuauhtemoc",
  "asentamientos": [
    {
      "nombre": "Roma Norte",
      "tipo": "Colonia",
      "ciudad": "Ciudad de México",
      "zona": "Urbano",
      "asenta_slug": "roma-norte"
    }
  ]
}

OpenAPI spec

The full machine-readable contract lives at:

• YAML: https://postali.app/api/openapi.yaml

Use it with Postman, Insomnia, OpenAPI Generator, Swagger Codegen, Redoc, etc.

Examples by language

Language	File
curl	examples/curl.sh
JavaScript	examples/javascript.js
Node.js	examples/node.mjs
Python	examples/python.py
PHP	examples/php.php
Ruby	examples/ruby.rb
Go	examples/go.go

All examples cover the same eight endpoints: lookup, validation, fuzzy search, regional listings, and bulk lookups.

Endpoints at a glance

Method	Path	Description
GET	/api/v1/{country}/cp/{codigo}	Lookup by postal code
GET	/api/v1/{country}/validate/{codigo}	Existence check
GET	/api/v1/{country}/search?q=…	Fuzzy search
GET	/api/v1/{country}/estados	List top-level regions
GET	/api/v1/{country}/estado/{slug}	Region details
GET	/api/v1/{country}/estado/{slug}/municipios	Municipalities of a region
GET	/api/v1/{country}/municipio/{estado}/{municipio}	Settlements of a municipality
POST	/api/v1/{country}/bulk	Bulk lookup (up to 100)

{country} is mx, co, or es. Omit it to default to mx.

Caching & fair use

Lookup endpoints (/cp, /validate, /estados, /estado/..., /municipio/...) are served from Cloudflare edge with Cache-Control: public, s-maxage=604800 — feel free to call them at any rate.

/search and /bulk are not cacheable and rate-limited per IP at the edge. Use exponential backoff starting at 200 ms on 429.

If you need the full dataset offline, please download it from the official sources directly (SEPOMEX for Mexico, GeoNames for Colombia and Spain) instead of scraping this API.

Documentation

Human-readable docs: https://postali.app/api/docs

Contributing

Pull requests welcome — especially for languages or frameworks not yet covered. Each sample should:

• Cover the eight core endpoints (or a clearly-marked subset)
• Be self-contained (single file, no extra dependencies beyond the language's stdlib + standard HTTP client)
• Avoid extra abstraction — these are samples, not SDKs

License

MIT — use, fork, modify freely.