Postal code API

GET /v1/postal-codes/{code}

Postal Code Lookup

Returns the full record for a single 5-digit postal code, including its state, municipality, city, and all settlements (colonias).

A code SEPOMEX has retired still answers 200, with status set to retired and the date it left the catalog in retired_at. Its settlements are the colonias it had on that date, and successors lists the live codes in the same municipality that now carry those colonias, matched by name. The prefix and geography searches leave retired codes out.

URL Parameters

Param	Type	Description
code	string	5-digit postal code, e.g. `06600`

Request

curl

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://api.postalkit.mx/v1/postal-codes/06600

Response

200 Success

{
  "data": {
    "id": 384,
    "code": "06600",
    "status": "active",
    "retired_at": null,
    "state": { "id": 1, "name": "Ciudad de México", "code": "09" },
    "municipality": { "id": 6, "name": "Cuauhtémoc", "code": "015" },
    "city": { "id": 1, "name": "Ciudad de México" },
    "settlements": [
      { "id": 532, "name": "Juárez", "zone": "Urbano", "settlement_type": { "id": 1, "name": "Colonia" } }
    ]
  }
}

200 Retired code

{
  "data": {
    "id": 21389,
    "code": "73453",
    "status": "retired",
    "retired_at": "2026-10-02",
    "state": { "id": 21, "name": "Puebla", "code": "21" },
    "municipality": { "id": 1628, "name": "Huitzilan de Serdán", "code": "078" },
    "city": null,
    "settlements": [
      { "id": 107130, "name": "Cuarta Sección", "zone": "Rural", "settlement_type": { "id": 3, "name": "Barrio" } },
      { "id": 107131, "name": "Segunda Sección", "zone": "Rural", "settlement_type": { "id": 3, "name": "Barrio" } },
      { "id": 107132, "name": "Tercera Sección", "zone": "Rural", "settlement_type": { "id": 3, "name": "Barrio" } }
    ],
    "successors": [
      { "code": "73450", "settlements": ["Cuarta Sección", "Segunda Sección", "Tercera Sección"] }
    ]
  }
}

404 Not Found

{ "message": "Postal code '99999' not found." }

GET /v1/postal-codes?q={prefix}

Search Postal Codes by Prefix

Search for postal codes by numeric prefix (useful for autocomplete). Returns paginated results ordered by code. Query must be at least 2 characters.

Query Parameters

Param	Type	Description
q	string	Numeric prefix, min 2 chars. E.g. `066`
page	integer	Page number (20 results per page, default 1)

Request

curl

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.postalkit.mx/v1/postal-codes?q=066&page=1"

Response

200 Success (paginated)

{
  "data": [ ... ],
  "links": { "first": "...", "last": "...", "prev": null, "next": "..." },
  "meta": { "current_page": 1, "total": 85, "per_page": 20 }
}

422 Validation Error

{ "message": "Query parameter \"q\" must be at least 2 characters." }

GET /v1/postal-codes/search

Search Postal Codes by Geography

Search for postal codes using geographic filters. Supports both fuzzy (LIKE) and exact matching via the exact parameter. Returns paginated results ordered by code.

Query Parameters

Param	Type	Description
state	string	State name to search (required). E.g. `Jalisco`
municipality	string	Optional municipality name filter. E.g. `Guadalajara`
colonia	string	Optional settlement (colonia) name filter. E.g. `Centro`
exact	boolean	Use exact matching instead of fuzzy (default: false)
page	integer	Page number (20 results per page, default 1)

Request

curl

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.postalkit.mx/v1/postal-codes/search?state=Jalisco&municipality=Guadalajara&colonia=Centro"

Response

200 Success (paginated)

{
  "data": [
    {
      "id": 3,
      "code": "44100",
      "status": "active",
      "retired_at": null,
      "state": { "id": 14, "name": "Jalisco", "code": "14" },
      "municipality": { "id": 39, "name": "Guadalajara", "code": "039" },
      "city": { "id": 1, "name": "Guadalajara" },
      "settlements": [
        { "id": 5, "name": "Guadalajara Centro", "zone": "Urbano", "settlement_type": { "id": 1, "name": "Colonia" } }
      ]
    }
  ],
  "links": { "first": "...", "last": "...", "prev": null, "next": null },
  "meta": { "current_page": 1, "total": 1, "per_page": 20 }
}

422 Validation Error

{ "message": "The given data was invalid.", "errors": { "state": ["The \"state\" query parameter is required."] } }

GET /v1/postal-codes/{code}/settlements

Settlements for a Postal Code

Retrieve all settlements (colonias) that belong to a specific 5-digit postal code. Returns a slim payload without full postal code details.

meta.postal_code says whether the code is active or retired. A retired code lists the colonias it had when SEPOMEX dropped it.

URL Parameters

Param	Type	Description
code	string	5-digit postal code, e.g. `06600`

Request

curl

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://api.postalkit.mx/v1/postal-codes/06600/settlements

Response

200 Success

{
  "data": [
    {
      "id": 532,
      "name": "Juárez",
      "zone": "Urbano",
      "settlement_type": { "id": 1, "name": "Colonia" }
    }
  ],
  "meta": {
    "postal_code": { "code": "06600", "status": "active", "retired_at": null }
  }
}

404 Not Found

{ "message": "Postal code '99999' not found." }

GET /v1/postal-codes/{code}/geocode

Geocode by Postal Code

Retrieve the full record for a specific 5-digit postal code with its geographic coordinates. Optional street and number query parameters are echoed back in the response for reference but do not affect the returned coordinates.

No data behind this endpoint yet

No postal code in the catalog carries coordinates yet, so this endpoint answers 200 with the record you asked for and latitude and longitude both null. Everything else in the response is real. For the state, municipio and colonias behind a code without the geocoding, use the lookup endpoint above.

URL Parameters

Param	Type	Description
code	string	5-digit postal code, e.g. `06600`

Query Parameters

Param	Type	Description
street	string	Optional street name for reference
number	string	Optional street number for reference

Request

curl

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.postalkit.mx/v1/postal-codes/06600/geocode?street=Reforma&number=100"

Response

200 Success

{
  "data": {
    "id": 384,
    "code": "06600",
    "status": "active",
    "retired_at": null,
    "state": { "id": 1, "name": "Ciudad de México", "code": "09" },
    "municipality": { "id": 6, "name": "Cuauhtémoc", "code": "015" },
    "city": null,
    "settlements": [],
    "latitude": null,
    "longitude": null,
    "geocoded_street": "Reforma",
    "geocoded_number": "100"
  }
}

404 Not Found

{ "message": "Postal code '99999' not found." }

Postal Code Lookup

URL Parameters

Search Postal Codes by Prefix

Query Parameters

Search Postal Codes by Geography

Query Parameters

Settlements for a Postal Code

URL Parameters

Geocode by Postal Code

URL Parameters

Query Parameters

Ready to build?