Ir al contenido

Ubigeos

Catálogo de ubigeos del INEI (≈ 1 900 distritos). Sirve para normalizar direcciones, validar fichas y enriquecer datos de RUC con su distrito real.

Endpoints

Método y ruta	Descripción
`GET /v1/ubigeos`	Listado paginado con filtros opcionales
`GET /v1/ubigeos/{code}`	Lookup directo por código de 6 dígitos


Scope requerido	`ubigeos:read`
Cuota	1 unidad por request
Cache HTTP	`public, max-age=2592000, immutable` (30 días)

Estructura del código ubigeo

El código de 6 dígitos sigue el formato DDPPDD:

Posición	Significado	Ejemplo
1-2	Código de departamento	`15` = Lima
3-4	Código de provincia	`01` = Lima
5-6	Código de distrito	`01` = Lima (Cercado)

Ejemplo completo: 150101 = Lima / Lima / Lima Cercado.

Listar ubigeos

GET /v1/ubigeos?q=miraflores&limit=10

Query parameters

Nombre	Tipo	Validación	Default
`q`	string	2-80 caracteres	—
`departamento`	string	2 dígitos	—
`provincia`	string	4 dígitos	—
`limit`	number	1-200	50
`cursor`	string	6 dígitos (ubigeo del último resultado)	—

Ejemplo de request

curl --request GET \
  --url 'https://api.chequea.pe/api/v1/ubigeos?departamento=15&provincia=1501&limit=5' \
  --header 'Authorization: Bearer ak_live_TU_CLAVE'

Respuesta `200 OK`

{
  "items": [
    {
      "code": "150101",
      "departamento": "LIMA",
      "provincia": "LIMA",
      "distrito": "LIMA",
      "departamentoCode": "15",
      "provinciaCode": "1501"
    },
    {
      "code": "150102",
      "departamento": "LIMA",
      "provincia": "LIMA",
      "distrito": "ANCON",
      "departamentoCode": "15",
      "provinciaCode": "1501"
    }
  ],
  "nextCursor": "150103"
}

Paginación

nextCursor es el código del último ítem devuelto. Para la siguiente página, envíalo en ?cursor=. Cuando nextCursor es null, no hay más resultados.

Consultar ubigeo por código

GET /v1/ubigeos/150101

Respuesta `200 OK`

{
  "code": "150101",
  "departamento": "LIMA",
  "provincia": "LIMA",
  "distrito": "LIMA",
  "departamentoCode": "15",
  "provinciaCode": "1501"
}

Errores comunes

Código	`type`	Cuándo ocurre
`400`	`validation_error`	Código mal formado, query inválida o cursor corrupto
`401`	`unauthorized`	Falta clave o es inválida
`403`	`forbidden_scope`	La clave no tiene `ubigeos:read`
`404`	`not_found`	El código no existe en el catálogo INEI
`429`	`rate_limited` / `quota_exceeded`	Plan excedido

Probar en el playground Ejecuta listados y lookups contra tu clave.