03/6 endpoints
List the 32 Mexican states and drill into the municipios, cities, postal codes and colonias inside each one, by internal ID or by official INEGI code.
https://api.postalkit.mx
/v1/states
Returns all Mexican states with their IDs and official state codes. Use the id to query municipalities.
Request
curl -H "Authorization: Bearer YOUR_API_KEY" \ https://api.postalkit.mx/v1/states
Response
{
"data": [
{ "id": 2, "name": "Aguascalientes", "code": "01" },
{ "id": 1, "name": "Ciudad de México", "code": "09" }
]
}
/v1/states/{id}/municipalities
Returns all municipalities for a given state. Get the state id from List States.
| Param | Type | Description |
|---|---|---|
| id | integer | Numeric state ID |
Request
curl -H "Authorization: Bearer YOUR_API_KEY" \ https://api.postalkit.mx/v1/states/1/municipalities
Response
{
"data": [
{ "id": 1, "name": "Álvaro Obregón", "code": "010" },
{ "id": 6, "name": "Cuauhtémoc", "code": "015" }
]
}
{ "message": "State with id 999 not found." }
/v1/states/by-code/{code}/municipalities
Returns all municipalities that belong to the state identified by its 2-digit INEGI code, ordered alphabetically.
| Param | Type | Description |
|---|---|---|
| code | string | 2-digit INEGI state code, e.g. 09 |
Request
curl -H "Authorization: Bearer YOUR_API_KEY" \ https://api.postalkit.mx/v1/states/by-code/09/municipalities
Response
{
"data": [
{ "id": 1, "name": "Álvaro Obregón", "code": "010" },
{ "id": 6, "name": "Cuauhtémoc", "code": "015" }
]
}
{ "message": "State with code '99' not found." }
/v1/states/{id}/cities
Returns all cities (ciudades) that belong to the given state, ordered alphabetically.
| Param | Type | Description |
|---|---|---|
| id | integer | Numeric state ID |
Request
curl -H "Authorization: Bearer YOUR_API_KEY" \ https://api.postalkit.mx/v1/states/2/cities
Response
{
"data": [
{ "id": 1, "name": "Aguascalientes" },
{ "id": 2, "name": "Calvillo" }
]
}
{ "message": "State with id 999 not found." }
/v1/states/{id}/postal-codes
Returns all postal codes that belong to the given state, ordered by code and paginated.
| Param | Type | Description |
|---|---|---|
| id | integer | Numeric state ID |
Request
curl -H "Authorization: Bearer YOUR_API_KEY" \ https://api.postalkit.mx/v1/states/2/postal-codes
Response
{
"data": [
{
"id": 1,
"code": "20000",
"state": { "id": 2, "name": "Aguascalientes", "code": "01" },
"municipality": { "id": 1, "name": "Aguascalientes", "code": "001" },
"city": { "id": 1, "name": "Aguascalientes" }
}
],
"links": { "first": "...", "last": "...", "prev": null, "next": "..." },
"meta": { "current_page": 1, "total": 100, "per_page": 20 }
}
{ "message": "State with id 999 not found." }
/v1/states/{id}/municipalities/{mid}/settlements
Returns all settlements that belong to the given municipality within the given state, ordered alphabetically and paginated with 20 results per page.
| Param | Type | Description |
|---|---|---|
| id | integer | Numeric state ID |
| mid | integer | Numeric municipality ID |
Request
curl -H "Authorization: Bearer YOUR_API_KEY" \ https://api.postalkit.mx/v1/states/1/municipalities/6/settlements
Response
{
"data": [
{
"id": 532,
"name": "Juárez",
"zone": "Urbano",
"settlement_type": { "id": 1, "name": "Colonia" },
"postal_code": { "id": 384, "code": "06600" }
}
],
"links": { "first": "...", "last": "...", "prev": null, "next": "..." },
"meta": { "current_page": 1, "total": 33, "per_page": 20 }
}
{ "message": "State with id 999 not found." }
{ "message": "Municipality with id 999 not found." }
Start querying the full postal catalog in minutes.
curl -s https://api.postalkit.mx/v1/postal-codes/06600 -H "Authorization: Bearer YOUR_API_KEY"