On this page

Overview
Authentication
01 · Postal Codes
02 · Settlements
03 · States
04 · Municipalities
05 · Localities
06 · Streets
07 · Geocoding
08 · Account
Rate Limits & Errors

Fresh Mexican postal data

API Reference

Programmatic access to postal codes, colonias, municipios, estados, localities, and streets. Every response is JSON, every request takes one Bearer token.

Base URL https://api.postalkit.mx

postal codes: 31,880
colonias: 159,019
municipios: 2,478
estados: 32

Authentication

Every request must include your API token in the Authorization header. Generate a token from your dashboard after registering.

Authorization

Authorization: Bearer YOUR_API_KEY

Requests without a valid token return 401 Unauthorized .

Endpoints

All paths below are relative to the base URL. Segments in {braces} are required path parameters.

01/5 endpoints

Postal Codes

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 geographic coordinates. Optional street and number query parameters are included in the response for reference but do not affect the returned coordinates.

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": "19.4233000",
    "longitude": "-99.1637000",
    "geocoded_street": "Reforma",
    "geocoded_number": "100"
  }
}

404 Not Found

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

02/1 endpoints

Settlements

GET /v1/settlements?q={name}

Settlement Search

Searches settlements (colonias) by partial name. Returns a paginated list with municipality and state context.

Query Parameters

Param	Type	Description
q	string	Partial settlement name, min 2 chars. E.g. `Polanco`
page	integer	Page number (20 results per page, default 1)

Request

curl

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

Response

200 Success

{
  "data": [
    {
      "id": 8421,
      "name": "Polanco I Sección",
      "type": "Colonia",
      "postal_code": "11510",
      "municipality": "Miguel Hidalgo",
      "state": "Ciudad de México"
    }
  ],
  "links": { "first": "...", "last": "...", "prev": null, "next": "..." },
  "meta": { "current_page": 1, "total": 6, "per_page": 20 }
}

03/6 endpoints

States

GET /v1/states

List States

Returns all Mexican states with their IDs and official state codes. Use the id to query municipalities.

Request

curl

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

Response

200 Success

{
  "data": [
    { "id": 2, "name": "Aguascalientes", "code": "01" },
    { "id": 1, "name": "Ciudad de México", "code": "09" }
  ]
}

GET /v1/states/{id}/municipalities

List Municipalities by State

Returns all municipalities for a given state. Get the state id from List States.

URL Parameters

Param	Type	Description
id	integer	Numeric state ID

Request

curl

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://api.postalkit.mx/v1/states/1/municipalities

Response

200 Success

{
  "data": [
    { "id": 1, "name": "Álvaro Obregón", "code": "010" },
    { "id": 6, "name": "Cuauhtémoc", "code": "015" }
  ]
}

404 State Not Found

{ "message": "State with id 999 not found." }

GET /v1/states/by-code/{code}/municipalities

List Municipalities by INEGI Code

Returns all municipalities that belong to the state identified by its 2-digit INEGI code, ordered alphabetically.

URL Parameters

Param	Type	Description
code	string	2-digit INEGI state code, e.g. `09`

Request

curl

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://api.postalkit.mx/v1/states/by-code/09/municipalities

Response

200 Success

{
  "data": [
    { "id": 1, "name": "Álvaro Obregón", "code": "010" },
    { "id": 6, "name": "Cuauhtémoc", "code": "015" }
  ]
}

404 State Not Found

{ "message": "State with code '99' not found." }

GET /v1/states/{id}/cities

List Cities by State

Returns all cities (ciudades) that belong to the given state, ordered alphabetically.

URL Parameters

Param	Type	Description
id	integer	Numeric state ID

Request

curl

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://api.postalkit.mx/v1/states/2/cities

Response

200 Success

{
  "data": [
    { "id": 1, "name": "Aguascalientes" },
    { "id": 2, "name": "Calvillo" }
  ]
}

404 State Not Found

{ "message": "State with id 999 not found." }

GET /v1/states/{id}/postal-codes

List Postal Codes by State

Returns all postal codes that belong to the given state, ordered by code and paginated.

