Documentación de PuduPostal API
API sencilla y eficiente para consultar códigos postales de Chile. A continuación encontrarás toda la información necesaria para integrar PuduPostal en tus aplicaciones.
Introducción
PuduPostal es una API REST que permite la consulta de códigos postales de Chile. Está diseñada para ser sencilla y fácil de integrar en cualquier aplicación.
URL Base: https://api.pudupostal.com/v1
Rate Limit: 60 solicitudes por minuto
Endpoints
Estado de la API
GET /info
Obtiene información sobre el estado actual de la API.
Ejemplo de solicitud:
GET https://api.pudupostal.com/v1/info
Respuesta:
{
"status": "ok",
"timestamp": "2025-05-21T16:59:14.381Z",
"version": "1.0.0"
} Listado de Comunas
GET /comunas
Devuelve la lista de todas las comunas de Chile con sus respectivos IDs.
Ejemplo de solicitud:
GET https://api.pudupostal.com/v1/comunas
Respuesta:
[
{
"id": "ABO",
"nombre": "ALGARROBO"
},
{
"id": "VAH",
"nombre": "ALHUE"
},
{
"id": "LAS",
"nombre": "ALTO BIOBIO"
},
{
"id": "ADC",
"nombre": "ALTO DEL CARMEN"
},
// ... más comunas
] Uso recomendado: Este endpoint es ideal para implementar un autocompletado de comunas en formularios.
Consulta de Códigos Postales
GET /postal
Consulta el código postal de una dirección específica.
Parámetros:
| Parámetro | Tipo | Descripción |
|---|---|---|
| direccion | string | Nombre de la calle o avenida |
| comuna | string | Nombre de la comuna |
| numero | string | Número de la dirección |
Ejemplo de solicitud:
GET https://api.pudupostal.com/v1/postal?direccion=fe&comuna=recoleta&numero=5
Respuesta exitosa:
{
"calle": "PASAJE FE",
"numero": "5",
"comuna": "RECOLETA",
"codigoPostal": "8441690",
"latitud": "-33.40222351",
"longitud": "-70.63972305"
} Respuestas de error:
Parámetro número faltante:
{
"success": false,
"error": {
"issues": [
{
"code": "invalid_type",
"expected": "string",
"received": "undefined",
"path": ["numero"],
"message": "Required"
}
],
"name": "ZodError"
}
} Parámetro comuna faltante:
{
"success": false,
"error": {
"issues": [
{
"code": "invalid_type",
"expected": "string",
"received": "undefined",
"path": ["comuna"],
"message": "Required"
}
],
"name": "ZodError"
}
} Parámetro dirección faltante:
{
"success": false,
"error": {
"issues": [
{
"code": "invalid_type",
"expected": "string",
"received": "undefined",
"path": ["direccion"],
"message": "Required"
}
],
"name": "ZodError"
}
} Ejemplos de Uso
Fetch (JavaScript)
// Consulta de código postal
const fetchPostalCode = async (direccion, comuna, numero) => {
try {
const response = await fetch(
`https://api.pudupostal.com/v1/postal?direccion=${encodeURIComponent(direccion)}&comuna=${encodeURIComponent(comuna)}&numero=${encodeURIComponent(numero)}`
);
const data = await response.json();
if (!response.ok) {
throw new Error(data.error || 'Error en la consulta');
}
return data;
} catch (error) {
console.error('Error:', error);
throw error;
}
};
// Ejemplo de uso
fetchPostalCode('fe', 'recoleta', '5')
.then(data => console.log(data))
.catch(error => console.error(error)); Axios (JavaScript)
// Consulta de código postal con Axios
import axios from 'axios';
const fetchPostalCode = async (direccion, comuna, numero) => {
try {
const response = await axios.get('https://api.pudupostal.com/v1/postal', {
params: {
direccion,
comuna,
numero
}
});
return response.data;
} catch (error) {
console.error('Error:', error.response ? error.response.data : error.message);
throw error;
}
};
// Ejemplo de uso
fetchPostalCode('fe', 'recoleta', '5')
.then(data => console.log(data))
.catch(error => console.error(error));