REData API

REData API

The REData API provides a simple REST service to allow third parties to access the backend data used in the REData application. By using this API, you will be able to retrieve data from the REData widgets and use them for your own purposes.

The use of this service is pretty simple. Only GET requests are allowed since the purpose of this API is to provide data related to the REData app. Each widget is set up by a series of indicators which provide data related to a particular category. The detailed format of the URI can be found below.

Content index:

Content  
1. API requests
  1.1 Request overview
  1.2 URI definition
  1.3 Query definition
  1.4 Example requests
2. API responses
  2.1 Successful responses
  2.2 Error responses

1. API requests

Returns a specific widget filtered by a date range, time aggregation and geo ids.

1.1 Request overview

GET /{lang}/datos/{category}/{widget}?[query]

Parameters:

Param Description
lang
Defines the response language.
category
Defines the general category.
widget
Defines the particular widget to be retrieved.
query
Set of parameters used to filter the requested data.

Headers:

Accept: application/json;
Content-Type: application/json
Host: apidatos.ree.es

1.2 URI definition

The accepted values for each parameter are defined in the table below:

lang category widget
es
 
 
en
 
 
 
balance
balance-electrico
 
demanda
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
 
generacion
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
 
intercambios
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
 
transporte
energia-no-suministrada-ens
 
 
indice-indisponibilidad
 
 
tiempo-interrupcion-medio-tim
 
 
kilometros-lineas
 
 
indice-disponibilidad
 
 
numero-cortes
 
 
ens-tim
 
 
indice-disponibilidad-total
 
mercados
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

1.3 Query definition

Query parameters are described below:

Param Description
start_date
Defines the starting date in ISO 8601 format:
YYYY-MM-DDTHH:MM
end_date
Defines the ending date in ISO 8601 format:
YYYY-MM-DDTHH:MM
time_trunc
Defines the time aggregation of the requested data. Valid values are:
  • hour
  • day
  • month
  • year
geo_trunc
(Optional) Defines the geographical scope of the requested data. Currently the only allowed value is:
electric_system
geo_limit
(Optional) Defines the electrical system of the requested data. Valid values are:
  • peninsular
  • canarias
  • baleares
  • ceuta
  • melilla
  • ccaa
geo_ids
(Optional) Defines the ID of the previously defined autonomous community/electrical system.

The optional parameters are not mandatory, however, if you wish to make a request for a particular region you must send all the above parameters in the request. If no geo params are sent, the default region will be either national or peninsular (it will depend on the requested widget).

The table below defines the geo_ids of each electrical system/autonomous community:

Region geo_limit geo_id
peninsular
peninsular 8741
canarias
canarias 8742
baleares
baleares 8743
ceuta
ceuta 8744
melilla
melilla 8745
Andalucía
ccaa 4
Aragón
ccaa 5
Cantabria
ccaa 6
Castilla la Mancha
ccaa 7
Castilla y León
ccaa 8
Cataluña
ccaa 9
País Vasco
ccaa 10
Principado de Asturias
ccaa 11
Comunidad de Ceuta
ccaa 8744
Comunidad de Melilla
ccaa 8745
Comunidad de Madrid
ccaa 13
Comunidad de Navarra
ccaa 14
Comunidad Valenciana
ccaa 15
Extremadura
ccaa 16
Galicia
ccaa 17
Islas Baleares
ccaa 8743
Islas Canarias
ccaa 8742
La Rioja
ccaa 20
Región de Murcia
ccaa 21

1.4 Example requests

Below are listed a few example requests combining several query parameters:

  • Requesting the daily balance widget for January (default geo_limit; Spanish):
    https://apidatos.ree.es/es/datos/balance/balance-electrico?start_date=2019-01-01T00:00&end_date=2019-01-31T23:59&time_trunc=day
  • Requesting the monthly general IRE widget for the year 2018 (peninsular geo_limit; English):
    https://apidatos.ree.es/en/datos/demanda/ire-general?start_date=2018-01-01T00:00&end_date=2018-12-31T23:59&time_trunc=month&geo_trunc=electric_system&geo_limit=peninsular&geo_ids=8741
  • Requesting the yearly generation structure widget between 2014 and 2018 (ccaa geo_limit; Castilla la Mancha; Spanish):
    https://apidatos.ree.es/es/datos/generacion/estructura-generacion?start_date=2014-01-01T00:00&end_date=2018-12-31T23:59&time_trunc=year&geo_trunc=electric_system&geo_limit=ccaa&geo_ids=7

2. API responses

The responses generated by the REData API are always served in JSON format following the JSONAPI standarts. The API will process the received request and will return either the requested widget or an error response message. In case the request was successfully processed a 200 status code will be returned, otherwise, an error status code will be present in the response.

2.1 Successful responses

The successful responses have structure similar to the following one:

      {
        "data": {
          "type": "WIDGET TYPE",
          "id": "WIDGET_ID",
          "attributes": {
            "title": "WIDGET NAME",
            "last-update": "2019-02-01T08:26:34.000+01:00",
            "description": "WIDGET DESCRIPTION",
          },
          "meta": {
            "cache-control": {
              "cache": "HIT",
              "expireAt": "2019-03-01T17:18:22"
            }
          }
        },
        "included": [
          {
            "type": "INDICATOR_1 TYPE",
            "id": "INDICADOR_1_ID",
            "groupId": null,
            "attributes": {
              "title": "INDICADOR_1 NAME",
              "description": "INDICADOR_1 DESCRIPTION",
              "color": "#2fa688",
              "type": "INDICADOR_1 TYPE",
              "magnitude": "INDICADOR_1 MAGNITUDE",
              "composite": false,
              "last-update": "2019-02-19T08:26:34.000+01:00",
              "values": [
                {
                  "value": 12345,
                  "percentage": "VALUE BETWEEN 0 AND 1",
                  "datetime": "2019-02-04T20:44:00.000+01:00"
                }
              ]
            },
           {
            "type": "INDICATOR_2 TYPE",
            "id": "INDICADOR_1_ID",
            "groupId": null,
            "attributes": {
      	       …
            }
          }
        ]
       }
      }
    

This example is meant to be orientative, mind that some of the attributes presented above may vary from widget to widget.

2.2 Error responses

In some cases, if the service is temporary unavailable or an incorrect request was sent, the API may return an error response. The error responses have the following structure:

    {
    	"errors":[
    		{
    			"code":XXX,
    			"status":"YYY",
    			"title":"ERROR TITLE",
    			"detail":"DETAILED ERROR"
    		}
    	]
    }
    

In case an error response was sent, the status code of the response will vary depending on the error. More specific details can be found under the 'detail' property of the JSON object returned.