URL Parameters

Param	Type	Description
id	integer	Numeric state ID

Request

curl

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

Response

200 Success (paginated)

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

404 State Not Found

{ "message": "State with id 999 not found." }

GET /v1/states/{id}/municipalities/{mid}/settlements

List Settlements by Municipality

Returns all settlements that belong to the given municipality within the given state, ordered alphabetically and paginated with 20 results per page.

URL Parameters

Param	Type	Description
id	integer	Numeric state ID
mid	integer	Numeric municipality ID

Request

curl

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://api.postalkit.mx/v1/states/1/municipalities/6/settlements

Response

200 Success (paginated)

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

404 Not Found

{ "message": "State with id 999 not found." }
{ "message": "Municipality with id 999 not found." }

04/2 endpoints

Municipalities

GET /v1/municipalities/{id}/postal-codes

List Postal Codes by Municipality

Returns all postal codes that belong to the given municipality, ordered by code and paginated with 20 results per page.

URL Parameters

Param	Type	Description
id	integer	Numeric municipality ID

Request

curl

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

Response

200 Success (paginated)

{
  "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" }
    }
  ],
  "links": { "first": "...", "last": "...", "prev": null, "next": "..." },
  "meta": { "current_page": 1, "total": 71, "per_page": 20 }
}

404 Not Found

{ "message": "Municipality with id 999 not found." }

GET /v1/municipalities/{id}/settlements

List Settlements by Municipality

Returns all settlements that belong to the given municipality, ordered alphabetically and paginated with 20 results per page.

URL Parameters

Param	Type	Description
id	integer	Numeric municipality ID

Request

curl

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://api.postalkit.mx/v1/municipalities/6/settlements

Response

200 Success (paginated)

{
  "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": 230, "per_page": 20 }
}

404 Not Found

{ "message": "Municipality with id 999 not found." }

05/2 endpoints

Localities

GET /v1/localities

Search Localities

Search for localities within a state and municipality. Supports two filter modes: by name (state + municipality) with fuzzy matching, or by INEGI code (state_code + municipality_code) with exact matching. Returns paginated results ordered by name.

Query Parameters

Param	Type	Description
state	string	State name (fuzzy match). Required if not using codes.
municipality	string	Municipality name (fuzzy match). Required if not using codes.
state_code	string	INEGI state code. Required if not using names.
municipality_code	string	INEGI municipality code. Required if not using names.
page	integer	Page number (20 results per page, default 1)

Request

curl

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.postalkit.mx/v1/localities?state=Jalisco&municipality=Guadalajara"

Response

200 Success (paginated)

{
  "data": [
    {
      "id": 1,
      "locality_code": "0001",
      "name": "Guadalajara",
      "ambito": "Urbano",
      "latitude": "20.6737800",
      "longitude": "-103.3442300",
      "altitude": "1566",
      "state": { "id": 14, "name": "Jalisco", "code": "14" },
      "municipality": { "id": 39, "name": "Guadalajara", "code": "039" }
    }
  ],
  "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": { "filter": ["You must provide either (state and municipality) or (state_code and municipality_code)."] } }

GET /v1/localities/{id}

Get Locality

Retrieve a single locality by its ID, including state and municipality details.

URL Parameters

Param	Type	Description
id	integer	The locality ID

Request

curl

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://api.postalkit.mx/v1/localities/1

Response

200 Success

{
  "data": {
    "id": 1,
    "locality_code": "0001",
    "name": "Guadalajara",
    "ambito": "Urbano",
    "latitude": "20.6737800",
    "longitude": "-103.3442300",
    "altitude": "1566",
    "state": { "id": 14, "name": "Jalisco", "code": "14" },
    "municipality": { "id": 39, "name": "Guadalajara", "code": "039" }
  }
}

404 Not Found

{ "message": "Locality with id 99999 not found." }

06/2 endpoints

Streets

GET /v1/streets

Search Streets

Search for streets within a state and municipality. Optionally filter by locality and street name. Returns paginated results ordered by name.

Query Parameters

