Modelos de Datos

El SDK utiliza Pydantic para proporcionar modelos de datos type-safe que validan automáticamente las respuestas de la API de Datadis. Todos los modelos incluyen validación de tipos y conversión automática de datos.

Características Generales

Todos los modelos comparten estas características:

  • Validación automática: Los datos se validan al crear instancias

  • Serialización: Conversión automática a/desde JSON

  • Type hints: Soporte completo para IDEs y herramientas de análisis

  • Alias de campos: Mapeo automático entre nombres de la API y Python

  • Documentación integrada: Cada campo está documentado

Modelo de Consumo Energético

class datadis_python.models.consumption.ConsumptionData(*, cups, date, time, consumptionKWh, obtainMethod, surplusEnergyKWh=None, generationEnergyKWh=None, selfConsumptionEnergyKWh=None)[fuente]

Bases: BaseModel

Modelo Pydantic para datos de consumo energético de Datadis.

Representa una medición de consumo eléctrico proveniente de los contadores inteligentes de las distribuidoras eléctricas españolas. Los datos incluyen tanto consumo tradicional como información de autoconsumo y generación para instalaciones con paneles solares u otras fuentes de energía renovable.

Características principales:

  • Validación automática: Todos los campos se validan con Pydantic

  • Compatibilidad de alias: Soporta tanto nombres Python como nombres API

  • Datos de autoconsumo: Información completa para instalaciones fotovoltaicas

  • Granularidad temporal: Mediciones horarias o cuarto-horarias según disponibilidad

  • Métodos de obtención: Distingue entre mediciones reales y estimadas

Tipos de mediciones soportadas:

  • Consumo tradicional: Energía consumida de la red eléctrica

  • Autoconsumo: Energía generada y consumida localmente (sin pasar por la red)

  • Excedentes/Vertidos: Energía generada y vendida a la red eléctrica

  • Generación total: Energía total producida por la instalación renovable

Métodos de obtención de datos:

  • «Real»: Medición directa del contador inteligente

  • «Estimada»: Estimación basada en patrones históricos o interpolación

  • «Provisional»: Datos preliminares pendientes de validación final

Ejemplo

Uso básico del modelo:

from datadis_python.models.consumption import ConsumptionData

# Datos típicos de consumo sin autoconsumo
consumption_basic = ConsumptionData(
    cups="ES001234567890123456AB",
    date="2024/12/15",
    time="14:00",
    consumptionKWh=2.45,
    obtainMethod="Real"
)

print(f"Consumo: {consumption_basic.consumption_kwh} kWh")
print(f"Método: {consumption_basic.obtain_method}")

Datos de instalación con autoconsumo fotovoltaico:

# Instalación con paneles solares
consumption_solar = ConsumptionData(
    cups="ES001234567890123456AB",
    date="2024/07/20",
    time="13:00",  # Hora de máxima producción solar
    consumptionKWh=0.25,      # Poca energía de la red
    obtainMethod="Real",
    surplusEnergyKWh=3.20,    # Excedente vendido a la red
    generationEnergyKWh=5.80, # Generación total de paneles
    selfConsumptionEnergyKWh=2.60  # Autoconsumo directo
)

# Verificar balance energético
total_consumption = (consumption_solar.consumption_kwh +
                   consumption_solar.self_consumption_energy_kwh)
print(f"Consumo total real: {total_consumption} kWh")
print(f"Excedente vendido: {consumption_solar.surplus_energy_kwh} kWh")

Validación automática con alias:

# Usando nombres de la API (camelCase)
data_api = {
    "cups": "ES001234567890123456AB",
    "date": "2024/12/15",
    "time": "10:30",
    "consumptionKWh": 1.85,  # Nombre API
    "obtainMethod": "Estimada"
}

consumption = ConsumptionData(**data_api)
print(f"Consumo: {consumption.consumption_kwh}")  # Acceso Python
Parámetros:

  • cups (str) – Código CUPS del punto de suministro. Identificador único de 22 caracteres que identifica de forma inequívoca el punto de conexión a la red eléctrica

  • date (str) – Fecha de la medición en formato YYYY/MM/DD. Corresponde al día de la lectura del contador, en zona horaria española (CET/CEST)

  • time (str) – Hora de la medición en formato HH:MM (24h). Para mediciones horarias normalmente :00, para cuarto-horarias :00, :15, :30, :45

  • consumption_kwh (float) – Energía activa consumida desde la red eléctrica en kWh. Representa la energía que el usuario ha tomado de la red durante el período de medición

  • obtain_method (str) – Método de obtención de los datos. Valores posibles: «Real» (medición directa), «Estimada» (cálculo), «Provisional»

  • surplus_energy_kwh (Optional[float]) – Energía excedentaria vertida a la red en kWh. Solo aplica para instalaciones de autoconsumo con excedentes. Representa la energía generada localmente y vendida/cedida a la red

  • generation_energy_kwh (Optional[float]) – Energía total generada por la instalación renovable en kWh. Suma del autoconsumo directo más los excedentes vertidos. Solo aplica para instalaciones con generación propia

  • self_consumption_energy_kwh (Optional[float]) – Energía autoconsumida directamente en kWh. Energía generada localmente y consumida sin pasar por la red. Solo aplica para instalaciones de autoconsumo

  • consumptionKWh (float)

  • obtainMethod (str)

  • surplusEnergyKWh (float | None)

  • generationEnergyKWh (float | None)

  • selfConsumptionEnergyKWh (float | None)

