Metadata-Version: 2.3
Name: bdeapi
Version: 0.1.0
Summary: Cliente Python no oficial para la API REST pública de Estadísticas del Banco de España
Author: Jon Aldekoa
Author-email: Jon Aldekoa <jaldekoa@gmail.com>
Requires-Dist: pandas>=3.0.5
Requires-Dist: requests>=2.34.2
Requires-Python: >=3.10
Description-Content-Type: text/markdown

# bdeapi

[![Python Version](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/)
[![License: GPL v3](https://img.shields.io/badge/License-GPLv3-blue.svg)](https://www.gnu.org/licenses/gpl-3.0)

Cliente en Python ligero y con tipos anotados para consultar de forma sencilla el **Servicio Web de Estadísticas (API REST JSON)** del **Banco de España (BdE / BIEST)**.

Transforma automáticamente las respuestas en formato JSON en DataFrames de **Pandas** listos para análisis financiero, econométrico y estadístico.

> [!WARNING]
> `bdeapi` es una librería de código abierto independiente desarrollada por la comunidad y **no tiene ninguna relación, afiliación, patrocinio ni respaldo oficial del Banco de España**.

---

## Características

* **Interfaz Pythonic:** Utiliza argumentos descriptivos en Python (`listado_series`, `rango_temporal`, etc.) que el cliente traduce automáticamente a los parámetros requeridos por la API HTTP.
* **Integración nativa con Pandas:** Devuelve la información limpia y estructurada directamente en objetos `pandas.DataFrame`.
* **Manejo flexible de argumentos:** Acepta listas, tuplas o conjuntos para las series y los convierte automáticamente al formato delimitado por comas que exige el servidor.
* **Validación de parámetros:** Decoradores internos que filtran parámetros no válidos antes de realizar la petición HTTP.

---

## Instalación

Puedes instalar la librería directamente desde PyPI o tu gestor de paquetes preferido:

```bash
pip install bdeapi
```

O usando **uv**:

```bash
uv add bdeapi
```

---

## Inicio Rápido

### 1. Obtener el último dato disponible de una o varias series

```python
from bdeapi import ultimo_dato

# Consultar el último valor del Euríbor a 1 año y 3 meses
df_data, df_metadata, df_info = ultimo_dato(
    idioma="es",
    listado_series=["D_1NBAF472", "D_DNBAD172"],
)

# Imprimir los valores numéricos y sus fechas
print(df_data)
```

### 2. Consultar el catálogo o metadatos de series

```python
from bdeapi import listado_series

# Obtener información del catálogo para una serie específica
df_data, df_metadata, df_info = listado_series(
    idioma="es",
    listado_series="D_1NBAF472",
)
```

---

## Estructura de las Respuestas

Todas las funciones de consulta devuelven siempre una tupla con **3 DataFrames de Pandas**:

| DataFrame | Contenido / Descripción |
| --- | --- |
| **`df_data`** | Datos de la serie temporal (`serie`, `fechaValor`, `valor`, etc.) |
| **`df_metadata`** | Metadatos de frecuencia y precisión (`descripcionCorta`, `codFrecuencia`, `decimales`, etc.) |
| **`df_info`** | Títulos e información descriptiva detallada proporcionada por el BdE |

---

## Parámetros Soportados y Mapeo Interno

Para facilitar el desarrollo, `bdeapi` traduce de forma transparente los argumentos de Python a la QueryString que exige la API HTTP del Banco de España:

| Parámetro en Python | Parámetro URL (API BdE) | Tipos Aceptados | Ejemplo |
| --- | --- | --- | --- |
| `idioma` | `idioma` | `str` | `"es"`, `"en"` |
| `listado_series` | `series` | `str`, `list`, `tuple` | `["D_1NBAF472", "D_DNBAD172"]` |
| `rango_temporal` | `rango` | `str` | `"2024-01-01,2026-01-01"` |

---

## Pruebas Unitarias

Para ejecutar la suite de tests y verificar la cobertura del código:

```bash
# Ejecutar los tests
pytest

# Reporte de cobertura de código
pytest --cov=bdeapi
```

---

## Licencia

Este proyecto está distribuido bajo la Licencia **GPL-3.0**. Consulta el archivo `LICENSE` para más detalles.

---

## Documentación de la API
- [Servicio web de Estadísticas (API) - Banco de España](https://www.bde.es/webbe/es/estadisticas/recursos/api-estadisticas-bde.html)

---

## ⚠️ Exención de Responsabilidad (Disclaimer)

Este proyecto es una librería no oficial y de desarrollo independiente. **No está afiliado, asociado, autorizado, respaldado ni conectado de ninguna manera con el Banco de España (BdE)** ni con ninguna de sus filiales u organismos oficiales.

* El nombre *Banco de España*, *BIEST* y las marcas o nombres relacionados son marcas registradas de sus respectivos propietarios.
* Este paquete únicamente facilita la interacción programática con el servicio web de datos abiertos del Banco de España a través de sus endpoints públicos.