https://github.com/netzulo/ine-explorer
https://github.com/netzulo/ine-explorer
Last synced: 3 months ago
JSON representation
- Host: GitHub
- URL: https://github.com/netzulo/ine-explorer
- Owner: netzulo
- License: gpl-3.0
- Created: 2026-01-23T21:21:58.000Z (5 months ago)
- Default Branch: main
- Last Pushed: 2026-01-23T21:47:53.000Z (5 months ago)
- Last Synced: 2026-01-24T10:26:05.815Z (5 months ago)
- Language: JavaScript
- Size: 45.9 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
README
# ine-scripts
CLI de scripts que replica las funciones clave del paquete R ineapir (es-ine) sobre la API JSON del INE (wstempus).
## Descripción
`ine-scripts` es una herramienta de línea de comandos Node.js ESM que proporciona acceso completo a la API JSON del Instituto Nacional de Estadística (INE) de España. Ofrece funcionalidades para:
- Gestión de operaciones, tablas y series estadísticas
- Descarga de metadatos y datos con caché, rate-limiting y reintentos
- Almacenamiento en SQLite con exportación a JSONL
- Normalización de datos a formato Parquet
- Detección de cambios por checksum y lastModified
- Búsqueda de texto completo (FTS) en el catálogo
## Características
### API REST del INE (wstempus)
- ✅ Operaciones estadísticas
- ✅ Tablas de operaciones
- ✅ Series temporales
- ✅ Metadatos y datos
### Parámetros soportados
- `nult`: Número de últimos elementos
- `date`: Filtro por fecha
- `det`: Nivel de detalle
- `tip`: Tipo de recurso
- `page`: Paginación
- `tv`, `g1..gN`: Filtros adicionales
### Almacenamiento y procesamiento
- 📦 **SQLite**: Base de datos local para catálogo
- 📄 **JSONL**: Exportación/importación en formato línea
- 🗂️ **Parquet**: Normalización para análisis
- 🔍 **FTS**: Búsqueda de texto completo
- 💾 **Caché**: Sistema de caché para optimizar descargas
- 🔄 **Diff**: Detección de cambios por checksum/lastModified
## Instalación
```bash
npm install
```
## Uso
### Comandos disponibles
#### Operaciones
```bash
# Listar operaciones locales
node src/cli.js operations --list
# Sincronizar operaciones desde la API
node src/cli.js operations --sync
# Obtener operación específica
node src/cli.js operations --get IPC
# Sincronizar con parámetros
node src/cli.js operations --sync --nult 10 --det 2
# Exportar a JSONL
node src/cli.js operations --list --export-jsonl operations.jsonl
# Exportar a Parquet
node src/cli.js operations --list --export-parquet operations.parquet
```
#### Tablas
```bash
# Sincronizar tablas de una operación
node src/cli.js tables --sync IPC30138
# Listar tablas de una operación
node src/cli.js tables --operation IPC30138
# Obtener tabla específica
node src/cli.js tables --get 50902
# Exportar tabla a Parquet
node src/cli.js tables --get 50902 --export-parquet tabla.parquet
```
#### Series
```bash
# Sincronizar series de una tabla
node src/cli.js series --sync 50902
# Listar series de una tabla
node src/cli.js series --table 50902
# Obtener datos de una serie
node src/cli.js series --data IPC251852
# Obtener datos con filtros
node src/cli.js series --data IPC251852 --nult 12 --tv 1 --g1 100
# Exportar serie a Parquet
node src/cli.js series --data IPC251852 --export-parquet serie.parquet
```
#### Búsqueda (FTS)
```bash
# Buscar en todo el catálogo
node src/cli.js search "precio consumo"
# Buscar solo en operaciones
node src/cli.js search "IPC" --type operations
# Buscar solo en tablas
node src/cli.js search "nacional" --type tables
# Buscar solo en series
node src/cli.js search "mensual" --type series
```
#### Detección de cambios
```bash
# Verificar cambios en una operación
node src/cli.js diff --id IPC30138 --type operation
# Verificar cambios en una tabla
node src/cli.js diff --id 50902 --type table
# Verificar cambios en una serie
node src/cli.js diff --id IPC251852 --type series
```
#### Importar/Exportar
```bash
# Exportar catálogo completo
node src/cli.js export --file catalog.jsonl
# Exportar solo operaciones
node src/cli.js export --file operations.jsonl --type operations
# Importar catálogo
node src/cli.js import --file catalog.jsonl
```
## Estructura del proyecto
```
ine-scripts/
├── src/
│ ├── api-client.js # Cliente HTTP con rate-limiting y retries
│ ├── storage.js # Gestor SQLite con FTS
│ ├── parquet-exporter.js # Exportador a formato Parquet
│ ├── cli.js # Interface de línea de comandos
│ └── index.js # Exports para uso programático
├── tests/
│ ├── api-client.test.js
│ ├── storage.test.js
│ └── parquet-exporter.test.js
├── data/ # Base de datos y caché (generado)
│ ├── catalog.db
│ └── cache/
├── .github/
│ └── workflows/
│ └── ci.yml # GitHub Actions CI
├── package.json
├── eslint.config.js
└── README.md
```
## API Programática
También puedes usar `ine-scripts` como biblioteca:
```javascript
import { INEApiClient, StorageManager, ParquetExporter } from './src/index.js';
// Cliente API
const client = new INEApiClient({
retries: 3,
rateLimit: 10,
rateLimitInterval: 1000
});
const operations = await client.getOperations({ nult: 5 });
// Almacenamiento
const storage = new StorageManager({
dbPath: './data/catalog.db',
cachePath: './data/cache'
});
await storage.init();
await storage.saveOperation(operations[0]);
// Exportar a Parquet
const exporter = new ParquetExporter({
outputDir: './data/parquet'
});
await exporter.exportSeries(seriesData, 'output.parquet');
```
### Runner del ejemplo
Para ejecutar el ejemplo anterior sin copiar código ni configurar nada adicional, usa el runner incluido:
```bash
npm run example
```
Este comando ejecuta el script de ejemplo en [examples/programmatic-runner.js](examples/programmatic-runner.js), crea/actualiza la base de datos en [data/catalog.db](data/catalog.db) y exporta un archivo Parquet en [data/parquet/example-series.parquet](data/parquet/example-series.parquet).
## Desarrollo
### Ejecutar tests
```bash
npm test
```
### Ejecutar linter
```bash
npm run lint
npm run lint:fix
```
### Estructura de datos
La base de datos SQLite incluye:
- **operations**: Operaciones estadísticas del INE
- **tables**: Tablas asociadas a operaciones
- **series**: Series temporales asociadas a tablas
- ***_fts**: Tablas FTS5 para búsqueda de texto completo
Cada tabla incluye:
- `id`: Identificador único
- `code`: Código del recurso
- `name`: Nombre descriptivo
- `metadata`: JSON con metadatos completos
- `checksum`: SHA-256 para detección de cambios
- `last_modified`: Fecha de última modificación
- `created_at`, `updated_at`: Timestamps
## Dependencias principales
- **better-sqlite3**: Base de datos SQLite con soporte FTS5
- **commander**: Parser de CLI
- **p-retry**: Reintentos con backoff exponencial
- **p-throttle**: Rate limiting
- **parquetjs**: Lectura/escritura de archivos Parquet
## Compatibilidad
- Node.js >= 18.0.0
- ESM (ECMAScript Modules)
## Licencia
MIT
## Referencias
- [API INE wstempus](https://www.ine.es/dyngs/DataLab/manual.html?cid=45)
- [Paquete R ineapir](https://github.com/oddworldng/ineapir)
## Contribuir
Las contribuciones son bienvenidas. Por favor:
1. Fork el proyecto
2. Crea una rama para tu feature (`git checkout -b feature/amazing-feature`)
3. Commit tus cambios (`git commit -m 'Add amazing feature'`)
4. Push a la rama (`git push origin feature/amazing-feature`)
5. Abre un Pull Request
## Soporte
Para reportar bugs o solicitar features, por favor abre un issue en GitHub.