Introducción
La API de Datastreams del Observatorio Digital proporciona acceso programático a datasets y metadatos de logística y comercio exterior de Chile. Esta API RESTful permite consultar, filtrar y obtener datos actualizados sobre el sector logístico nacional.
Características Principales
No requiere autenticación ni registro previo. Acceso inmediato para desarrollo y producción.
La API ofrece las siguientes funcionalidades clave:
Filtrado Dinámico: Filtra por cualquier campo JSON disponible en los datos usando parámetros de consulta simples.
Cache Automático: Respuestas optimizadas para mejor rendimiento y menor latencia.
Rate Limiting: Límite de 100 requests por minuto por dirección IP para garantizar disponibilidad del servicio.
CORS Habilitado: Uso directo desde navegadores web sin configuración adicional.
URL Base
https://www.observatoriologistico.cl/api/v1
Rate Limiting
100 requests por minuto por dirección IP. Ventana deslizante de 60 segundos con bloqueo temporal si se excede el límite.
Conceptos Básicos
Estructura de Respuestas
Todas las respuestas exitosas siguen una estructura JSON consistente:
{
"status": "success",
"data": [...],
"pagination": {
"page": 1,
"limit": 100,
"total": 250,
"total_pages": 3
},
"metadata": {
"timestamp": "2025-07-29T13:31:16-04:00",
"version": "1.0"
}
}
Paginación
Todos los endpoints soportan paginación mediante parámetros de consulta:
| Parámetro | Tipo | Descripción | Por Defecto |
|---|---|---|---|
| page | integer | Número de página (mínimo 1) | 1 |
| limit | integer | Elementos por página (1-100) | 100 |
Ejemplo de Paginación
GET /api/v1/datastreams/lists?page=2&limit=50
Manejo de Errores
Los errores devuelven códigos HTTP estándar con información detallada:
{
"status": "error",
"message": "Descripción del error",
"timestamp": "2025-07-29T13:31:16-04:00"
}
Filtrado Dinámico
La característica más potente de la API es su capacidad de filtrar por cualquier campo presente en los datos JSON de cada datastream.
Cómo Funciona
Simplemente usa la clave del campo JSON como parámetro de consulta, seguido de su valor. La búsqueda es case-insensitive y permite coincidencias parciales.
Patrón: ?nombre_del_campo=valor_buscado
Característica: Búsqueda parcial y sin distinción de mayúsculas/minúsculas
Ejemplos Prácticos
Filtrado por Categoría
# Buscar datastreams de logística aérea GET /api/v1/datastreams/lists?category=Logística aérea
Filtrado por Código
# Buscar datastream específico por código GET /api/v1/datastreams/lists?code=C010
Filtrado en Datos
# Filtrar datos del C010 por mes específico GET /api/v1/datastreams/C010/data?mes=Abril # Filtrar por año y categoría de bienes GET /api/v1/datastreams/C010/data?anio=2025&categoria_bienes=Bienes de capital
Combinación de Filtros
Puedes combinar múltiples filtros para búsquedas más específicas:
# Múltiples filtros dinámicos GET /api/v1/datastreams/C010/data?anio=2025&mes=Abril&tipo_bienes=Durables
Ordenamiento
Cada endpoint tiene opciones de ordenamiento específicas:
Para Lista de Datastreams
# Ordenar por título ascendente GET /api/v1/datastreams/lists?sort=title&order=ASC # Ordenar por categoría descendente GET /api/v1/datastreams/lists?sort=category&order=DESC
Para Datos y Metadatos
# Ordenar por columna específica GET /api/v1/datastreams/C010/data?sort_column=0&sort_order=DESC
Obtiene una lista paginada de todos los datastreams disponibles en el sistema con información básica y URLs para acceder a sus datos y metadatos.
Parámetros de Consulta
| Parámetro | Tipo | Descripción | Ejemplo |
|---|---|---|---|
| page | integer | Número de página | 1 |
| limit | integer | Elementos por página (1-100) | 10 |
| category | string | Filtrar por categoría | Logística aérea |
| title | string | Filtrar por título | transporte |
| code | string | Filtrar por código exacto | C010 |
| sort | string | Campo de ordenamiento | title |
| order | string | Dirección (ASC/DESC) | ASC |
Ejemplo de Solicitud
GET /api/v1/datastreams/lists?category=Logística aérea&limit=5
Respuesta Exitosa
{
"status": "success",
"data": [
{
"code": "C001",
"title": "Carga nacional transportada en modo aéreo",
"description": "Toneladas y toneladas-km totales de transporte aéreo de cabotaje, según origen y destino.",
"category": "Logística aérea",
"date_last_update": "2025-07-29T09:10:32-04:00",
"metadata_url": "/api/v1/datastreams/C001/metadata",
"data_url": "/api/v1/datastreams/C001/data"
},
{
"code": "C013",
"title": "Carga internacional transportada en modo aéreo",
"description": "Cantidad de carga y toneladas-kilómetro del transporte aéreo internacional. Desagregación anual de entradas y salidas de carga de Chile.",
"category": "Logística aérea",
"date_last_update": "2025-07-29T09:10:31-04:00",
"metadata_url": "/api/v1/datastreams/C013/metadata",
"data_url": "/api/v1/datastreams/C013/data"
}
],
"pagination": {
"page": 1,
"limit": 5,
"total": 2,
"total_pages": 1
},
"metadata": {
"timestamp": "2025-07-29T13:31:16-04:00",
"version": "1.0"
}
}
Obtiene los metadatos de un datastream específico con información sobre la estructura de datos, variables disponibles y descripciones detalladas.
Parámetros de Ruta
| Parámetro | Tipo | Descripción | Ejemplo |
|---|---|---|---|
| code | string | Código único del datastream | C010 |
Filtrado Dinámico
Los metadatos pueden filtrarse por cualquier campo presente en su estructura JSON:
# Filtrar metadatos por variable específica GET /api/v1/datastreams/C010/metadata?variable=titulo # Filtrar por descripción GET /api/v1/datastreams/C010/metadata?Descripcion=Categoría
Ejemplo de Solicitud
GET /api/v1/datastreams/C010/metadata
Respuesta Exitosa
{
"status": "success",
"data": [
{
"codigo": "C010",
"Descripcion": "ID del datastream",
"variable": "codigo"
},
{
"codigo": "C010",
"Descripcion": "Título del proceso",
"variable": "titulo"
},
{
"codigo": "C010",
"Descripcion": "Categoría temática",
"variable": "categoria"
},
{
"codigo": "C010",
"Descripcion": "Conjunto de datos",
"variable": "tipo_elemento"
}
],
"pagination": {
"page": 1,
"limit": 100,
"total": 4,
"total_pages": 1
},
"metadata": {
"timestamp": "2025-07-29T13:34:36-04:00",
"version": "1.0"
}
}
Obtiene los datos de un datastream específico con opciones avanzadas de paginación, filtrado dinámico y ordenamiento.
Parámetros de Ruta
| Parámetro | Tipo | Descripción | Ejemplo |
|---|---|---|---|
| code | string | Código único del datastream | C010 |
Parámetros de Consulta
| Parámetro | Tipo | Descripción | Ejemplo |
|---|---|---|---|
| page | integer | Número de página | 1 |
| limit | integer | Elementos por página (1-100) | 50 |
| sort_column | integer | Índice de columna para ordenar (base 0) | 0 |
| sort_order | string | Dirección de ordenamiento (ASC/DESC) | DESC |
| [campo_dinamico] | string | Cualquier campo presente en los datos | mes=Abril |
Cada datastream tiene una estructura de datos diferente. Consulta los metadatos para conocer los campos disponibles para filtrar en cada datastream específico.
Ejemplos de Solicitudes
Solicitud Básica
GET /api/v1/datastreams/C010/data?page=1&limit=50
Con Filtros Dinámicos
# Filtrar por mes específico GET /api/v1/datastreams/C010/data?mes=Abril # Múltiples filtros GET /api/v1/datastreams/C010/data?anio=2025&categoria_bienes=Bienes de capital # Con ordenamiento GET /api/v1/datastreams/C010/data?mes=Abril&sort_column=0&sort_order=DESC
Respuesta Exitosa
{
"status": "success",
"data": [
{
"anio": 2025,
"mes": "Abril",
"categoria_bienes": "Bienes de capital",
"tipo_bienes": "Vehículos, Maquinarias y Otros",
"valor_cif": 1559.3
},
{
"anio": 2025,
"mes": "Abril",
"categoria_bienes": "Bienes de consumo",
"tipo_bienes": "Durables",
"valor_cif": 689.2
},
{
"anio": 2025,
"mes": "Abril",
"categoria_bienes": "Bienes de consumo",
"tipo_bienes": "Otros bienes de consumo",
"valor_cif": 865.6
}
],
"pagination": {
"page": 1,
"limit": 50,
"total": 150,
"total_pages": 3
},
"metadata": {
"timestamp": "2025-07-29T13:34:38-04:00",
"version": "1.0"
}
}
Casos de Uso Comunes
1. Explorar Datastreams Disponibles
Obtener una vista general de todos los datasets disponibles:
# Ver todos los datastreams con información básica GET /api/v1/datastreams/lists # Filtrar por categoría específica GET /api/v1/datastreams/lists?category=Logística aérea # Buscar por palabras clave en el título GET /api/v1/datastreams/lists?title=transporte
2. Analizar Estructura de Datos
Antes de trabajar con los datos, examina la estructura:
# Obtener metadatos para entender la estructura GET /api/v1/datastreams/C010/metadata # Ver una muestra pequeña de datos GET /api/v1/datastreams/C010/data?limit=5
3. Consultas Específicas por Periodo
Filtrar datos por rangos temporales específicos:
# Datos de un año específico GET /api/v1/datastreams/C010/data?anio=2025 # Datos de un mes específico GET /api/v1/datastreams/C010/data?mes=Abril&anio=2025 # Combinar filtros temporales y categorías GET /api/v1/datastreams/C010/data?anio=2025&categoria_bienes=Bienes de capital
4. Análisis por Categorías
Segmentar datos por diferentes categorías disponibles:
# Filtrar por tipo de bien específico GET /api/v1/datastreams/C010/data?tipo_bienes=Durables # Buscar categorías específicas GET /api/v1/datastreams/C010/data?categoria_bienes=Bienes de consumo
5. Paginación Eficiente
Manejar grandes volúmenes de datos con paginación:
# Procesar datos en lotes de 100 GET /api/v1/datastreams/C010/data?limit=100&page=1 GET /api/v1/datastreams/C010/data?limit=100&page=2 # Lotes más pequeños para procesamiento rápido GET /api/v1/datastreams/C010/data?limit=25&page=1
6. Ordenamiento de Resultados
Ordenar datos para análisis específicos:
# Ordenar datastreams por fecha de actualización GET /api/v1/datastreams/lists?sort=fecha_ultima_actualizacion&order=DESC # Ordenar datos por columna específica GET /api/v1/datastreams/C010/data?sort_column=4&sort_order=DESC
Códigos de Respuesta HTTP
Respuestas Exitosas
La solicitud se procesó correctamente y se devolvieron los datos solicitados.
Errores del Cliente
El código de datastream especificado no existe en el sistema.
{
"status": "error",
"message": "Datastream not found",
"timestamp": "2025-07-29T13:31:16-04:00"
}
Errores de Rate Limiting
Se ha excedido el límite de 100 requests por minuto. La respuesta incluye el header Retry-After indicando cuándo se puede hacer la siguiente solicitud.
Headers:
Retry-After: 60
Body:
{
"status": "error",
"message": "Rate limit exceeded. Try again later.",
"timestamp": "2025-07-29T13:31:16-04:00"
}
Errores del Servidor
Error interno del servidor. Si persiste, contacta al equipo de soporte.
{
"status": "error",
"message": "Internal server error",
"timestamp": "2025-07-29T13:31:16-04:00"
}
Manejo de Errores Recomendado
Para implementar manejo robusto de errores, considera implementar reintentos automáticos con backoff exponencial para errores 429 y 500, y siempre verifica el código de estado HTTP antes de procesar la respuesta JSON.