ctr-datadis 0.3.0

SDK completo de Python para la API oficial de Datadis - Acceso programático a datos de consumo eléctrico español

ctr-datadis

Un SDK completo de Python para interactuar con la API oficial de Datadis (plataforma española de datos de suministro eléctrico).

Datadis es la plataforma oficial del gobierno español que proporciona acceso a los datos de consumo eléctrico para los consumidores españoles. Este SDK facilita el acceso a tus datos eléctricos de forma programática.

Características

• Autenticación Automática - Autenticación basada en tokens con renovación automática
• Cobertura Completa de API - Acceso a todos los endpoints de la API de Datadis
• Parámetros Flexibles - Acepta tipos Python nativos (datetime, int, float) además de strings
• Seguridad de Tipos - Type hints completos y modelos Pydantic para validación de datos
• Manejo de Errores - Manejo exhaustivo de errores con excepciones personalizadas
• Python 3.9+ - Compatible con versiones modernas de Python
• Normalización de Texto - Manejo automático de acentos españoles y caracteres especiales
• Modelos de Datos - Datos estructurados con Pydantic para consumo, suministro y datos de contrato
• Dos Versiones de API - Soporte para clientes V1 y V2 (V2 incluye datos de energía reactiva)

Instalación

pip install ctr-datadis

Inicio Rápido

from datetime import datetime, date
from datadis_python.client.v1.simple_client import SimpleDatadisClientV1

# Inicializar cliente con tus credenciales de Datadis
client = SimpleDatadisClientV1(username="12345678A", password="tu_password")

# Obtener tus puntos de suministro
supplies = client.get_supplies()
print(f"Encontrados {len(supplies)} puntos de suministro")

# Obtener datos de consumo con tipos flexibles (más pythónico!)
consumption = client.get_consumption(
    cups="ES1234000000000001JN0F",  # Tu código CUPS
    distributor_code=2,             # int en lugar de string
    date_from=datetime(2024, 1, 1),  # datetime object
    date_to=date(2024, 2, 28),     # date object
    measurement_type=0              # int en lugar de string
)
print(f"Obtenidos {len(consumption)} registros de consumo")

# También funciona con strings tradicionales (100% compatible)
consumption_classic = client.get_consumption(
    cups="ES1234000000000001JN0F",
    distributor_code="2",           # string clásico
    date_from="2024/01/01",         # string clásico
    date_to="2024/02/28"            # string clásico
)

# Para cliente V2 con datos de energía reactiva
from datadis_python.client.v2.simple_client import SimpleDatadisClientV2

client_v2 = SimpleDatadisClientV2(username="12345678A", password="tu_password")
reactive_data = client_v2.get_reactive_data(
    cups="ES1234000000000001JN0F",
    distributor_code=2,             # También acepta tipos flexibles
    date_from=datetime(2024, 1, 1),
    date_to=date(2024, 2, 28)
)

Métodos Disponibles

Información de Suministro

# Obtener todos los puntos de suministro
supplies = client.get_supplies()

# Obtener detalles del contrato para un CUPS específico
contract = client.get_contract_detail(cups="ES1234...", distributor_code="2")

Datos de Consumo

from datetime import datetime, date

# Obtener datos de consumo con tipos flexibles
consumption = client.get_consumption(
    cups="ES1234000000000001JN0F",
    distributor_code=2,             # int o string
    date_from=datetime(2024, 1, 1), # datetime, date o string
    date_to=date(2024, 2, 28),      # datetime, date o string
    measurement_type=0,             # int, float o string
    point_type=1                    # int, float o string (opcional)
)

# Obtener datos de potencia máxima
max_power = client.get_max_power(
    cups="ES1234000000000001JN0F",
    distributor_code=2,             # int o string
    date_from=datetime(2024, 1, 1), # datetime, date o string
    date_to=date(2024, 2, 28)       # datetime, date o string
)

Información de Distribuidoras

# Obtener distribuidoras disponibles
distributors = client.get_distributors()

Tipos de Parámetros Flexibles

El SDK acepta múltiples tipos de parámetros para mayor comodidad, manteniendo 100% de compatibilidad hacia atrás:

Fechas

# Todas estas son válidas:
date_from = "2024/01/15"           # String tradicional
date_from = datetime(2024, 1, 15)  # datetime object
date_from = date(2024, 1, 15)      # date object

# Para fechas mensuales:
date_from = "2024/01"              # String YYYY/MM
date_from = datetime(2024, 1, 1)   # Se convierte a 2024/01

Números

# Measurement type, point type, etc.:
measurement_type = "0"             # String tradicional
measurement_type = 0               # int
measurement_type = 0.0             # float

# Distributor code:
distributor_code = "2"             # String tradicional
distributor_code = 2               # int

Conversión Automática

• Las fechas datetime/date se convierten automáticamente al formato API (YYYY/MM/DD o YYYY/MM)
• Los números int/float se convierten a strings
• Los strings se validan para asegurar formato correcto
• Validación completa en todos los casos

Modelos de Datos

El SDK incluye modelos Pydantic para manejo seguro de tipos:

• SupplyData - Información de puntos de suministro
• ConsumptionData - Registros de consumo energético
• ContractData - Detalles del contrato
• MaxPowerData - Datos de demanda de potencia máxima

Manejo de Errores

from datadis_python.exceptions import DatadisError, AuthenticationError, APIError

try:
    supplies = client.get_supplies()
except AuthenticationError:
    print("Credenciales inválidas")
except APIError as e:
    print(f"Error de API: {e}")
except DatadisError as e:
    print(f"Error de Datadis: {e}")

Requisitos

• Python 3.9 o superior
• Credenciales válidas de cuenta Datadis
• Conexión a internet

Limitaciones de la API

• Los datos están disponibles solo para los últimos 2 años
• El formato de fecha debe ser YYYY/MM (datos mensuales)
• La plataforma Datadis aplica limitación de velocidad (rate limiting)
• La mayoría de operaciones requieren un código de distribuidora

Documentación

• Documentación Completa: https://ctr-datadis.readthedocs.io
• Referencia de API: Documentación detallada de la API con ejemplos
• Ejemplos: Tutoriales paso a paso y casos de uso
• Solución de Problemas: Problemas comunes y soluciones

Versiones de API

Característica	Cliente V1	Cliente V2
Datos de Consumo	✓	✓
Información de Suministro	✓	✓
Detalles del Contrato	✓	✓
Datos de Potencia Máxima	✓	✓
Datos de Energía Reactiva	✗	✓

Recomendación: Usa V1 para datos básicos de consumo, V2 para análisis avanzado de energía reactiva.

Contribuciones

Las contribuciones son bienvenidas! No dudes en enviar un Pull Request.

Licencia

Este proyecto está licenciado bajo la Licencia MIT - consulta el archivo LICENSE para más detalles.

Descargo de Responsabilidad

Este es un SDK no oficial para la API de Datadis. No está afiliado ni respaldado por Datadis o el gobierno español.