openapi: 3.0.0
info:
  title: REData API
  version: 1.0.0
  description: >
    API REST pública para acceder a widgets de datos eléctricos de REData (Red Eléctrica de España).
servers:
  - url: https://apidatos.ree.es/{lang}/datos
    variables:
      lang:
        enum:
          - es
          - en
        default: en
paths:
  /{category}/{widget}:
    get:
      summary: Obtiene un widget específico
      parameters:
        - name: category
          in: path
          required: true
          description: Categoría de datos (p. ej. balance, demanda, generacion...)
          schema:
            type: string
            enum:
              - balance
              - demanda
              - generacion
              - intercambios
              - transporte
              - mercados
        - name: widget
          in: path
          required: true
          description: Nombre del widget a recuperar
          schema:
            type: string
            enum:
              - balance-electrico
              - evolucion
              - variacion-componentes
              - variacion-componentes-movil
              - ire-general
              - ire-general-anual
              - ire-general-movil
              - ire-industria
              - ire-industria-anual
              - ire-industria-movil
              - ire-servicios
              - ire-servicios-anual
              - ire-servicios-movil
              - ire-otras
              - ire-otras-anual
              - ire-otras-movil
              - demanda-maxima-diaria
              - demanda-maxima-horaria
              - perdidas-transporte
              - potencia-maxima-instantanea
              - variacion-demanda
              - potencia-maxima-instantanea-variacion
              - potencia-maxima-instantanea-variacion-historico
              - demanda-tiempo-real
              - variacion-componentes-anual
              - estructura-generacion
              - evolucion-renovable-no-renovable
              - estructura-renovables
              - estructura-generacion-emisiones-asociadas
              - evolucion-estructura-generacion-emisiones-asociadas
              - no-renovables-detalle-emisiones-CO2
              - maxima-renovable
              - potencia-instalada
              - maxima-renovable-historico
              - maxima-sin-emisiones-historico
              - francia-frontera
              - portugal-frontera
              - marruecos-frontera
              - andorra-frontera
              - lineas-francia
              - lineas-portugal
              - lineas-marruecos
              - lineas-andorra
              - francia-frontera-programado
              - portugal-frontera-programado
              - marruecos-frontera-programado
              - andorra-frontera-programado
              - enlace-baleares
              - frontera-fisicos
              - todas-fronteras-fisicos
              - frontera-programados
              - todas-fronteras-programados
              - energia-no-suministrada-ens
              - indice-indisponibilidad
              - tiempo-interrupcion-medio-tim
              - kilometros-lineas
              - indice-disponibilidad
              - numero-cortes
              - ens-tim
              - indice-disponibilidad-total
              - componentes-precio-energia-cierre-desglose
              - componentes-precio
              - energia-gestionada-servicios-ajuste
              - energia-restricciones
              - precios-restricciones
              - reserva-potencia-adicional
              - banda-regulacion-secundaria
              - energia-precios-regulacion-secundaria
              - energia-precios-regulacion-terciaria
              - energia-precios-gestion-desvios
              - coste-servicios-ajuste
              - volumen-energia-servicios-ajuste-variacion
              - precios-mercados-tiempo-real
              - energia-precios-ponderados-gestion-desvios-before
              - energia-precios-ponderados-gestion-desvios
              - energia-precios-ponderados-gestion-desvios-after
        - name: start_date
          in: query
          required: true
          description: Fecha/hora de inicio en ISO8601 (YYYY-MM-DDTHH:MM)
          schema:
            type: string
            format: date-time
        - name: end_date
          in: query
          required: true
          description: Fecha/hora de fin en ISO8601 (YYYY-MM-DDTHH:MM)
          schema:
            type: string
            format: date-time
        - name: time_trunc
          in: query
          required: true
          description: Agregación temporal
          schema:
            type: string
            enum: [hour, day, month, year]
        - name: geo_limit
          in: query
          required: false
          description: Define el sistema eléctrico de los datos solicitados.
          schema:
            type: string
            enum:
              - peninsular
              - canarias
              - baleares
              - ceuta
              - melilla
              - ccaa
        - name: geo_trunc
          in: query
          required: false
          description: Agregación geográfica (requiere geo_ids)
          schema:
            type: string
        - name: geo_ids
          in: query
          required: false
          description: IDs geográficos (sin/peninsular/regional) separados por comas
          schema:
            type: string
      responses:
        '200':
          description: Respuesta JSON con datos del widget (formato JSON:API)
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                  - included
                properties:
                  data: 
                    type: object
                    required:
                      - type
                      - id
                      - attributes
                    properties: 
                        type: 
                          type: string
                        id: 
                          type: string
                        attributes: 
                          type: object
                          required: 
                            - title
                            - last-update
                            - description
                          properties: 
                            title: 
                              type: string
                            last-update: 
                              type: string
                              format: date-time
                            description: 
                              type: string
                        meta: 
                          type: object
                          required: 
                            - cache-control
                          properties: 
                            cache-control:
                              required:
                                - cache
                                - expireAt
                              type: object
                              properties: 
                                cache: 
                                  type: string
                                expireAt: 
                                  type: string
                  included: 
                    type: array
                    items: 
                      type: object
                      required:
                        - type
                        - id
                        - groupId
                        - attributes
                      properties: 
                        type: 
                          type: string
                        id: 
                          type: string
                        groupId: 
                          type: string
                          format: nullable
                        attributes: 
                          type: object
                          required: 
                            - title
                            - description
                            - color
                            - type
                            - magnitude
                            - composite
                            - last-update
                            - values
                          properties: 
                            title: 
                              type: string
                            description: 
                              type: string
                            color: 
                              type: string
                            type: 
                              type: string
                            magnitude: 
                              type: string
                            composite: 
                              type: boolean
                            last-update: 
                              type: string
                              format: date-time
                            values: 
                              type: array
                              items: 
                                type: object
                                required: 
                                  - value
                                  - percentage
                                  - datetime
                                properties: 
                                  value: 
                                    type: integer
                                    format: int32
                                  percentage: 
                                    type: string
                                  datetime: 
                                    type: string
                                    format: date-time
                    
        '400':
          description: Parámetros inválidos
        '404':
          description: Widget o categoría no encontrados
        '500':
          description: Error del servidor
      security:
        - {}
components:
  securitySchemes: {}