01/5 endpoints

Postal code API

Look up any Mexican postal code and get its state, municipio, city and colonias. Search by numeric prefix, or by estado, municipio and colonia name, and list the settlements behind a single code.

Base URL https://api.postalkit.mx

Authentication

Postal Code Lookup
Search by Prefix
Search by Geography
Settlements by Code
Geocode by Code

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).

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",
    "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" } }
    ]
  }
}

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",
      "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.

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" }
    }
  ]
}

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",
    "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 API

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?