php artisan api:generate-key --name="My App". Pass the key as a Bearer token in the Authorization header.'
security:
-
default: []
paths:
/api/health:
get:
summary: ''
operationId: getApiHealth
description: ''
parameters: []
responses:
200:
description: ''
content:
application/json:
schema:
type: object
example:
status: ok
service: 'CodigoPostal MX API'
version: 1.0.0
timestamp: '2026-05-13T15:52:18+00:00'
properties:
status:
type: string
example: ok
service:
type: string
example: 'CodigoPostal MX API'
version:
type: string
example: 1.0.0
timestamp:
type: string
example: '2026-05-13T15:52:18+00:00'
tags:
- General
/api/v1/postal-codes/search:
get:
summary: 'Search postal codes by state, municipality, and/or colonia'
operationId: searchPostalCodesByStateMunicipalityAndorColonia
description: "Search for postal codes using geographic filters. Supports both fuzzy (LIKE) and exact\nmatching via the `exact` parameter. Returns paginated results ordered by code."
parameters:
-
in: query
name: state
description: 'State name to search.'
example: Jalisco
required: true
schema:
type: string
description: 'State name to search.'
example: Jalisco
-
in: query
name: municipality
description: 'Optional municipality name filter.'
example: Guadalajara
required: false
schema:
type: string
description: 'Optional municipality name filter.'
example: Guadalajara
-
in: query
name: colonia
description: 'Optional settlement (colonia) name filter.'
example: Centro
required: false
schema:
type: string
description: 'Optional settlement (colonia) name filter.'
example: Centro
-
in: query
name: exact
description: 'Use exact matching instead of fuzzy (default: false).'
example: true
required: false
schema:
type: boolean
description: 'Use exact matching instead of fuzzy (default: false).'
example: true
-
in: query
name: page
description: 'Page number (20 results per page).'
example: 1
required: false
schema:
type: integer
description: 'Page number (20 results per page).'
example: 1
responses:
200:
description: Results
content:
application/json:
schema:
type: object
example:
data:
-
id: 3
code: '44100'
state:
id: 1
name: Jalisco
code: '14'
municipality:
id: 2
name: Guadalajara
code: '039'
city:
id: 1
name: Guadalajara
settlements:
-
id: 5
name: Centro
type: Colonia
postal_code: '44100'
links:
first: ...
last: ...
prev: null
next: null
meta:
current_page: 1
total: 1
per_page: 20
properties:
data:
type: array
example:
-
id: 3
code: '44100'
state:
id: 1
name: Jalisco
code: '14'
municipality:
id: 2
name: Guadalajara
code: '039'
city:
id: 1
name: Guadalajara
settlements:
-
id: 5
name: Centro
type: Colonia
postal_code: '44100'
items:
type: object
properties:
id:
type: integer
example: 3
code:
type: string
example: '44100'
state:
type: object
properties:
id:
type: integer
example: 1
name:
type: string
example: Jalisco
code:
type: string
example: '14'
municipality:
type: object
properties:
id:
type: integer
example: 2
name:
type: string
example: Guadalajara
code:
type: string
example: '039'
city:
type: object
properties:
id:
type: integer
example: 1
name:
type: string
example: Guadalajara
settlements:
type: array
example:
-
id: 5
name: Centro
type: Colonia
postal_code: '44100'
items:
type: object
properties:
id:
type: integer
example: 5
name:
type: string
example: Centro
type:
type: string
example: Colonia
postal_code:
type: string
example: '44100'
links:
type: object
properties:
first:
type: string
example: ...
last:
type: string
example: ...
prev:
type: string
example: null
nullable: true
next:
type: string
example: null
nullable: true
meta:
type: object
properties:
current_page:
type: integer
example: 1
total:
type: integer
example: 1
per_page:
type: integer
example: 20
422:
description: 'Missing state'
content:
application/json:
schema:
type: object
example:
message: 'The given data was invalid.'
errors:
state:
- 'The "state" query parameter is required.'
properties:
message:
type: string
example: 'The given data was invalid.'
errors:
type: object
properties:
state:
type: array
example:
- 'The "state" query parameter is required.'
items:
type: string
tags:
- 'Postal Codes'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
state:
type: string
description: 'Must be at least 1 character.'
example: bngzmiyvdljnikhw
municipality:
type: string
description: 'Must be at least 1 character.'
example: aykcmyuwpwlvqwrs
nullable: true
colonia:
type: string
description: 'Must be at least 1 character.'
example: itcpscqldzsnrwtu
nullable: true
exact:
type: boolean
description: ''
example: false
nullable: true
required:
- state
'/api/v1/postal-codes/{code}':
get:
summary: 'Exact postal code lookup'
operationId: exactPostalCodeLookup
description: "Retrieve the full record for a specific 5-digit postal code, including state, municipality,\ncity, and all settlements (colonias) that share that code.\nResponses include `Cache-Control: public, max-age=3600` for client-side caching."
parameters: []
responses:
200:
description: Found
content:
application/json:
schema:
type: object
example:
data:
id: 3
code: '06600'
state:
id: 1
name: 'Ciudad de México'
code: '09'
municipality:
id: 2
name: Cuauhtémoc
code: '015'
city:
id: 1
name: 'Ciudad de México'
settlements:
-
id: 5
name: 'Roma Sur'
type: Colonia
postal_code: '06600'
properties:
data:
type: object
properties:
id:
type: integer
example: 3
code:
type: string
example: '06600'
state:
type: object
properties:
id:
type: integer
example: 1
name:
type: string
example: 'Ciudad de México'
code:
type: string
example: '09'
municipality:
type: object
properties:
id:
type: integer
example: 2
name:
type: string
example: Cuauhtémoc
code:
type: string
example: '015'
city:
type: object
properties:
id:
type: integer
example: 1
name:
type: string
example: 'Ciudad de México'
settlements:
type: array
example:
-
id: 5
name: 'Roma Sur'
type: Colonia
postal_code: '06600'
items:
type: object
properties:
id:
type: integer
example: 5
name:
type: string
example: 'Roma Sur'
type:
type: string
example: Colonia
postal_code:
type: string
example: '06600'
401:
description: Unauthenticated
content:
application/json:
schema:
type: object
example:
error: Unauthenticated
message: 'A valid API key is required. Pass it as: Authorization: Bearer {token}'
properties:
error:
type: string
example: Unauthenticated
message:
type: string
example: 'A valid API key is required. Pass it as: Authorization: Bearer {token}'
404:
description: 'Not found'
content:
application/json:
schema:
type: object
example:
message: "Postal code '99999' not found."
properties:
message:
type: string
example: "Postal code '99999' not found."
422:
description: 'Invalid format'
content:
application/json:
schema:
type: object
example:
message: 'Postal code must be exactly 5 digits.'
properties:
message:
type: string
example: 'Postal code must be exactly 5 digits.'
429:
description: 'Rate limited'
content:
application/json:
schema:
type: object
example:
error: 'Too Many Requests'
message: 'Rate limit exceeded. You are allowed 1 000 requests per hour.'
retry_after: 1800
properties:
error:
type: string
example: 'Too Many Requests'
message:
type: string
example: 'Rate limit exceeded. You are allowed 1 000 requests per hour.'
retry_after:
type: integer
example: 1800
tags:
- 'Postal Codes'
parameters:
-
in: path
name: code
description: 'The 5-digit postal code.'
example: '06600'
required: true
schema:
type: string
'/api/v1/postal-codes/{code}/settlements':
get:
summary: 'Settlements for a postal code'
operationId: settlementsForAPostalCode
description: "Retrieve all settlements (colonias) that belong to a specific 5-digit postal code.\nReturns a slim payload without full postal code details.\nResponses include `Cache-Control: public, max-age=3600` for client-side caching."
parameters: []
responses:
200:
description: Found
content:
application/json:
schema:
type: object
example:
data:
-
id: 5
name: 'Roma Sur'
zone: Urbano
settlement_type:
id: 1
name: Colonia
properties:
data:
type: array
example:
-
id: 5
name: 'Roma Sur'
zone: Urbano
settlement_type:
id: 1
name: Colonia
items:
type: object
properties:
id:
type: integer
example: 5
name:
type: string
example: 'Roma Sur'
zone:
type: string
example: Urbano
settlement_type:
type: object
properties:
id:
type: integer
example: 1
name:
type: string
example: Colonia
404:
description: 'Not found'
content:
application/json:
schema:
type: object
example:
message: "Postal code '99999' not found."
properties:
message:
type: string
example: "Postal code '99999' not found."
422:
description: 'Invalid format'
content:
application/json:
schema:
type: object
example:
message: 'Postal code must be exactly 5 digits.'
properties:
message:
type: string
example: 'Postal code must be exactly 5 digits.'
tags:
- 'Postal Codes'
parameters:
-
in: path
name: code
description: 'The 5-digit postal code.'
example: '06600'
required: true
schema:
type: string
'/api/v1/postal-codes/{code}/geocode':
get:
summary: 'Geocode by postal code'
operationId: geocodeByPostalCode
description: "Retrieve the full record for a specific 5-digit postal code with geographic coordinates.\nOptional `street` and `number` query parameters are included in the response for reference\nbut do not affect the returned coordinates.\nResponses include `Cache-Control: public, max-age=3600` for client-side caching."
parameters:
-
in: query
name: street
description: 'Optional street name for reference.'
example: Reforma
required: false
schema:
type: string
description: 'Optional street name for reference.'
example: Reforma
-
in: query
name: number
description: 'Optional street number for reference.'
example: '100'
required: false
schema:
type: string
description: 'Optional street number for reference.'
example: '100'
responses:
200:
description: Found
content:
application/json:
schema:
type: object
example:
data:
id: 3
code: '06600'
state:
id: 1
name: 'Ciudad de Mexico'
code: '09'
municipality:
id: 2
name: Cuauhtemoc
code: '015'
city: null
settlements: []
latitude: '19.4233000'
longitude: '-99.1637000'
geocoded_street: null
geocoded_number: null
properties:
data:
type: object
properties:
id:
type: integer
example: 3
code:
type: string
example: '06600'
state:
type: object
properties:
id:
type: integer
example: 1
name:
type: string
example: 'Ciudad de Mexico'
code:
type: string
example: '09'
municipality:
type: object
properties:
id:
type: integer
example: 2
name:
type: string
example: Cuauhtemoc
code:
type: string
example: '015'
city:
type: string
example: null
nullable: true
settlements:
type: array
example: []
latitude:
type: string
example: '19.4233000'
longitude:
type: string
example: '-99.1637000'
geocoded_street:
type: string
example: null
nullable: true
geocoded_number:
type: string
example: null
nullable: true
404:
description: 'Not found'
content:
application/json:
schema:
type: object
example:
message: "Postal code '99999' not found."
properties:
message:
type: string
example: "Postal code '99999' not found."
422:
description: 'Invalid format'
content:
application/json:
schema:
type: object
example:
message: 'Postal code must be exactly 5 digits.'
properties:
message:
type: string
example: 'Postal code must be exactly 5 digits.'
tags:
- 'Postal Codes'
parameters:
-
in: path
name: code
description: 'The 5-digit postal code.'
example: '06600'
required: true
schema:
type: string
/api/v1/postal-codes:
get:
summary: 'Search postal codes by prefix'
operationId: searchPostalCodesByPrefix
description: "Search for postal codes by numeric prefix (useful for autocomplete). Returns paginated\nresults ordered by code. Query must be at least 2 characters."
parameters:
-
in: query
name: q
description: 'Numeric prefix to search. Must be at least 2 characters.'
example: '066'
required: true
schema:
type: string
description: 'Numeric prefix to search. Must be at least 2 characters.'
example: '066'
-
in: query
name: page
description: 'Page number (20 results per page).'
example: 1
required: false
schema:
type: integer
description: 'Page number (20 results per page).'
example: 1
responses:
200:
description: Results
content:
application/json:
schema:
type: object
example:
data:
-
id: 3
code: '06600'
state:
id: 1
name: 'Ciudad de México'
code: '09'
municipality:
id: 2
name: Cuauhtémoc
code: '015'
city:
id: 1
name: 'Ciudad de México'
links:
first: ...
last: ...
prev: null
next: null
meta:
current_page: 1
total: 1
per_page: 20
properties:
data:
type: array
example:
-
id: 3
code: '06600'
state:
id: 1
name: 'Ciudad de México'
code: '09'
municipality:
id: 2
name: Cuauhtémoc
code: '015'
city:
id: 1
name: 'Ciudad de México'
items:
type: object
properties:
id:
type: integer
example: 3
code:
type: string
example: '06600'
state:
type: object
properties:
id:
type: integer
example: 1
name:
type: string
example: 'Ciudad de México'
code:
type: string
example: '09'
municipality:
type: object
properties:
id:
type: integer
example: 2
name:
type: string
example: Cuauhtémoc
code:
type: string
example: '015'
city:
type: object
properties:
id:
type: integer
example: 1
name:
type: string
example: 'Ciudad de México'
links:
type: object
properties:
first:
type: string
example: ...
last:
type: string
example: ...
prev:
type: string
example: null
nullable: true
next:
type: string
example: null
nullable: true
meta:
type: object
properties:
current_page:
type: integer
example: 1
total:
type: integer
example: 1
per_page:
type: integer
example: 20
422:
description: 'Query too short'
content:
application/json:
schema:
type: object
example:
message: 'Query parameter "q" must be at least 2 characters.'
properties:
message:
type: string
example: 'Query parameter "q" must be at least 2 characters.'
tags:
- 'Postal Codes'
/api/v1/settlements:
get:
summary: 'Search settlements by name'
operationId: searchSettlementsByName
description: "Full-text partial search across all settlement names in the SEPOMEX catalog. The search is\ncase-insensitive and matches anywhere in the name. Returns paginated results ordered\nalphabetically. Query must be at least 2 characters."
parameters:
-
in: query
name: q
description: 'Partial name of the settlement to search for.'
example: Roma
required: true
schema:
type: string
description: 'Partial name of the settlement to search for.'
example: Roma
-
in: query
name: page
description: 'Page number (20 results per page).'
example: 1
required: false
schema:
type: integer
description: 'Page number (20 results per page).'
example: 1
responses:
200:
description: Results
content:
application/json:
schema:
type: object
example:
data:
-
id: 5
name: 'Roma Sur'
type: Colonia
postal_code: '06600'
municipality: Cuauhtémoc
state: 'Ciudad de México'
links:
first: ...
last: ...
prev: null
next: null
meta:
current_page: 1
total: 2
per_page: 20
properties:
data:
type: array
example:
-
id: 5
name: 'Roma Sur'
type: Colonia
postal_code: '06600'
municipality: Cuauhtémoc
state: 'Ciudad de México'
items:
type: object
properties:
id:
type: integer
example: 5
name:
type: string
example: 'Roma Sur'
type:
type: string
example: Colonia
postal_code:
type: string
example: '06600'
municipality:
type: string
example: Cuauhtémoc
state:
type: string
example: 'Ciudad de México'
links:
type: object
properties:
first:
type: string
example: ...
last:
type: string
example: ...
prev:
type: string
example: null
nullable: true
next:
type: string
example: null
nullable: true
meta:
type: object
properties:
current_page:
type: integer
example: 1
total:
type: integer
example: 2
per_page:
type: integer
example: 20
422:
description: 'Query too short'
content:
application/json:
schema:
type: object
example:
message: 'Query parameter "q" must be at least 2 characters.'
properties:
message:
type: string
example: 'Query parameter "q" must be at least 2 characters.'
tags:
- Settlements
/api/v1/states:
get:
summary: 'List all states'
operationId: listAllStates
description: "Returns the complete list of the 32 Mexican states (estados) ordered alphabetically.\nEach state includes its SEPOMEX state code."
parameters: []
responses:
200:
description: Success
content:
application/json:
schema:
type: object
example:
data:
-
id: 5
name: Aguascalientes
code: '01'
-
id: 1
name: 'Ciudad de México'
code: '09'
properties:
data:
type: array
example:
-
id: 5
name: Aguascalientes
code: '01'
-
id: 1
name: 'Ciudad de México'
code: '09'
items:
type: object
properties:
id:
type: integer
example: 5
name:
type: string
example: Aguascalientes
code:
type: string
example: '01'
tags:
- 'States & Municipalities'
'/api/v1/states/by-code/{code}/municipalities':
get:
summary: 'List municipalities for a state by INEGI code'
operationId: listMunicipalitiesForAStateByINEGICode
description: "Returns all municipalities (municipios) that belong to the state identified by its\n2-digit INEGI code, ordered alphabetically."
parameters: []
responses:
200:
description: Success
content:
application/json:
schema:
type: object
example:
data:
-
id: 1
name: 'Álvaro Obregón'
code: '010'
-
id: 2
name: Cuauhtémoc
code: '015'
properties:
data:
type: array
example:
-
id: 1
name: 'Álvaro Obregón'
code: '010'
-
id: 2
name: Cuauhtémoc
code: '015'
items:
type: object
properties:
id:
type: integer
example: 1
name:
type: string
example: 'Álvaro Obregón'
code:
type: string
example: '010'
404:
description: 'State not found'
content:
application/json:
schema:
type: object
example:
message: "State with code '99' not found."
properties:
message:
type: string
example: "State with code '99' not found."
tags:
- 'States & Municipalities'
parameters:
-
in: path
name: code
description: 'The 2-digit INEGI state code (e.g. "09", "14").'
example: '09'
required: true
schema:
type: string
'/api/v1/states/{id}/municipalities':
get:
summary: 'List municipalities for a state'
operationId: listMunicipalitiesForAState
description: 'Returns all municipalities (municipios) that belong to the given state, ordered alphabetically.'
parameters: []
responses:
200:
description: Success
content:
application/json:
schema:
type: object
example:
data:
-
id: 1
name: 'Álvaro Obregón'
code: '010'
-
id: 2
name: Cuauhtémoc
code: '015'
properties:
data:
type: array
example:
-
id: 1
name: 'Álvaro Obregón'
code: '010'
-
id: 2
name: Cuauhtémoc
code: '015'
items:
type: object
properties:
id:
type: integer
example: 1
name:
type: string
example: 'Álvaro Obregón'
code:
type: string
example: '010'
404:
description: 'State not found'
content:
application/json:
schema:
type: object
example:
message: 'State with id 999 not found.'
properties:
message:
type: string
example: 'State with id 999 not found.'
tags:
- 'States & Municipalities'
parameters:
-
in: path
name: id
description: 'The numeric ID of the state (use `GET /api/v1/states` to find IDs).'
example: 1
required: true
schema:
type: integer
'/api/v1/states/{id}/cities':
get:
summary: 'List cities for a state'
operationId: listCitiesForAState
description: 'Returns all cities (ciudades) that belong to the given state, ordered alphabetically.'
parameters: []
responses:
200:
description: Success
content:
application/json:
schema:
type: object
example:
data:
-
id: 1
name: Aguascalientes
-
id: 2
name: Calvillo
properties:
data:
type: array
example:
-
id: 1
name: Aguascalientes
-
id: 2
name: Calvillo
items:
type: object
properties:
id:
type: integer
example: 1
name:
type: string
example: Aguascalientes
404:
description: 'State not found'
content:
application/json:
schema:
type: object
example:
message: 'State with id 999 not found.'
properties:
message:
type: string
example: 'State with id 999 not found.'
tags:
- 'States & Municipalities'
parameters:
-
in: path
name: id
description: 'The numeric ID of the state (use `GET /api/v1/states` to find IDs).'
example: 1
required: true
schema:
type: integer
'/api/v1/states/{id}/postal-codes':
get:
summary: 'List postal codes for a state'
operationId: listPostalCodesForAState
description: 'Returns all postal codes that belong to the given state, ordered by code and paginated.'
parameters: []
responses:
200:
description: Success
content:
application/json:
schema:
type: object
example:
data:
-
id: 1
code: '01000'
state:
id: 1
name: Aguascalientes
municipality:
id: 1
name: Aguascalientes
city:
id: 1
name: Aguascalientes
properties:
data:
type: array
example:
-
id: 1
code: '01000'
state:
id: 1
name: Aguascalientes
municipality:
id: 1
name: Aguascalientes
city:
id: 1
name: Aguascalientes
items:
type: object
properties:
id:
type: integer
example: 1
code:
type: string
example: '01000'
state:
type: object
properties:
id:
type: integer
example: 1
name:
type: string
example: Aguascalientes
municipality:
type: object
properties:
id:
type: integer
example: 1
name:
type: string
example: Aguascalientes
city:
type: object
properties:
id:
type: integer
example: 1
name:
type: string
example: Aguascalientes
404:
description: 'State not found'
content:
application/json:
schema:
type: object
example:
message: 'State with id 999 not found.'
properties:
message:
type: string
example: 'State with id 999 not found.'
tags:
- 'States & Municipalities'
parameters:
-
in: path
name: id
description: 'The numeric ID of the state (use `GET /api/v1/states` to find IDs).'
example: 1
required: true
schema:
type: integer
'/api/v1/states/{id}/municipalities/{mid}/settlements':
get:
summary: 'List settlements for a municipality within a state'
operationId: listSettlementsForAMunicipalityWithinAState
description: "Returns all settlements that belong to the given municipality within the given state,\nordered alphabetically by name and paginated with 20 results per page."
parameters: []
responses:
200:
description: Success
content:
application/json:
schema:
type: object
example:
data:
-
id: 1
name: Centro
zone: Urbano
settlement_type:
id: 1
name: Colonia
postal_code:
id: 1
code: '06600'
links: { }
meta:
current_page: 1
per_page: 20
total: 1
properties:
data:
type: array
example:
-
id: 1
name: Centro
zone: Urbano
settlement_type:
id: 1
name: Colonia
postal_code:
id: 1
code: '06600'
items:
type: object
properties:
id:
type: integer
example: 1
name:
type: string
example: Centro
zone:
type: string
example: Urbano
settlement_type:
type: object
properties:
id:
type: integer
example: 1
name:
type: string
example: Colonia
postal_code:
type: object
properties:
id:
type: integer
example: 1
code:
type: string
example: '06600'
links:
type: object
properties: { }
meta:
type: object
properties:
current_page:
type: integer
example: 1
per_page:
type: integer
example: 20
total:
type: integer
example: 1
404:
description: ''
content:
application/json:
schema:
oneOf:
-
description: 'State not found'
type: object
example:
message: 'State with id 999 not found.'
properties:
message:
type: string
example: 'State with id 999 not found.'
-
description: 'Municipality not found'
type: object
example:
message: 'Municipality with id 999 not found.'
properties:
message:
type: string
example: 'Municipality with id 999 not found.'
tags:
- 'States & Municipalities'
parameters:
-
in: path
name: id
description: 'The numeric ID of the state.'
example: 1
required: true
schema:
type: integer
-
in: path
name: mid
description: 'The numeric ID of the municipality.'
example: 1
required: true
schema:
type: integer
'/api/v1/municipalities/{id}/postal-codes':
get:
summary: 'List postal codes for a municipality'
operationId: listPostalCodesForAMunicipality
description: "Returns all postal codes that belong to the given municipality, ordered by code\nand paginated with 20 results per page."
parameters: []
responses:
200:
description: Success
content:
application/json:
schema:
type: object
example:
data:
-
id: 1
code: '06600'
state:
id: 1
name: 'Ciudad de México'
code: '09'
municipality:
id: 2
name: Cuauhtémoc
code: '015'
city:
id: 1
name: 'Ciudad de México'
links: { }
meta:
current_page: 1
per_page: 20
total: 1
properties:
data:
type: array
example:
-
id: 1
code: '06600'
state:
id: 1
name: 'Ciudad de México'
code: '09'
municipality:
id: 2
name: Cuauhtémoc
code: '015'
city:
id: 1
name: 'Ciudad de México'
items:
type: object
properties:
id:
type: integer
example: 1
code:
type: string
example: '06600'
state:
type: object
properties:
id:
type: integer
example: 1
name:
type: string
example: 'Ciudad de México'
code:
type: string
example: '09'
municipality:
type: object
properties:
id:
type: integer
example: 2
name:
type: string
example: Cuauhtémoc
code:
type: string
example: '015'
city:
type: object
properties:
id:
type: integer
example: 1
name:
type: string
example: 'Ciudad de México'
links:
type: object
properties: { }
meta:
type: object
properties:
current_page:
type: integer
example: 1
per_page:
type: integer
example: 20
total:
type: integer
example: 1
404:
description: 'Municipality not found'
content:
application/json:
schema:
type: object
example:
message: 'Municipality with id 999 not found.'
properties:
message:
type: string
example: 'Municipality with id 999 not found.'
tags:
- Municipalities
parameters:
-
in: path
name: id
description: 'The numeric ID of the municipality.'
example: 1
required: true
schema:
type: integer
'/api/v1/municipalities/{id}/settlements':
get:
summary: 'List settlements for a municipality'
operationId: listSettlementsForAMunicipality
description: "Returns all settlements that belong to the given municipality (via their postal codes),\nordered alphabetically by name and paginated with 20 results per page."
parameters: []
responses:
200:
description: Success
content:
application/json:
schema:
type: object
example:
data:
-
id: 1
name: Centro
zone: Urbano
settlement_type:
id: 1
name: Colonia
postal_code:
id: 1
code: '06600'
links: { }
meta:
current_page: 1
per_page: 20
total: 1
properties:
data:
type: array
example:
-
id: 1
name: Centro
zone: Urbano
settlement_type:
id: 1
name: Colonia
postal_code:
id: 1
code: '06600'
items:
type: object
properties:
id:
type: integer
example: 1
name:
type: string
example: Centro
zone:
type: string
example: Urbano
settlement_type:
type: object
properties:
id:
type: integer
example: 1
name:
type: string
example: Colonia
postal_code:
type: object
properties:
id:
type: integer
example: 1
code:
type: string
example: '06600'
links:
type: object
properties: { }
meta:
type: object
properties:
current_page:
type: integer
example: 1
per_page:
type: integer
example: 20
total:
type: integer
example: 1
404:
description: 'Municipality not found'
content:
application/json:
schema:
type: object
example:
message: 'Municipality with id 999 not found.'
properties:
message:
type: string
example: 'Municipality with id 999 not found.'
tags:
- Municipalities
parameters:
-
in: path
name: id
description: 'The numeric ID of the municipality.'
example: 1
required: true
schema:
type: integer
/api/v1/localities:
get:
summary: 'Search localities'
operationId: searchLocalities
description: "Search for localities within a state and municipality. Supports two filter modes:\nby name (`state` + `municipality`) with fuzzy matching, or by INEGI code\n(`state_code` + `municipality_code`) with exact matching. Returns paginated results\nordered by name."
parameters:
-
in: query
name: state
description: 'State name (fuzzy match). Required if not using codes.'
example: Jalisco
required: false
schema:
type: string
description: 'State name (fuzzy match). Required if not using codes.'
example: Jalisco
-
in: query
name: municipality
description: 'Municipality name (fuzzy match). Required if not using codes.'
example: Guadalajara
required: false
schema:
type: string
description: 'Municipality name (fuzzy match). Required if not using codes.'
example: Guadalajara
-
in: query
name: state_code
description: 'INEGI state code. Required if not using names.'
example: '14'
required: false
schema:
type: string
description: 'INEGI state code. Required if not using names.'
example: '14'
-
in: query
name: municipality_code
description: 'INEGI municipality code. Required if not using names.'
example: '039'
required: false
schema:
type: string
description: 'INEGI municipality code. Required if not using names.'
example: '039'
-
in: query
name: page
description: 'Page number (20 results per page).'
example: 1
required: false
schema:
type: integer
description: 'Page number (20 results per page).'
example: 1
responses:
200:
description: Results
content:
application/json:
schema:
type: object
example:
data:
-
id: 1
locality_code: '0001'
name: Guadalajara
ambito: Urbano
latitude: '20.6737800'
longitude: '-103.3442300'
altitude: '1566'
state:
id: 1
name: Jalisco
code: '14'
municipality:
id: 2
name: Guadalajara
code: '039'
links:
first: ...
last: ...
prev: null
next: null
meta:
current_page: 1
total: 1
per_page: 20
properties:
data:
type: array
example:
-
id: 1
locality_code: '0001'
name: Guadalajara
ambito: Urbano
latitude: '20.6737800'
longitude: '-103.3442300'
altitude: '1566'
state:
id: 1
name: Jalisco
code: '14'
municipality:
id: 2
name: Guadalajara
code: '039'
items:
type: object
properties:
id:
type: integer
example: 1
locality_code:
type: string
example: '0001'
name:
type: string
example: Guadalajara
ambito:
type: string
example: Urbano
latitude:
type: string
example: '20.6737800'
longitude:
type: string
example: '-103.3442300'
altitude:
type: string
example: '1566'
state:
type: object
properties:
id:
type: integer
example: 1
name:
type: string
example: Jalisco
code:
type: string
example: '14'
municipality:
type: object
properties:
id:
type: integer
example: 2
name:
type: string
example: Guadalajara
code:
type: string
example: '039'
links:
type: object
properties:
first:
type: string
example: ...
last:
type: string
example: ...
prev:
type: string
example: null
nullable: true
next:
type: string
example: null
nullable: true
meta:
type: object
properties:
current_page:
type: integer
example: 1
total:
type: integer
example: 1
per_page:
type: integer
example: 20
401:
description: Unauthenticated
content:
application/json:
schema:
type: object
example:
error: Unauthenticated
message: 'A valid API key is required. Pass it as: Authorization: Bearer {token}'
properties:
error:
type: string
example: Unauthenticated
message:
type: string
example: 'A valid API key is required. Pass it as: Authorization: Bearer {token}'
422:
description: 'Missing filter pair'
content:
application/json:
schema:
type: object
example:
message: 'The given data was invalid.'
errors:
filter:
- 'You must provide either (state and municipality) or (state_code and municipality_code).'
properties:
message:
type: string
example: 'The given data was invalid.'
errors:
type: object
properties:
filter:
type: array
example:
- 'You must provide either (state and municipality) or (state_code and municipality_code).'
items:
type: string
429:
description: 'Rate limited'
content:
application/json:
schema:
type: object
example:
error: 'Too Many Requests'
message: 'Rate limit exceeded. You are allowed 1 000 requests per hour.'
retry_after: 1800
properties:
error:
type: string
example: 'Too Many Requests'
message:
type: string
example: 'Rate limit exceeded. You are allowed 1 000 requests per hour.'
retry_after:
type: integer
example: 1800
tags:
- Localities
requestBody:
required: false
content:
application/json:
schema:
type: object
properties:
state:
type: string
description: 'Must be at least 1 character.'
example: bngzmiyvdljnikhw
nullable: true
municipality:
type: string
description: 'Must be at least 1 character.'
example: aykcmyuwpwlvqwrs
nullable: true
state_code:
type: string
description: 'Must be at least 1 character.'
example: itcpscqldzsnrwtu
nullable: true
municipality_code:
type: string
description: 'Must be at least 1 character.'
example: jwvlxjklqppwqbew
nullable: true
'/api/v1/localities/{id}':
get:
summary: 'Get a locality'
operationId: getALocality
description: 'Retrieve a single locality by its ID, including state and municipality details.'
parameters: []
responses:
200:
description: Found
content:
application/json:
schema:
type: object
example:
data:
id: 1
locality_code: '0001'
name: Guadalajara
ambito: Urbano
latitude: '20.6737800'
longitude: '-103.3442300'
altitude: '1566'
state:
id: 1
name: Jalisco
code: '14'
municipality:
id: 2
name: Guadalajara
code: '039'
properties:
data:
type: object
properties:
id:
type: integer
example: 1
locality_code:
type: string
example: '0001'
name:
type: string
example: Guadalajara
ambito:
type: string
example: Urbano
latitude:
type: string
example: '20.6737800'
longitude:
type: string
example: '-103.3442300'
altitude:
type: string
example: '1566'
state:
type: object
properties:
id:
type: integer
example: 1
name:
type: string
example: Jalisco
code:
type: string
example: '14'
municipality:
type: object
properties:
id:
type: integer
example: 2
name:
type: string
example: Guadalajara
code:
type: string
example: '039'
401:
description: Unauthenticated
content:
application/json:
schema:
type: object
example:
error: Unauthenticated
message: 'A valid API key is required. Pass it as: Authorization: Bearer {token}'
properties:
error:
type: string
example: Unauthenticated
message:
type: string
example: 'A valid API key is required. Pass it as: Authorization: Bearer {token}'
404:
description: 'Not found'
content:
application/json:
schema:
type: object
example:
message: 'Locality with id 99999 not found.'
properties:
message:
type: string
example: 'Locality with id 99999 not found.'
429:
description: 'Rate limited'
content:
application/json:
schema:
type: object
example:
error: 'Too Many Requests'
message: 'Rate limit exceeded. You are allowed 1 000 requests per hour.'
retry_after: 1800
properties:
error:
type: string
example: 'Too Many Requests'
message:
type: string
example: 'Rate limit exceeded. You are allowed 1 000 requests per hour.'
retry_after:
type: integer
example: 1800
tags:
- Localities
parameters:
-
in: path
name: id
description: 'The locality ID.'
example: 1
required: true
schema:
type: integer
/api/v1/streets:
get:
summary: 'Search streets'
operationId: searchStreets
description: "Search for streets within a state and municipality. Optionally filter by locality and\nstreet name. Returns paginated results ordered by name."
parameters:
-
in: query
name: state_code
description: 'The INEGI state code.'
example: '09'
required: true
schema:
type: string
description: 'The INEGI state code.'
example: '09'
-
in: query
name: municipality_code
description: 'The INEGI municipality code.'
example: '015'
required: true
schema:
type: string
description: 'The INEGI municipality code.'
example: '015'
-
in: query
name: locality_code
description: 'Optional INEGI locality code to narrow results.'
example: '0001'
required: false
schema:
type: string
description: 'Optional INEGI locality code to narrow results.'
example: '0001'
-
in: query
name: q
description: 'Optional street name search (partial match).'
example: Reforma
required: false
schema:
type: string
description: 'Optional street name search (partial match).'
example: Reforma
-
in: query
name: limit
description: 'Results per page (max 100, default 50).'
example: 20
required: false
schema:
type: integer
description: 'Results per page (max 100, default 50).'
example: 20
-
in: query
name: page
description: 'Page number.'
example: 1
required: false
schema:
type: integer
description: 'Page number.'
example: 1
responses:
200:
description: Results
content:
application/json:
schema:
type: object
example:
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: 2
name: Cuauhtémoc
code: '015'
links:
first: ...
last: ...
prev: null
next: null
meta:
current_page: 1
total: 1
per_page: 20
properties:
data:
type: array
example:
-
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: 2
name: Cuauhtémoc
code: '015'
items:
type: object
properties:
id:
type: integer
example: 1
name:
type: string
example: Reforma
code:
type: string
example: '0001'
ambito:
type: string
example: Urbano
street_type:
type: object
properties:
id:
type: integer
example: 1
name:
type: string
example: Avenida
code:
type: string
example: '01'
state:
type: object
properties:
id:
type: integer
example: 1
name:
type: string
example: 'Ciudad de México'
code:
type: string
example: '09'
municipality:
type: object
properties:
id:
type: integer
example: 2
name:
type: string
example: Cuauhtémoc
code:
type: string
example: '015'
links:
type: object
properties:
first:
type: string
example: ...
last:
type: string
example: ...
prev:
type: string
example: null
nullable: true
next:
type: string
example: null
nullable: true
meta:
type: object
properties:
current_page:
type: integer
example: 1
total:
type: integer
example: 1
per_page:
type: integer
example: 20
401:
description: Unauthenticated
content:
application/json:
schema:
type: object
example:
error: Unauthenticated
message: 'A valid API key is required. Pass it as: Authorization: Bearer {token}'
properties:
error:
type: string
example: Unauthenticated
message:
type: string
example: 'A valid API key is required. Pass it as: Authorization: Bearer {token}'
422:
description: 'Missing required params'
content:
application/json:
schema:
type: object
example:
message: 'The given data was invalid.'
errors:
state_code:
- 'The "state_code" query parameter is required.'
properties:
message:
type: string
example: 'The given data was invalid.'
errors:
type: object
properties:
state_code:
type: array
example:
- 'The "state_code" query parameter is required.'
items:
type: string
429:
description: 'Rate limited'
content:
application/json:
schema:
type: object
example:
error: 'Too Many Requests'
message: 'Rate limit exceeded. You are allowed 1 000 requests per hour.'
retry_after: 1800
properties:
error:
type: string
example: 'Too Many Requests'
message:
type: string
example: 'Rate limit exceeded. You are allowed 1 000 requests per hour.'
retry_after:
type: integer
example: 1800
tags:
- Streets
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
state_code:
type: string
description: 'Must be at least 1 character.'
example: bngzmiyvdljnikhw
municipality_code:
type: string
description: 'Must be at least 1 character.'
example: aykcmyuwpwlvqwrs
locality_code:
type: string
description: 'Must be at least 1 character.'
example: itcpscqldzsnrwtu
nullable: true
q:
type: string
description: 'Must be at least 1 character.'
example: jwvlxjklqppwqbew
nullable: true
limit:
type: integer
description: 'Must be at least 1. Must not be greater than 100.'
example: 6
nullable: true
required:
- state_code
- municipality_code
/api/v1/street-types:
get:
summary: 'List street types'
operationId: listStreetTypes
description: "Retrieve the full catalog of street types (e.g. Avenida, Calle, Boulevard).\nReturns all types ordered by name."
parameters: []
responses:
200:
description: Success
content:
application/json:
schema:
type: object
example:
data:
-
id: 1
name: Avenida
code: '01'
-
id: 2
name: Boulevard
code: '02'
-
id: 3
name: Calle
code: '03'
properties:
data:
type: array
example:
-
id: 1
name: Avenida
code: '01'
-
id: 2
name: Boulevard
code: '02'
-
id: 3
name: Calle
code: '03'
items:
type: object
properties:
id:
type: integer
example: 1
name:
type: string
example: Avenida
code:
type: string
example: '01'
401:
description: Unauthenticated
content:
application/json:
schema:
type: object
example:
error: Unauthenticated
message: 'A valid API key is required. Pass it as: Authorization: Bearer {token}'
properties:
error:
type: string
example: Unauthenticated
message:
type: string
example: 'A valid API key is required. Pass it as: Authorization: Bearer {token}'
429:
description: 'Rate limited'
content:
application/json:
schema:
type: object
example:
error: 'Too Many Requests'
message: 'Rate limit exceeded. You are allowed 1 000 requests per hour.'
retry_after: 1800
properties:
error:
type: string
example: 'Too Many Requests'
message:
type: string
example: 'Rate limit exceeded. You are allowed 1 000 requests per hour.'
retry_after:
type: integer
example: 1800
tags:
- Streets
/api/v1/geocode/reverse:
get:
summary: 'Reverse geocode'
operationId: reverseGeocode
description: 'Find the nearest postal code to the given latitude and longitude coordinates.'
parameters:
-
in: query
name: lat
description: 'Latitude (-90 to 90).'
example: 19.4233
required: true
schema:
type: number
description: 'Latitude (-90 to 90).'
example: 19.4233
-
in: query
name: lng
description: 'Longitude (-180 to 180).'
example: -99.1637
required: true
schema:
type: number
description: 'Longitude (-180 to 180).'
example: -99.1637
responses:
200:
description: Found
content:
application/json:
schema:
type: object
example:
data:
id: 3
code: '06600'
state:
id: 1
name: 'Ciudad de Mexico'
code: '09'
municipality:
id: 2
name: Cuauhtemoc
code: '015'
city: null
settlements: []
latitude: '19.4233000'
longitude: '-99.1637000'
properties:
data:
type: object
properties:
id:
type: integer
example: 3
code:
type: string
example: '06600'
state:
type: object
properties:
id:
type: integer
example: 1
name:
type: string
example: 'Ciudad de Mexico'
code:
type: string
example: '09'
municipality:
type: object
properties:
id:
type: integer
example: 2
name:
type: string
example: Cuauhtemoc
code:
type: string
example: '015'
city:
type: string
example: null
nullable: true
settlements:
type: array
example: []
latitude:
type: string
example: '19.4233000'
longitude:
type: string
example: '-99.1637000'
401:
description: Unauthenticated
content:
application/json:
schema:
type: object
example:
error: Unauthenticated
message: 'A valid API key is required.'
properties:
error:
type: string
example: Unauthenticated
message:
type: string
example: 'A valid API key is required.'
404:
description: 'No results'
content:
application/json:
schema:
type: object
example:
message: 'No geocoded postal codes found near the given coordinates.'
properties:
message:
type: string
example: 'No geocoded postal codes found near the given coordinates.'
422:
description: 'Invalid params'
content:
application/json:
schema:
type: object
example:
message: 'The given data was invalid.'
errors:
lat:
- 'The lat field is required.'
lng:
- 'The lng field is required.'
properties:
message:
type: string
example: 'The given data was invalid.'
errors:
type: object
properties:
lat:
type: array
example:
- 'The lat field is required.'
items:
type: string
lng:
type: array
example:
- 'The lng field is required.'
items:
type: string
tags:
- Geocoding
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
lat:
type: number
description: 'Must be between -90 and 90.'
example: -89
lng:
type: number
description: 'Must be between -180 and 180.'
example: -179
required:
- lat
- lng
/api/v1/account/usage:
get:
summary: 'Get account usage'
operationId: getAccountUsage
description: "Retrieve the authenticated user's current plan, monthly request limit,\nusage count, and remaining requests for the current billing period."
parameters: []
responses:
200:
description: Success
content:
application/json:
schema:
type: object
example:
data:
plan: free
monthly_limit: 100
usage_count: 42
remaining: 58
period: 2026-04
properties:
data:
type: object
properties:
plan:
type: string
example: free
monthly_limit:
type: integer
example: 100
usage_count:
type: integer
example: 42
remaining:
type: integer
example: 58
period:
type: string
example: 2026-04
401:
description: Unauthenticated
content:
application/json:
schema:
type: object
example:
error: Unauthenticated
message: 'A valid API key is required. Pass it as: Authorization: Bearer {token}'
properties:
error:
type: string
example: Unauthenticated
message:
type: string
example: 'A valid API key is required. Pass it as: Authorization: Bearer {token}'
429:
description: 'Rate limited'
content:
application/json:
schema:
type: object
example:
error: 'Too Many Requests'
message: 'Rate limit exceeded. You are allowed 1 000 requests per hour.'
retry_after: 1800
properties:
error:
type: string
example: 'Too Many Requests'
message:
type: string
example: 'Rate limit exceeded. You are allowed 1 000 requests per hour.'
retry_after:
type: integer
example: 1800
tags:
- Account
/api/v1/account/db-version:
get:
summary: 'Get database version'
operationId: getDatabaseVersion
description: 'Retrieve the date of the last SEPOMEX database update and the current API version.'
parameters: []
responses:
200:
description: Success
content:
application/json:
schema:
type: object
example:
data:
last_updated: '2026-03-15T00:00:00.000000Z'
version: 1.0.0
properties:
data:
type: object
properties:
last_updated:
type: string
example: '2026-03-15T00:00:00.000000Z'
version:
type: string
example: 1.0.0
401:
description: Unauthenticated
content:
application/json:
schema:
type: object
example:
error: Unauthenticated
message: 'A valid API key is required. Pass it as: Authorization: Bearer {token}'
properties:
error:
type: string
example: Unauthenticated
message:
type: string
example: 'A valid API key is required. Pass it as: Authorization: Bearer {token}'
429:
description: 'Rate limited'
content:
application/json:
schema:
type: object
example:
error: 'Too Many Requests'
message: 'Rate limit exceeded. You are allowed 1 000 requests per hour.'
retry_after: 1800
properties:
error:
type: string
example: 'Too Many Requests'
message:
type: string
example: 'Rate limit exceeded. You are allowed 1 000 requests per hour.'
retry_after:
type: integer
example: 1800
tags:
- Account
'/api/demo/postal-codes/{code}':
get:
summary: 'Demo postal code lookup'
operationId: demoPostalCodeLookup
description: "Retrieve the full record for a 5-digit postal code, including state, municipality, city,\nand all settlements (colonias). No API key required. Rate limited per IP address."
parameters: []
responses:
200:
description: Found
content:
application/json:
schema:
type: object
example:
data:
id: 3
code: '06600'
state:
id: 1
name: 'Ciudad de México'
code: '09'
municipality:
id: 2
name: Cuauhtémoc
code: '015'
city:
id: 1
name: 'Ciudad de México'
settlements:
-
id: 5
name: 'Roma Sur'
zone: Urbano
settlement_type:
id: 1
name: Colonia
properties:
data:
type: object
properties:
id:
type: integer
example: 3
code:
type: string
example: '06600'
state:
type: object
properties:
id:
type: integer
example: 1
name:
type: string
example: 'Ciudad de México'
code:
type: string
example: '09'
municipality:
type: object
properties:
id:
type: integer
example: 2
name:
type: string
example: Cuauhtémoc
code:
type: string
example: '015'
city:
type: object
properties:
id:
type: integer
example: 1
name:
type: string
example: 'Ciudad de México'
settlements:
type: array
example:
-
id: 5
name: 'Roma Sur'
zone: Urbano
settlement_type:
id: 1
name: Colonia
items:
type: object
properties:
id:
type: integer
example: 5
name:
type: string
example: 'Roma Sur'
zone:
type: string
example: Urbano
settlement_type:
type: object
properties:
id:
type: integer
example: 1
name:
type: string
example: Colonia
404:
description: 'Not found'
content:
application/json:
schema:
type: object
example:
message: "Postal code '00000' not found."
properties:
message:
type: string
example: "Postal code '00000' not found."
422:
description: 'Invalid format'
content:
application/json:
schema:
type: object
example:
message: 'Postal code must be exactly 5 digits.'
properties:
message:
type: string
example: 'Postal code must be exactly 5 digits.'
429:
description: 'Demo limit reached'
content:
application/json:
schema:
type: object
example:
message: 'Demo lookup limit reached. Sign up for a free key for 100 lookups every month.'
properties:
message:
type: string
example: 'Demo lookup limit reached. Sign up for a free key for 100 lookups every month.'
tags:
- 'Try it (no key needed)'
security: []
parameters:
-
in: path
name: code
description: 'The 5-digit postal code.'
example: '06600'
required: true
schema:
type: string