Muestra:

ValidationError – Si algún campo no cumple las validaciones de Pydantic (tipos incorrectos, valores nulos en campos obligatorios, etc.)

Nota

Para instalaciones con autoconsumo, se cumple la ecuación: generation_energy_kwh = self_consumption_energy_kwh + surplus_energy_kwh

Ver también

  • ConsumptionResponse - Respuesta estructurada de la API V2

  • SimpleDatadisClientV1.get_consumption() - Obtener datos V1

  • SimpleDatadisClientV2.get_consumption() - Obtener datos V2

cups: str
date: str
time: str
consumption_kwh: float
obtain_method: str
surplus_energy_kwh: float | None
generation_energy_kwh: float | None
self_consumption_energy_kwh: float | None
model_config: ClassVar[ConfigDict] = {'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

El modelo ConsumptionData representa un registro de consumo energético:

from datadis_python.models.consumption import ConsumptionData

# Crear desde diccionario (como viene de la API)
consumo = ConsumptionData(
    cups="ES1234000000000001JN0F",
    date="2024/01/15",
    time="01:00",
    consumptionKWh=2.5,
    obtainMethod="Real"
)

# Acceder a los datos
print(f"Consumo: {consumo.consumption_kwh} kWh")
print(f"Fecha: {consumo.date} {consumo.time}")
print(f"Método: {consumo.obtain_method}")

# Serializar a diccionario
data = consumo.model_dump()

Modelo de Punto de Suministro

class datadis_python.models.supply.SupplyData(*, address, cups, postalCode, province, municipality, distributor, validDateFrom, validDateTo=None, pointType, distributorCode)[fuente]

Bases: BaseModel

Modelo Pydantic para datos de puntos de suministro eléctrico españoles.

Representa la información completa de un punto de suministro (CUPS) registrado en el sistema eléctrico español. Cada objeto contiene todos los datos técnicos, geográficos y contractuales necesarios para identificar y trabajar con un punto de conexión específico a la red eléctrica nacional.

Información del punto de suministro:

  • Identificación única: Código CUPS de 20-22 caracteres

  • Ubicación física: Dirección completa, código postal, provincia y municipio

  • Información técnica: Tipo de punto de medida y clasificación

  • Datos del distribuidor: Empresa responsable de la red en la zona

  • Período contractual: Fechas de validez del contrato actual

Tipos de punto de medida (point_type):

  • Tipo 1: Potencia contratada > 450 kW (grandes industrias)

  • Tipo 2: 50 kW < Potencia ≤ 450 kW (medianas industrias)

  • Tipo 3: 15 kW < Potencia ≤ 50 kW (pequeñas industrias, grandes comercios)

  • Tipo 4: 10 kW < Potencia ≤ 15 kW (pequeños comercios, grandes viviendas)

  • Tipo 5: Potencia ≤ 10 kW (viviendas domésticas típicas)

Estructura del código CUPS:

  • Formato: ESXXXXXXXXXXXXXXXXXXX

  • Longitud: 20-22 caracteres alfanuméricos

  • Prefijo: Siempre «ES» para España

  • Identificador: Único a nivel nacional

  • Verificación: Dígitos de control incluidos

Distribuidores por zona geográfica:

  • Viesgo (1): Cantabria, Asturias

  • E-distribución (2): Cobertura nacional, mayor distribuidor

  • E-redes (3): Galicia

  • ASEME (4): Melilla (ciudad autónoma)

  • UFD (5): Nacional, especialmente Cataluña y Madrid

  • EOSA (6): Aragón

  • CIDE (7): Ceuta (ciudad autónoma)

  • IDE (8): Islas Baleares

Ejemplo

Análisis básico de un punto de suministro:

from datadis_python.models.supply import SupplyData

# Punto de suministro doméstico típico
supply_home = SupplyData(
    address="Calle Mayor 123, 1º A",
    cups="ES001234567890123456AB",
    postalCode="28001",
    province="Madrid",
    municipality="Madrid",
    distributor="E-distribución",
    validDateFrom="2023/01/15",
    validDateTo=None,  # Contrato activo
    pointType=5,  # Doméstico
    distributorCode="2"  # E-distribución
)

print(f"CUPS: {supply_home.cups}")
print(f"Ubicación: {supply_home.address}")
print(f"Zona: {supply_home.municipality}, {supply_home.province}")
print(f"Distribuidor: {supply_home.distributor}")

# Determinar tipo de instalación
point_types = {
    1: "Gran industria (>450 kW)",
    2: "Mediana industria (50-450 kW)",
    3: "Pequeña industria (15-50 kW)",
    4: "Comercio/gran vivienda (10-15 kW)",
    5: "Vivienda doméstica (≤10 kW)"
}

print(f"Tipo: {point_types.get(supply_home.point_type, 'Desconocido')}")

Análisis de vigencia contractual:

from datetime import datetime

def analyze_contract_validity(supply: SupplyData) -> str:
    \"\"\"Analiza el estado del contrato del suministro.\"\"\"

    if supply.valid_date_to is None:
        return "✅ Contrato activo (sin fecha de fin)"

    # Parsear fecha de fin (formato YYYY/MM/DD)
    try:
        end_date = datetime.strptime(supply.valid_date_to, "%Y/%m/%d")
        current_date = datetime.now()

        if end_date > current_date:
            days_remaining = (end_date - current_date).days
            return f"✅ Contrato activo ({days_remaining} días restantes)"
        else:
            return "❌ Contrato expirado"
    except ValueError:
        return "⚠️ Fecha de fin inválida"

# Usar la función
status = analyze_contract_validity(supply_home)
print(f"Estado contractual: {status}")

Agrupación por distribuidor:

# Lista de suministros de un usuario
supplies = [
    SupplyData(
        address="Calle A", cups="ES0012...", postalCode="28001",
        province="Madrid", municipality="Madrid", distributor="E-distribución",
        validDateFrom="2023/01/01", pointType=5, distributorCode="2"
    ),
    SupplyData(
        address="Calle B", cups="ES0034...", postalCode="08001",
        province="Barcelona", municipality="Barcelona", distributor="UFD",
        validDateFrom="2022/06/15", pointType=4, distributorCode="5"
    )
]

# Agrupar por distribuidor
by_distributor = {}
for supply in supplies:
    dist_name = supply.distributor
    if dist_name not in by_distributor:
        by_distributor[dist_name] = []
    by_distributor[dist_name].append(supply)

print("Suministros por distribuidor:")
for distributor, supply_list in by_distributor.items():
    print(f"- {distributor}: {len(supply_list)} suministros")
    for supply in supply_list:
        print(f"  * {supply.municipality} ({supply.cups[:8]}...)")

Validación de código CUPS:

def validate_cups_format(cups: str) -> bool:
    \"\"\"Valida formato básico del código CUPS español.\"\"\"

    # Verificaciones básicas
    if not cups.startswith("ES"):
        return False
    if len(cups) < 20 or len(cups) > 22:
        return False
    if not cups[2:].isalnum():
        return False

    return True

# Validar CUPS
if validate_cups_format(supply_home.cups):
    print("✅ Formato CUPS válido")
else:
    print("❌ Formato CUPS inválido")

Análisis geográfico:

# Identificar región por distribuidor
regions = {
    "1": "Norte (Cantabria/Asturias)",
    "2": "Nacional (E-distribución)",
    "3": "Galicia",
    "4": "Melilla",
    "5": "Nacional (UFD)",
    "6": "Aragón",
    "7": "Ceuta",
    "8": "Baleares"
}

region = regions.get(supply_home.distributor_code, "Región desconocida")
print(f"Región de distribución: {region}")
Parámetros:

  • address (str) – Dirección física completa del punto de suministro. Incluye calle, número, piso/puerta si aplica. Corresponde a la ubicación real donde se encuentra la instalación eléctrica

  • cups (str) – Código CUPS (Código Único del Punto de Suministro). Identificador alfanumérico único de 20-22 caracteres que identifica inequívocamente el punto de conexión a la red eléctrica española

  • postal_code (str) – Código postal de la dirección del suministro. Código numérico de 5 dígitos que identifica la zona postal española

  • province (str) – Provincia española donde se ubica el punto de suministro. Corresponde a la división administrativa de primer nivel

  • municipality (str) – Municipio donde se encuentra el suministro eléctrico. División administrativa local dentro de la provincia

  • distributor (str) – Nombre comercial de la empresa distribuidora responsable de la red eléctrica en la zona geográfica del suministro

  • valid_date_from (str) – Fecha de inicio de validez del contrato actual en formato YYYY/MM/DD. Marca el comienzo del período contractual vigente

  • valid_date_to (Optional[str]) – Fecha de finalización del contrato en formato YYYY/MM/DD. None para contratos sin fecha de fin definida (más común)

  • point_type (int) – Tipo de punto de medida según clasificación técnica española. Entero del 1 al 5 que determina el tipo de instalación y medición

  • distributor_code (str) – Código numérico del distribuidor (1-8). Identificador único usado en las consultas API para el distribuidor específico

  • postalCode (str)

  • validDateFrom (str)

  • validDateTo (str | None)

  • pointType (int)

  • distributorCode (str)

Muestra:

ValidationError – Si algún campo obligatorio falta o tiene formato incorrecto

Nota

El point_type determina el tipo de contador y sistema de medición. Los tipos 1-3 suelen tener medición cuarto-horaria, los tipos 4-5 horaria.

Truco

Use el distributor_code para consultas posteriores de consumo, contratos y otros datos específicos del punto de suministro.

Ver también

  • SuppliesResponse - Respuesta estructurada de la API V2 que contiene estos datos

  • SimpleDatadisClientV1.get_supplies() - Obtener puntos de suministro V1

  • SimpleDatadisClientV2.get_supplies() - Obtener puntos de suministro V2

  • Códigos CUPS oficiales en la documentación del sistema eléctrico español

Added in version 1.0: Modelo base para puntos de suministro del sistema eléctrico español

address: str
cups: str
postal_code: str
province: str
municipality: str
distributor: str
valid_date_from: str
valid_date_to: str | None
point_type: int
distributor_code: str
model_config: ClassVar[ConfigDict] = {'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

Representa un punto de suministro eléctrico:

from datadis_python.models.supply import SupplyData

suministro = SupplyData(
    cups="ES1234000000000001JN0F",
    distributorCode="2",
    address="Calle Ejemplo 123",
    postalCode="28001",
    province="Madrid",
    municipality="Madrid",
    validDateFrom="2020/01/01",
    validDateTo="2025/12/31"
)

print(f"CUPS: {suministro.cups}")
print(f"Dirección: {suministro.address}")
print(f"Válido hasta: {suministro.valid_date_to}")

Modelo de Contrato

class datadis_python.models.contract.ContractData(*, cups, distributor, marketer=None, tension, accessFare, province, municipality, postalCode, contractedPowerkW, timeDiscrimination=None, modePowerControl, startDate, endDate=None, codeFare, selfConsumptionTypeCode=None, selfConsumptionTypeDesc=None, section=None, subsection=None, partitionCoefficient=None, cau=None, installedCapacityKW=None, dateOwner=None, lastMarketerDate=None, maxPowerInstall=None)[fuente]

Bases: BaseModel

Modelo Pydantic completo para datos contractuales de suministros eléctricos.

Representa la información contractual completa de un punto de suministro (CUPS), incluyendo datos técnicos, comerciales, tarifarios y de autoconsumo. Este modelo contiene toda la información relevante sobre el contrato eléctrico asociado a una instalación, desde datos básicos hasta configuraciones avanzadas de autoconsumo.

Información contractual incluida:

  • Datos básicos: CUPS, distribuidor, comercializadora, ubicación

  • Información técnica: Tensión, potencias contratadas, control de potencia

  • Datos tarifarios: Tarifa de acceso, discriminación horaria, códigos CNMC

  • Autoconsumo: Tipo, configuración, coeficientes, CAU

  • Histórico: Períodos de propiedad, cambios de comercializadora

Tipos de instalaciones soportadas:

  • Consumo tradicional: Sin generación propia

  • Autoconsumo individual: Instalación fotovoltaica privada

  • Autoconsumo colectivo: Instalaciones compartidas entre varios usuarios

  • Autoconsumo con excedentes: Venta de energía sobrante a la red

  • Autoconsumo sin excedentes: Generación solo para consumo propio

Códigos de tarifa de acceso (CNMC):

  • 2.0TD: Baja tensión ≤ 15 kW (doméstico típico)

  • 3.0TD: Baja tensión > 15 kW ≤ 100 kW (comercios, pequeña industria)

  • 6.1TD: Alta tensión 1-36 kV (gran industria)

  • 6.2TD: Alta tensión 36-72.5 kV

  • 6.3TD: Alta tensión 72.5-145 kV

  • 6.4TD: Alta tensión ≥ 145 kV

Ejemplo

Contrato doméstico básico sin autoconsumo:

from datadis_python.models.contract import ContractData

# Vivienda típica con tarifa 2.0TD
contract_home = ContractData(
    cups="ES001234567890123456AB",
    distributor="E-distribución",
    marketer="Iberdrola",
    tension="BT",
    accessFare="2.0TD (Peaje de acceso 2.0TD)",
    province="Madrid",
    municipality="Madrid",
    postalCode="28001",
    contractedPowerkW=[5.75],  # 5.75 kW contratados
    timeDiscrimination="DHA",   # Discriminación horaria
    modePowerControl="ICP",     # Interruptor Control Potencia
    startDate="2023/01/15",
    codeFare="2.0TD"
)

print(f"Potencia contratada: {contract_home.contracted_power_kw[0]} kW")
print(f"Tarifa: {contract_home.code_fare}")

Instalación con autoconsumo fotovoltaico:

from datadis_python.models.contract import ContractData, DateOwner

# Casa con paneles solares y autoconsumo
contract_solar = ContractData(
    cups="ES001234567890123456AB",
    distributor="UFD",
    marketer="Naturgy",
    tension="BT",
    accessFare="2.0TD con autoconsumo",
    province="Valencia",
    municipality="Valencia",
    postalCode="46001",
    contractedPowerkW=[4.60],
    modePowerControl="ICP",
    startDate="2022/03/01",
    codeFare="2.0TD",
    # Configuración de autoconsumo
    selfConsumptionTypeCode="41",
    selfConsumptionTypeDesc="Autoconsumo con excedentes acogido a compensación",
    installedCapacityKW=5.0,  # 5 kW de paneles solares
    cau="ES00123456789",      # Código de Autoconsumo Único
    dateOwner=[
        DateOwner(startDate="2022/03/01", endDate="2024/12/31")
    ]
)

print(f"Tipo autoconsumo: {contract_solar.self_consumption_type_desc}")
print(f"Potencia instalada: {contract_solar.installed_capacity_kw} kW")

Autoconsumo colectivo con coeficiente de reparto:

# Instalación compartida en comunidad de vecinos
contract_collective = ContractData(
    cups="ES001234567890123456AB",
    distributor="E-distribución",
    tension="BT",
    accessFare="2.0TD autoconsumo colectivo",
    province="Barcelona",
    municipality="Barcelona",
    postalCode="08001",
    contractedPowerkW=[3.45],
    codeFare="2.0TD",
    selfConsumptionTypeCode="43",
    selfConsumptionTypeDesc="Autoconsumo colectivo con excedentes",
    partitionCoefficient=0.15,  # 15% del total generado
    cau="ES00987654321",
    installedCapacityKW=20.0,    # Instalación total compartida
    startDate="2023/06/01"
)

print(f"Coeficiente de reparto: {contract_collective.partition_coefficient}")
Parámetros:

  • cups (str) – Código CUPS del punto de suministro. Identificador único nacional de 20-22 caracteres que identifica inequívocamente el punto de conexión

  • distributor (str) – Nombre de la empresa distribuidora responsable de la red en la zona geográfica del suministro

  • marketer (Optional[str]) – Empresa comercializadora que factura la energía. Solo visible si el usuario autenticado es propietario del CUPS

  • tension (str) – Nivel de tensión del suministro. Valores típicos: «BT» (Baja Tensión), «AT» (Alta Tensión), «MT» (Media Tensión)

  • access_fare (str) – Descripción completa de la tarifa de acceso aplicable. Incluye el código y descripción extendida

  • province (str) – Provincia donde se ubica físicamente el punto de suministro

  • municipality (str) – Municipio de ubicación del suministro eléctrico

  • postal_code (str) – Código postal de la dirección del punto de suministro

  • contracted_power_kw (List[float]) – Lista de potencias contratadas en kW por período tarifario. Para tarifas simples: un valor. Para discriminación horaria: múltiples valores

  • time_discrimination (Optional[str]) – Tipo de discriminación horaria aplicada. Valores típicos: «DHA» (Discriminación Horaria), «DHS» (Supervalle), None (tarifa simple)

  • mode_power_control (str) – Sistema de control de la potencia contratada. «ICP» (Interruptor Control Potencia) o «Maxímetro»

  • start_date (str) – Fecha de inicio de vigencia del contrato en formato YYYY/MM/DD

  • end_date (Optional[str]) – Fecha de finalización del contrato. None para contratos activos

  • code_fare (str) – Código oficial de la tarifa de acceso según clasificación CNMC. Define la estructura tarifaria aplicable

  • self_consumption_type_code (Optional[str]) – Código numérico del tipo de autoconsumo según RD 244/2019. Códigos 4X para diferentes modalidades de autoconsumo

  • self_consumption_type_desc (Optional[str]) – Descripción detallada del tipo de autoconsumo configurado. Especifica modalidad, excedentes y acogimiento a compensación

  • section (Optional[str]) – Clasificación de sección para autoconsumo según normativa vigente

  • subsection (Optional[str]) – Subclasificación específica dentro de la sección de autoconsumo

  • partition_coefficient (Optional[float]) – Coeficiente de reparto para autoconsumo colectivo. Porcentaje de la energía generada asignado a este CUPS (0.0-1.0)

  • cau (Optional[str]) – Código de Autoconsumo Único. Identificador oficial de la instalación de autoconsumo asignado por la administración competente

  • installed_capacity_kw (Optional[float]) – Potencia pico instalada de generación renovable en kW. Suma de toda la capacidad de generación asociada al autoconsumo

  • date_owner (Optional[List[DateOwner]]) – Lista de períodos durante los cuales el usuario autenticado ha sido propietario del punto de suministro

  • last_marketer_date (Optional[str]) – Fecha del último cambio de empresa comercializadora en formato YYYY/MM/DD

  • max_power_install (Optional[str]) – Potencia máxima de la instalación eléctrica en formato texto. Puede incluir información adicional sobre limitaciones técnicas

  • accessFare (str)

  • postalCode (str)

  • contractedPowerkW (List[float])

  • timeDiscrimination (str | None)

  • modePowerControl (str)

  • startDate (str)

  • endDate (str | None)

  • codeFare (str)

  • selfConsumptionTypeCode (str | None)

  • selfConsumptionTypeDesc (str | None)

  • partitionCoefficient (float | None)

  • installedCapacityKW (float | None)

  • dateOwner (List[DateOwner] | None)

  • lastMarketerDate (str | None)

  • maxPowerInstall (str | None)

Muestra:

ValidationError – Si algún campo obligatorio está ausente o tiene formato incorrecto

Nota

Para autoconsumo colectivo, el partition_coefficient debe sumar 1.0 entre todos los participantes de la instalación compartida.

Ver también

  • DateOwner - Modelo para períodos de propiedad

  • ContractResponse - Respuesta estructurada de la API V2

  • SimpleDatadisClientV2.get_contract_detail() - Obtener datos contractuales

  • RD 244/2019 para códigos de autoconsumo oficiales

Added in version 2.0: Soporte completo para autoconsumo y datos contractuales extendidos

cups: str
distributor: str
marketer: str | None
tension: str
access_fare: str
province: str
municipality: str
postal_code: str
contracted_power_kw: List[float]
time_discrimination: str | None
mode_power_control: str
start_date: str
end_date: str | None
code_fare: str
self_consumption_type_code: str | None
self_consumption_type_desc: str | None
section: str | None
subsection: str | None
partition_coefficient: float | None
cau: str | None
installed_capacity_kw: float | None
date_owner: List[DateOwner] | None
last_marketer_date: str | None
max_power_install: str | None
model_config: ClassVar[ConfigDict] = {'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

Información contractual del suministro:

from datadis_python.models.contract import ContractData

contrato = ContractData(
    cups="ES1234000000000001JN0F",
    distributorCode="2",
    marketer="Iberdrola",
    tension="BT",
    accessRate="2.0TD",
    contractedPowerP1=5.5,
    contractedPowerP2=5.5,
    validDateFrom="2023/01/01"
)

print(f"Comercializadora: {contrato.marketer}")
print(f"Tarifa: {contrato.access_rate}")
print(f"Potencia P1: {contrato.contracted_power_p1} kW")

Modelo de Distribuidor

class datadis_python.models.distributor.DistributorData(*, distributorCodes)[fuente]

Bases: BaseModel

Modelo Pydantic para datos de distribuidoras eléctricas españolas.

Representa la información de las empresas distribuidoras de energía eléctrica donde el usuario tiene puntos de suministro activos. Las distribuidoras son las empresas responsables del mantenimiento y operación de las redes eléctricas en España, y cada zona geográfica está asignada a una distribuidora específica.

Sistema eléctrico español:

Las distribuidoras están reguladas por la CNMC (Comisión Nacional de los Mercados y la Competencia) y tienen asignadas zonas geográficas exclusivas donde son responsables de la red de distribución eléctrica.

Distribuidoras principales en España:

  • Código «1»: Viesgo - Cantabria, Asturias

  • Código «2»: E-distribución (Endesa) - Nacional (mayor cobertura)

  • Código «3»: E-redes - Galicia

  • Código «4»: ASEME - Melilla

  • Código «5»: UFD (Naturgy) - Nacional, especialmente Cataluña, Madrid

  • Código «6»: EOSA - Aragón

  • Código «7»: CIDE - Ceuta

  • Código «8»: IDE (Redeia) - Islas Baleares

Diferencia con comercializadoras:

  • Distribuidoras: Mantienen y operan la red física (cables, transformadores)

  • Comercializadoras: Venden la energía y emiten facturas al usuario final

Ejemplo

Uso básico del modelo:

from datadis_python.models.distributor import DistributorData

# Datos típicos de respuesta V1
distributor_data = DistributorData(
    distributorCodes=["2", "5"]  # E-distribución y UFD
)

print("Distribuidoras donde tienes suministros:")
for code in distributor_data.distributor_codes:
    distributor_name = {
        "1": "Viesgo",
        "2": "E-distribución (Endesa)",
        "3": "E-redes",
        "4": "ASEME",
        "5": "UFD (Naturgy)",
        "6": "EOSA",
        "7": "CIDE",
        "8": "IDE (Redeia)"
    }.get(code, f"Distribuidor {code}")

    print(f"- Código {code}: {distributor_name}")

Uso con clientes V1:

from datadis_python.client.v1 import SimpleDatadisClientV1

with SimpleDatadisClientV1("12345678A", "password") as client:
    # Obtener distribuidoras donde el usuario tiene suministros
    distributors = client.get_distributors()

    print(f"Distribuidoras encontradas: {len(distributors)}")
    for dist in distributors:
        print(f"Códigos: {dist.distributor_codes}")

    # Usar el primer código para consultas posteriores
    if distributors and distributors[0].distributor_codes:
        first_code = distributors[0].distributor_codes[0]
        supplies = client.get_supplies(distributor_code=first_code)

Filtrado por zona geográfica:

# Ejemplo: usuario con suministros en múltiples zonas
multi_zone_data = DistributorData(
    distributorCodes=["2", "5", "8"]  # Endesa, Naturgy, Baleares
)

# Identificar regiones
regions = {
    "2": "Península (Endesa)",
    "5": "Cataluña/Madrid (Naturgy)",
    "8": "Islas Baleares (IDE)"
}

for code in multi_zone_data.distributor_codes:
    print(f"Suministros en: {regions.get(code, 'Región desconocida')}")
Parámetros:

  • distributor_codes (List[str]) – Lista de códigos de distribuidoras donde el usuario tiene puntos de suministro activos. Cada código identifica una empresa distribuidora específica del sistema eléctrico español

  • distributorCodes (List[str])

Muestra:

ValidationError – Si la lista está vacía o contiene valores no válidos

Nota

Este modelo representa la respuesta simplificada de la API V1. La API V2 utiliza modelos más complejos con información extendida de cada distribuidor.

Ver también

  • DistributorsResponse - Respuesta estructurada de la API V2

  • SimpleDatadisClientV1.get_distributors() - Obtener distribuidoras V1

  • SimpleDatadisClientV2.get_distributors() - Obtener distribuidoras V2

  • Los códigos obtenidos se usan en métodos de consulta específicos

Added in version 1.0: Soporte para códigos de distribuidor en API V1

distributor_codes: List[str]
model_config: ClassVar[ConfigDict] = {'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

Información sobre las empresas distribuidoras:

from datadis_python.models.distributor import DistributorData

distribuidor = DistributorData(
    distributorCodes=["2", "3", "5"]
)

print(f"Códigos disponibles: {distribuidor.distributor_codes}")
print(f"Primer código: {distribuidor.distributor_codes[0]}")

Modelo de Potencia Máxima

class datadis_python.models.max_power.MaxPowerData(*, cups, date, time, maxPower, period)[fuente]

Bases: BaseModel

Modelo Pydantic para datos de potencia máxima demandada en suministros eléctricos.

Representa el registro de potencia eléctrica máxima demandada en un punto de suministro durante un período determinado. Esta información es crucial para la facturación eléctrica, optimización de contratos y análisis de consumo, especialmente en instalaciones comerciales e industriales con control por maxímetro.

Conceptos fundamentales:

  • Potencia máxima: Pico de demanda eléctrica registrado en un período

  • Control por maxímetro: Sistema que registra automáticamente los picos de potencia

  • Períodos tarifarios: Franjas horarias con diferentes precios de energía

  • Penalizaciones: Excesos sobre la potencia contratada pueden generar recargos

Sistemas de control de potencia en España:

  • ICP (Interruptor Control Potencia): Corta el suministro si se excede la potencia

  • Maxímetro: Registra los picos pero permite el consumo (con posible recargo)

Períodos tarifarios comunes:

  • PUNTA: Horas de mayor demanda nacional (18:00-22:00 invierno)

  • LLANO: Horas intermedias de demanda

  • VALLE: Horas de menor demanda (01:00-08:00)

  • P1-P6: Períodos numerados según discriminación horaria específica

Ejemplo

Análisis de potencia máxima doméstica:

from datadis_python.models.max_power import MaxPowerData

# Pico de potencia en hora punta
max_power_home = MaxPowerData(
    cups="ES001234567890123456AB",
    date="2024/12/15",
    time="19:30",  # Hora punta de invierno
    maxPower=4250.0,  # 4.25 kW
    period="PUNTA"
)

print(f"Potencia máxima: {max_power_home.max_power / 1000:.2f} kW")
print(f"Momento pico: {max_power_home.date} a las {max_power_home.time}")
print(f"Período tarifario: {max_power_home.period}")

# Verificar si excede potencia contratada
potencia_contratada = 5750  # 5.75 kW en W
if max_power_home.max_power > potencia_contratada:
    exceso = max_power_home.max_power - potencia_contratada
    print(f"⚠️ Exceso: {exceso:.0f} W sobre lo contratado")
else:
    print("✅ Dentro de la potencia contratada")

Instalación comercial con múltiples períodos:

# Ejemplo de pequeño comercio
power_records = [
    MaxPowerData(
        cups="ES009876543210987654AB",
        date="2024/11/20",
        time="09:15",
        maxPower=12500.0,  # 12.5 kW
        period="LLANO"
    ),
    MaxPowerData(
        cups="ES009876543210987654AB",
        date="2024/11/20",
        time="20:45",
        maxPower=15200.0,  # 15.2 kW
        period="PUNTA"
    )
]

# Analizar picos por período
for record in power_records:
    kw_power = record.max_power / 1000
    print(f"Período {record.period}: {kw_power:.1f} kW a las {record.time}")

Optimización de contrato basada en datos históricos:

from datadis_python.client.v2 import SimpleDatadisClientV2

with SimpleDatadisClientV2("12345678A", "password") as client:
    # Obtener datos de potencia máxima del último año
    max_power_response = client.get_max_power(
        cups="ES001234567890123456AB",
        distributor_code="2",
        date_from="2024/01",
        date_to="2024/12"
    )

    # Analizar patrones para optimizar contrato
    monthly_peaks = {}
    for power_data in max_power_response.max_power_data:
        month = power_data.date[:7]  # YYYY/MM
        current_peak = monthly_peaks.get(month, 0)
        monthly_peaks[month] = max(current_peak, power_data.max_power)

    avg_peak = sum(monthly_peaks.values()) / len(monthly_peaks)
    print(f"Potencia promedio máxima: {avg_peak/1000:.2f} kW")
Parámetros:

  • cups (str) – Código CUPS del punto de suministro. Identificador único del punto de conexión donde se registró la potencia máxima

  • date (str) – Fecha en que se registró la potencia máxima en formato YYYY/MM/DD. Corresponde al día específico en que ocurrió el pico de demanda

  • time (str) – Hora exacta del pico de potencia en formato HH:MM (24h). Momento preciso en que se registró la demanda máxima del período

  • max_power (float) – Potencia máxima demandada expresada en vatios (W). Representa el pico de consumo eléctrico registrado en el momento especificado

  • period (str) – Período tarifario en el que ocurrió el pico. Valores típicos: «PUNTA», «LLANO», «VALLE» o códigos numéricos «P1»-«P6» según discriminación horaria

  • maxPower (float)

Muestra:

ValidationError – Si algún campo obligatorio falta o tiene formato incorrecto

Nota

La potencia se expresa en vatios (W). Para convertir a kilovatios: max_power / 1000

Truco

Para instalaciones con ICP, los picos registrados normalmente no excederán la potencia contratada ya que el interruptor cortaría el suministro.

Ver también

  • MaxPowerResponse - Respuesta estructurada de la API V2

  • SimpleDatadisClientV1.get_max_power() - Obtener datos V1

  • SimpleDatadisClientV2.get_max_power() - Obtener datos V2

  • ContractData - Información sobre potencias contratadas

Added in version 1.0: Soporte para datos de potencia máxima de contadores inteligentes

cups: str
date: str
time: str
max_power: float
period: str
model_config: ClassVar[ConfigDict] = {'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

Registros de potencia máxima demandada:

from datadis_python.models.max_power import MaxPowerData

potencia = MaxPowerData(
    cups="ES1234000000000001JN0F",
    date="2024/01/15",
    time="19:00",
    maxPower=4.2,
    period="P1"
)

print(f"Potencia máxima: {potencia.max_power} kW")
print(f"Período: {potencia.period}")

Modelo de Energía Reactiva

class datadis_python.models.reactive.ReactiveData(*, reactiveEnergy)[fuente]

Bases: BaseModel

Modelo Pydantic simplificado para respuesta de energía reactiva.

Wrapper o contenedor simple para datos de energía reactiva que encapsula la información principal en un objeto ReactiveEnergyData. Este modelo representa la estructura de respuesta básica de algunos endpoints de energía reactiva, proporcionando acceso directo a los datos principales.

Casos de uso:

  • Respuestas simples: Cuando solo se necesitan los datos principales

  • Compatibilidad: Para mantener consistencia con otras APIs

  • Encapsulación: Estructura que puede extenderse en futuras versiones

Ejemplo

Uso básico del modelo wrapper:

from datadis_python.models.reactive import ReactiveData, ReactiveEnergyData

# Datos encapsulados en el wrapper
reactive_wrapper = ReactiveData(
    reactiveEnergy=ReactiveEnergyData(
        cups="ES001234567890123456AB",
        energy=[],  # Lista de períodos
        code=None,
        code_desc=None
    )
)

# Acceso a los datos principales
main_data = reactive_wrapper.reactive_energy
print(f"CUPS: {main_data.cups}")
print(f"Períodos disponibles: {len(main_data.energy)}")

Procesamiento directo:

# Trabajar directamente con los datos encapsulados
if reactive_wrapper.reactive_energy.code is None:
    # Procesar datos de energía reactiva
    for period in reactive_wrapper.reactive_energy.energy:
        print(f"Mes {period.date}: datos disponibles")
else:
    print(f"Error: {reactive_wrapper.reactive_energy.code_desc}")
Parámetros:

  • reactive_energy (ReactiveEnergyData) – Objeto ReactiveEnergyData que contiene toda la información de energía reactiva para el punto de suministro consultado

  • reactiveEnergy (ReactiveEnergyData)

Muestra:

ValidationError – Si el objeto ReactiveEnergyData no es válido

Nota

Este modelo es principalmente un wrapper. Para acceso a datos detallados, utilice directamente el atributo reactive_energy.

Ver también

reactive_energy: ReactiveEnergyData
model_config: ClassVar[ConfigDict] = {'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

Datos de energía reactiva:

from datadis_python.models.reactive import ReactiveData

reactiva = ReactiveData(
    cups="ES1234000000000001JN0F",
    date="2024/01/15",
    time="01:00",
    reactiveEnergyQ1=0.5,
    reactiveEnergyQ2=0.3,
    reactiveEnergyQ3=0.1,
    reactiveEnergyQ4=0.2
)

print(f"Q1: {reactiva.reactive_energy_q1} kVArh")

Modelos de Respuesta

Respuesta Base

Respuesta de Error

Respuesta Paginada

Validación y Errores

Manejo de Errores de Validación

Los modelos de Pydantic validan automáticamente los datos:

from datadis_python.models.consumption import ConsumptionData
from pydantic import ValidationError

try:
    # Datos inválidos
    consumo = ConsumptionData(
        cups="",  # CUPS vacío (inválido)
        date="fecha-incorrecta",  # Formato incorrecto
        time="25:70",  # Hora inválida
        consumptionKWh="no-es-numero"  # Tipo incorrecto
    )
except ValidationError as e:
    print("Errores de validación:")
    for error in e.errors():
        print(f"- {error['loc']}: {error['msg']}")

Conversión Automática de Tipos

Pydantic intenta convertir tipos automáticamente cuando es posible:

from datadis_python.models.consumption import ConsumptionData

# Los números como string se convierten automáticamente
consumo = ConsumptionData(
    cups="ES1234000000000001JN0F",
    date="2024/01/15",
    time="01:00",
    consumptionKWh="2.5",  # String que se convierte a float
    obtainMethod="Real"
)

print(type(consumo.consumption_kwh))  # <class 'float'>
print(consumo.consumption_kwh)        # 2.5

Configuración del Modelo

Los modelos incluyen configuración específica:

# Todos los modelos permiten usar alias
data = {
    "consumptionKWh": 2.5  # Nombre de la API
}

consumo = ConsumptionData(
    cups="ES1234000000000001JN0F",
    date="2024/01/15",
    time="01:00",
    obtainMethod="Real",
    **data
)

# Acceso con nombre pythónico
print(consumo.consumption_kwh)  # 2.5

Serialización Avanzada

Exportar a JSON

import json
from datadis_python.models.consumption import ConsumptionData

consumo = ConsumptionData(
    cups="ES1234000000000001JN0F",
    date="2024/01/15",
    time="01:00",
    consumptionKWh=2.5,
    obtainMethod="Real"
)

# Exportar a JSON
json_data = consumo.model_dump_json(indent=2)
print(json_data)

# Cargar desde JSON
consumo_cargado = ConsumptionData.model_validate_json(json_data)

Filtrar Campos

# Incluir solo ciertos campos
data = consumo.model_dump(include={'cups', 'consumption_kwh'})

# Excluir campos
data = consumo.model_dump(exclude={'time'})

# Usar alias en la salida
data = consumo.model_dump(by_alias=True)

Creación de Modelos Personalizados

Si necesitas extender los modelos:

from datadis_python.models.consumption import ConsumptionData
from pydantic import computed_field

class ConsumptionExtended(ConsumptionData):
    """Modelo extendido con campos calculados"""

    @computed_field
    @property
    def consumption_wh(self) -> float:
        """Consumo en Wh en lugar de kWh"""
        return self.consumption_kwh * 1000

    @computed_field
    @property
    def fecha_completa(self) -> str:
        """Fecha y hora combinadas"""
        return f"{self.date} {self.time}"

# Uso
consumo = ConsumptionExtended(
    cups="ES1234000000000001JN0F",
    date="2024/01/15",
    time="01:00",
    consumptionKWh=2.5,
    obtainMethod="Real"
)

print(f"Consumo: {consumo.consumption_wh} Wh")
print(f"Timestamp: {consumo.fecha_completa}")

Mejores Prácticas

  1. Validación temprana: Usa los modelos inmediatamente después de recibir datos

  2. Type hints: Aprovecha las anotaciones de tipo para mejor desarrollo

  3. Serialización: Usa model_dump() para convertir a diccionarios

  4. Manejo de errores: Captura ValidationError para datos inválidos

  5. Documentación: Los docstrings están disponibles en tiempo de ejecución