API REST · Gratuita · Sin autenticación

Ubigeo Perú API

Consulta la división político-administrativa del Perú en tiempo real. Accede a los 25 departamentos, 196 provincias y 1 874 distritos del país con una simple petición HTTP.

Base URL

https://kmoxd00ic1.execute-api.us-east-1.amazonaws.com

25

Departamentos

196

Provincias

1 874

Distritos

0

Auth requerida

Ejemplo rápido

bash

# Obtener todos los departamentos
curl "https://kmoxd00ic1.execute-api.us-east-1.amazonaws.com/departamentos"

# Buscar por nombre
curl "https://kmoxd00ic1.execute-api.us-east-1.amazonaws.com/buscar?q=miraflores"

GET /departamentos

Listar todos los departamentos

Retorna la lista completa de los 25 departamentos del Perú, ordenados por código.

URL completa https://kmoxd00ic1.execute-api.us-east-1.amazonaws.com/departamentos

Autenticación Ninguna

Probar endpoint

GET

https://kmoxd00ic1.execute-api.us-east-1.amazonaws.com/departamentos

Ejemplo de respuesta · 200 OK

[
  { "codigo": "01", "nombre": "AMAZONAS"  },
  { "codigo": "02", "nombre": "ANCASH"    },
  { "codigo": "03", "nombre": "APURIMAC"  },
  { "codigo": "15", "nombre": "LIMA"      },
  // ... 25 departamentos en total
]

Campos de la respuesta

Campo	Tipo	Descripción
`codigo`	string	Código del departamento (2 dígitos)
`nombre`	string	Nombre oficial del departamento en mayúsculas

GET /departamentos/{code}

Obtener departamento por código

Retorna la información detallada de un departamento junto con la lista de sus provincias.

Parámetros de ruta

Parámetro	Tipo	Requerido	Descripción
`code`	string	Sí	Código de 2 dígitos. Ej: `15` para Lima

Probar endpoint

code requerido Código de 2 dígitos — 01 a 25

GET

https://kmoxd00ic1.execute-api.us-east-1.amazonaws.com/departamentos/{code}

Ejemplo · 200 OK · code=15

{}
  "codigo": "15",
  "nombre": "LIMA",
  "provincias": [
    { "codigo": "1501", "nombre": "LIMA"      },
    { "codigo": "1502", "nombre": "BARRANCA"  },
    { "codigo": "1503", "nombre": "CAJATAMBO" },
    // ... todas las provincias del departamento
  ]
}

Error · 404 Not Found

{ "error": "Departamento '99' no encontrado" }

GET /provincias/{code}

Obtener provincia por código

Retorna la información de una provincia, su departamento padre y la lista completa de sus distritos.

Parámetros de ruta

Parámetro	Tipo	Requerido	Descripción
`code`	string	Sí	Código de 4 dígitos. Ej: `1501` para Lima

Probar endpoint

code requerido Código de 4 dígitos — primeros 2 = departamento

GET

https://kmoxd00ic1.execute-api.us-east-1.amazonaws.com/provincias/{code}

Ejemplo · 200 OK · code=1501

{}
  "codigo": "1501",
  "nombre": "LIMA",
  "departamento": { "codigo": "15", "nombre": "LIMA" },
  "distritos": [
    { "codigo": "150101", "nombre": "LIMA"       },
    { "codigo": "150102", "nombre": "ANCON"      },
    { "codigo": "150118", "nombre": "MIRAFLORES" },
    // ... todos los distritos de la provincia
  ]
}

GET /distritos/{code}

Obtener distrito por código

Retorna la información completa de un distrito: nombre, capital, región natural, provincia y departamento.

Parámetros de ruta

Parámetro	Tipo	Requerido	Descripción
`code`	string	Sí	Código de 6 dígitos. Ej: `150118` para Miraflores

Probar endpoint

code requerido Código de 6 dígitos — dep(2) + prov(2) + dist(2)

GET

https://kmoxd00ic1.execute-api.us-east-1.amazonaws.com/distritos/{code}

Ejemplo · 200 OK · code=150118

{}
  "codigo":        "150118",
  "nombre":        "MIRAFLORES",
  "capital":       "MIRAFLORES",
  "regionNatural": "COSTA",
  "provincia":    { "codigo": "1501", "nombre": "LIMA" },
  "departamento": { "codigo": "15",   "nombre": "LIMA" }
}

Campos de la respuesta

Campo	Tipo	Descripción
`codigo`	string	Código UBIGEO del distrito (6 dígitos)
`nombre`	string	Nombre oficial del distrito
`capital`	string	Nombre de la capital del distrito
`regionNatural`	string	COSTA, SIERRA o SELVA
`provincia`	object	Provincia a la que pertenece (codigo, nombre)
`departamento`	object	Departamento al que pertenece (codigo, nombre)

GET /buscar

Buscar por nombre

Búsqueda de texto libre con soporte multi-palabra (AND), insensible a tildes y mayúsculas. Devuelve el árbol completo: distrito → provincia → departamento.

Query parameters

Parámetro	Tipo	Requerido	Default	Descripción
`q`	string	Sí	—	Texto de búsqueda (mín. 2 caracteres)
`limit`	number	No	`20`	Máximo de resultados a retornar

Probar endpoint

q requerido Mínimo 2 caracteres

limit opcional Default: 20, máx: 100

GET

https://kmoxd00ic1.execute-api.us-east-1.amazonaws.com/buscar?q={q}

Ejemplo · 200 OK · q=san isidro

{}
  "query": "san isidro",
  "total": 3,
  "resultados": [
    {}
      "codigo":       "150131",
      "nombre":       "SAN ISIDRO",
      "provincia":    { "codigo": "1501", "nombre": "LIMA"     },
      "departamento": { "codigo": "15",   "nombre": "LIMA"     }
    },
    {}
      "codigo":       "040101",
      "nombre":       "SAN ISIDRO",
      "provincia":    { "codigo": "0401", "nombre": "AREQUIPA" },
      "departamento": { "codigo": "04",   "nombre": "AREQUIPA" }
    }
    // ...
  ]
}

Error · 400 Bad Request

{ "error": "El parámetro q debe tener al menos 2 caracteres" }

Códigos de respuesta

La API utiliza códigos HTTP estándar para indicar el resultado de cada petición.

200

OK

La petición fue exitosa. El cuerpo contiene los datos en formato JSON.

400

Bad Request

Parámetros inválidos. Ej: código con longitud incorrecta o query demasiado corta.

404

Not Found

El recurso solicitado no existe. Ej: código de departamento o distrito inexistente.

500

Server Error

Error interno del servidor. Intenta nuevamente en unos momentos.

Formato de error — Todos los errores retornan un JSON con el campo error: { "error": "mensaje descriptivo" }