Param	Type	Description
state_code	string	INEGI state code (required). E.g. `09`
municipality_code	string	INEGI municipality code (required). E.g. `015`
locality_code	string	Optional INEGI locality code to narrow results
q	string	Optional street name search (partial match)
limit	integer	Results per page (max 100, default 50)
page	integer	Page number

Request

curl

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.postalkit.mx/v1/streets?state_code=09&municipality_code=015&q=Reforma"

Response

200 Success (paginated)

{
  "data": [
    {
      "id": 1,
      "name": "Reforma",
      "code": "0001",
      "ambito": "Urbano",
      "street_type": { "id": 1, "name": "Avenida", "code": "01" },
      "state": { "id": 1, "name": "Ciudad de México", "code": "09" },
      "municipality": { "id": 6, "name": "Cuauhtémoc", "code": "015" }
    }
  ],
  "links": { "first": "...", "last": "...", "prev": null, "next": null },
  "meta": { "current_page": 1, "total": 1, "per_page": 50 }
}

422 Validation Error

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

GET /v1/street-types

List Street Types

Retrieve the full catalog of street types (e.g. Avenida, Calle, Boulevard). Returns all types ordered by name.

Request

curl

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://api.postalkit.mx/v1/street-types

Response

200 Success

{
  "data": [
    { "id": 1, "name": "Avenida", "code": "01" },
    { "id": 2, "name": "Boulevard", "code": "02" },
    { "id": 3, "name": "Calle", "code": "03" }
  ]
}

07/1 endpoints

Geocoding

GET /v1/geocode/reverse

Reverse Geocode

Find the nearest postal code to the given latitude and longitude coordinates.

Query Parameters

Param	Type	Description
lat	number	Latitude (-90 to 90)
lng	number	Longitude (-180 to 180)

Request

curl

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.postalkit.mx/v1/geocode/reverse?lat=19.4233&lng=-99.1637"

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": "19.4233000",
    "longitude": "-99.1637000"
  }
}

404 No Results

{ "message": "No geocoded postal codes found near the given coordinates." }

422 Validation Error

{ "message": "The given data was invalid.", "errors": { "lat": ["The lat field is required."], "lng": ["The lng field is required."] } }

08/2 endpoints

Account

GET /v1/account/usage

Account Usage

Retrieve your current plan, monthly request limit, usage count, and remaining requests for the current billing period.

Request

curl

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://api.postalkit.mx/v1/account/usage

Response

200 Success

{
  "data": {
    "plan": "free",
    "monthly_limit": 100,
    "usage_count": 42,
    "remaining": 58,
    "period": "2026-08"
  }
}

GET /v1/account/db-version

Database Version

Retrieve the date of the last database update and the current API version.

Request

curl

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://api.postalkit.mx/v1/account/db-version

Response

200 Success

{
  "data": {
    "last_updated": "2026-03-15T00:00:00.000000Z",
    "version": "1.0.0"
  }
}

Rate Limits & Errors

Monthly Quotas

Plan	Requests / Month
Free	100
Starter	5,000
Pro	50,000
Business	250,000

See pricing for current plan details and monthly prices.

Rate Limit Headers

Every API response includes these headers:

headers

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 58

Error Responses

Status	Meaning
401 Unauthorized	Missing or invalid API token
404 Not Found	Resource (postal code or state) does not exist
422 Unprocessable Entity	Invalid input, check the message field for details
429 Too Many Requests	Monthly quota exceeded

API Reference

Authentication

Endpoints

Postal Codes

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

Settlements

Settlement Search

Query Parameters

States

List States

List Municipalities by State

URL Parameters

List Municipalities by INEGI Code

URL Parameters

List Cities by State

URL Parameters

List Postal Codes by State

URL Parameters

List Settlements by Municipality

URL Parameters

Municipalities

List Postal Codes by Municipality

URL Parameters

List Settlements by Municipality

URL Parameters

Localities

Search Localities

Query Parameters

Get Locality

URL Parameters

Streets

Search Streets

Query Parameters

List Street Types

Geocoding

Reverse Geocode

Query Parameters

Account

Account Usage

Database Version

Rate Limits & Errors

Ready to build?