ctr-datadis Documentation

ctr-datadis es un SDK completo de Python para interactuar con la API oficial de Datadis, la plataforma española de datos de suministro eléctrico. Proporciona acceso type-safe a datos de consumo eléctrico, información de suministro y utilidades relacionadas para consumidores de energía españoles.

Características principales:

  • Dos versiones de API: Soporte completo para V1 y V2 de la API de Datadis

  • Type-safe: Modelos Pydantic para validación automática de datos

  • Manejo robusto de errores: V2 incluye manejo específico de errores por distribuidor

  • Fácil de usar: API simple y pythónica con context managers

  • Reintentos automáticos: Backoff exponencial para timeouts y errores de red

  • Completo: Acceso a todos los endpoints incluyendo energía reactiva (V2)

  • Bien documentado: Documentación completa con ejemplos didácticos

Inicio Rápido

pip install ctr-datadis

Cliente V1 (Básico)

from datadis_python.client.v1.simple_client import SimpleDatadisClientV1

# Inicializar cliente V1
with SimpleDatadisClientV1("tu_nif", "tu_contraseña") as client:
    # Obtener puntos de suministro
    supplies = client.get_supplies()

    if supplies:
        # Obtener datos de consumo (formato mensual requerido)
        consumption = client.get_consumption(
            cups=supplies[0].cups,
            distributor_code=supplies[0].distributorCode,
            date_from="2024/01",  # Solo formato mensual YYYY/MM
            date_to="2024/12"
        )

        total_kwh = sum(c.consumptionKWh for c in consumption if c.consumptionKWh)
        print(f"Consumo total 2024: {total_kwh:.2f} kWh")

Cliente V2 (Recomendado - con manejo de errores mejorado)

from datadis_python.client.v2.simple_client import SimpleDatadisClientV2

# Inicializar cliente V2
with SimpleDatadisClientV2("tu_nif", "tu_contraseña") as client:
    # Obtener puntos de suministro con manejo de errores
    supplies_response = client.get_supplies()

    print(f"Suministros obtenidos: {len(supplies_response.supplies)}")

    # Verificar errores por distribuidor
    if supplies_response.distributor_error:
        for error in supplies_response.distributor_error:
            print(f"Error en {error.distributorName}: {error.errorDescription}")

    if supplies_response.supplies:
        supply = supplies_response.supplies[0]

        # Obtener consumo con manejo robusto de errores
        consumption_response = client.get_consumption(
            cups=supply.cups,
            distributor_code=supply.distributorCode,
            date_from="2024/01",
            date_to="2024/12"
        )

        if consumption_response.time_curve:
            total_kwh = sum(c.consumptionKWh for c in consumption_response.time_curve
                          if c.consumptionKWh)
            print(f"Consumo total 2024: {total_kwh:.2f} kWh")

        # Funcionalidad exclusiva V2: Energía reactiva
        reactive_data = client.get_reactive_data(
            cups=supply.cups,
            distributor_code=supply.distributorCode,
            date_from="2024/01",
            date_to="2024/12"
        )
        print(f"Datos de energía reactiva: {len(reactive_data)} registros")

Documentación

Guía del Usuario

Referencia de la API

Licencia

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

Contribuir

Las contribuciones son bienvenidas. Por favor:

  1. Fork el repositorio

  2. Crea una rama para tu feature (git checkout -b feature/nueva-funcionalidad)

  3. Commit tus cambios (git commit -am “Añadir nueva funcionalidad”)

  4. Push a la rama (git push origin feature/nueva-funcionalidad)

  5. Crea un Pull Request

Soporte