User Guide

Unavailability Additional Information API

 

 

 

 

Version 1.2

Effective date: 8 February 2019

 

 

 

 

 

 

 

 

 

 

 

 

Contents

1       Document history 3

2       Introduction_ 4

2.1      Definitions 4

2.2      Technical support 5

3       Functional description of the Unavailability Additional Information API  6

3.1      General description. 6

3.2      Prerequisites for using the APIs 6

3.2.1   Data confidentiality. 6

3.2.2   Termination. 6

3.3      “transmission_network_unavailabilities” resource. 6

3.4      "generation unavailabilities” resource. 6

4       Accessing the API 7

5       Resource exposed by the “Unavailability Additional Information” API 8

5.1      Transmission_network_unavailabilitiesresource. 8

5.1.1   GET /transmission_network_unavailabilities. 8

5.1.1.1     Call methods. 8

5.1.1.2     Inputs. 9

5.1.1.3     Outputs. 11

5.1.1.4     Control rules. 14

5.1.1.5     Error codes. 16

5.2      Generation unavailabilities resource. 17

5.2.1   GET /generation_unavailabilities. 17

5.2.1.1     Call methods. 17

5.2.1.2     Inputs. 18

5.2.1.3     Outputs. 19

5.2.1.4     Control rules. 22

5.2.1.5     Error codes. 23

6       Details of errors 24

6.1      Functional errors 26

6.1.1   transmission network unavailabilities. 26

6.1.2   generation_unavailabilities. 27

6.2      Technical errors 29

7       Appendices 30

7.1      Sample files 30

END OF DOCUMENT_ 30

 

Version

Date

Notes

1.0

08/04/2016

First release

1.1

23/02/2018

User Guide General Rework

1.2

08/02/2019

Error codes for the "transmission_network_unavailabilities" resource

-       UNADINFO_TRANSNETUN_F05 deprecated,

-       initial errors UNADINFO_TRANSNETUN_F05 and UNADINFO_TRANSNETUN_F06 shifted to "…F06" and "…F07"

 

Error codes for the "generation_unavailabilities" resource

-       UNADINFO_GENUN_F05 inserted,

-       initial errors UNADINFO_GENUN_F05 and UNADINFO_GENUN_F06 shifted to "…F06" and "…F07"

 

 

 

 

This document describes version 1 of the Unavailability Additional Information API that RTE provides for its Clients in order to expose the following data:

·         components making up the RTE network experiencing periods of scheduled or accidental unavailability which have an impact of more than 100 MW on NTC (Net Transfer Capacity) 

·         production facilities experiencing periods of scheduled or accidental unavailability which have an impact of more than 100 MW on NTC 

For the moment, this API cannot be used to retrieve data about other information which impacts the market.

 

Reference documents

 

Short reference

Name of the document

Complete reference

[R1]

Terms of use for RTE’s APIs

Access Link

 

2.1     Definitions

The terms used in this User Guide (the first letters of which are always capitalised) are defined below. Otherwise, their definitions are given in the General Conditions of Use [R1]:

 

 

API

Application Programming Interface

Authentification

Protection Mode for ensuring that the identity of the Sender or Receiver has been checked by RTE, and that they are authorised to access the IT system and use the Applications.

Sender

Party which sends a Message.

Message 

Set of computer data used to transmit information, structured in accordance with a particular order that is specified in the User Guide. A Message can be sent by the User or by RTE.

Operation

An operation is the way in which the client interacts with the API's resource. An HTTP verb is always used (for example: GET for reading)

Party or Parties

Within the framework of the User Guide, these terms refer to either RTE or the User individually, or to both RTE and the User collectively.

Receiver

Party which receives the Sender's Message.

Resource

A resource is the data in relation to which the client application interacts.

URL

Uniform Resource Locator: character string based on a specific format used to locate a resource on a network and specify what protocol should be used on this resource.

User(s) 

Legal entity which has agreed to RTE’s General Terms and Conditions for Using APIs and which has been granted access to RTE’s IT system for the purposes of using the APIs it has made available.

2.2     Technical support

In the event of difficulties accessing or using an API, Users can contact the telephone support services provided by RTE in accordance with the technical conditions detailed in the General Terms and Conditions of Use.

 

 

 

3.1     General description

The service provided by this API can be used to obtain the following data:

·         components making up the RTE network experiencing periods of scheduled or accidental unavailability which have an impact of more than 100 MW on NTC (Net Transfer Capacity) 

·         production facilities experiencing periods of scheduled or accidental unavailability which have an impact of more than 100 MW on NTC 

For the moment, this API cannot be used to retrieve data about other information which impacts the market.

3.2     Prerequisites for using the APIs

 

The Unavailability Additional Information API is for stakeholders operating on the electricity market and the general public. However, users of the API will need to create an account on RTE's digital portal. Once they have set up an account, they'll be able to get their Oauth 2.0 credentials. These credentials are then required whenever calls are made to the APIs.

3.2.1   Data confidentiality

 

The information contained in the Messages may not be used for any purpose other than the ones described in the General Terms and Conditions of Use [R1].

3.2.2   Termination

 

A subscription to an API is automatically terminated when the user deletes their account on RTE's digital portal.

Should the user wish to cease using an API without terminating their subscription, they simply need to stop sending calls to it.

3.3     transmission_network_unavailabilities” resource

 

This service is for getting data about periods of network unavailability. The data received is in the form of a list of periods of scheduled and accidental unavailability of the components making up the RTE network which may impact exchange capacities at borders.

3.4    "generation unavailabilities” resource

 

This service is for getting data about periods of generation unavailability. The data received is information about the unavailability of power plants and generating facilities in mainland France (excluding Corsica).

4         Accessing the API

 

The REST protocol is used to access the API described in this document.

As is the case for all of the APIs provided by RTE, accessing and using them are subject to the provisions of the General Terms and Conditions of Use [R1].

The authorisation method for accessing the APIs is the OAuth framework, the applications of which are described in the FAQs.

 

5      Resource exposed by the “Unavailability Additional Information” API

5.1     Transmission_network_unavailabilitiesresource

5.1.1               GET /transmission_network_unavailabilities

5.1.1.1               Call methods

The resource is exposed in the following way:

 

Exposure

REST / JSON

Method

GET

Resource URL

https://digital.iservices.rte-france.com/open_api/unavailability_additional_information/v1/transmission_network_unavailabilities?start_date=<valeur>&end_date=<valeur>&status=<valeur(s)>&date_type=<valeur>&start_date=<valeur>&end_date=<valeur>&country_eic_code=<valeur>

URL sandbox (1)

https://digital.iservices.rte-france.com/open_api/unavailability_additional_information/v1/sandbox/transmission_network_unavailabilities

 

(1) The sandbox does not take the input parameters into account

 

Call recommendations

This resource is for retrieving information about the unavailability of networks created/updated/cancelled during the day. For nominal use, the period's fields do not need to be filled in. The service automatically returns data received during the current day. Cf. TNUN-RG01. The search can:

·         either focus on all borders and all statuses if none of the input fields are filled in

·         or a list of statuses and/or a list of borders can be specified. For each of the countries on the list, the operation returns the export and import.

The data available is from 18/03/2014 onwards. Data for periods before this date is not available.

 

It is advisable to make one call to this service per hour, and not to exceed a period of 366 days per call.

 

5.1.1.2  Inputs

 

NAME

CARD

DESCRIPTION

TYPE

VALUES / FORMAT

RULES

start_date

0..1

Forecast search start date

date

YYYY-MM-DDThh:mm:sszzzzzz

TNUN-RG01

TNUN-RG02

TNUN-RG03

TNUN-RG04

TNUN-RG08

end_date

0..1

Forecast search end date

date

 

YYYY-MM-DDThh:mm:sszzzzzz

TNUN-RG01

TNUN-RG02

TNUN-RG03

TNUN-RG04

TNUN-RG08

status

0..2

Status of unavailability

enum

Possible values:

CANCELLED

FINISHED

TNUN-RG01

TNUN-RG07

TNUN-RG08

TNUN-RG09

country_eic_code

0..6

EIC code of the country sought

enum

Possible values:
10YCB-GERMANY--8

10YGB----------A

10YBE----------2

10YIT-GRTN-----B

10YES-REE------0

10YCH-SWISSGRIDZ

TNUN-RG01

TNUN-RG06

TNUN-RG08

TNUN-RG09

date_type

0..1

Type for specifying on what date the search is to be performed

enum

Possible values:

APPLICATION_DATE

UPDATED_DATE

TNUN-RG01

TNUN-RG02

TNUN-RG03

TNUN-RG04

TNUN-RG08

1 Dates used as parameters can be expressed in any time zone

 

Call examples:

Without parameters

 

URL:

GET  /open_api/unavailability_additional_information/v1/transmission_network_unavailabilities

HTTP/1.1

Headers:

Host: digital.iservices.rte-france.com

Authorization: Bearer CNAPbfmg7GjvtqTTlKqPm8ykP6R8YJFfJPnyjqW8p1v2PW2UX6bF8z

Body:

 

 

With all parameters

 

URL:

GET /open_api/unavailability_additional_information/v1/transmission_network_unavailabilities? status=FINISHED&date_type=APPLICATION_DATE&start_date=2015-09-01T00:00:00%2B02:00&end_date=2015-10-01T00:00:00%2B02:00&country_eic_code=10YCB-GERMANY--8

HTTP/1.1

Headers:

Host: digital.iservices.rte-france.com

Authorization: Bearer CNAPbfmg7GjvtqTTlKqPm8ykP6R8YJFfJPnyjqW8p1v2PW2UX6bF8z

Body:

5.1.1.3Outputs

 

NAME

CARD

DESCRIPTION

transmission_network_unavailabilities

1..1

Table of unavailabilities {JSON} containing n occurrences.

It is structured as shown below:

0..n

NAME

CARD

DESCRIPTION

TYPE

VALUES / FORMAT

RULES

identifier

1..1

Unavailability identifier

string

_

TNUN-RG05

version

1..1

version

string

_

TNUN-RG05

creation_date

1..1

Date and time the unavailability was created

date

YYYY-MM-DDThh:mm:sszzzzzz1

_

start_date

1..1

Unavailability start date

date

YYYY-MM-DDThh:mm:sszzzzzz1

_

end_date

1..1

Unavailability end date

date

YYYY-MM-DDThh:mm:sszzzzzz1

_

updated_date

1..1

Unavailability update date

date

YYYY-MM-DDThh:mm:sszzzzzz1

_

type

1..1

Type of unavailability

enum

Possible values:

PLANNED_MAINTENANCE
FORCED_UNAVAILABILITY

_

impacted_asset

1..1

Infrastructure impacted.

Table {JSON} structured as shown below:

 

1..1

NAME

CARD

DESCRIPTION

TYPE

VALUES / FORMAT

RULES

 

eic_code

1..1

Production unit's EIC code

string

_

_

 

name

1..1

Name of the infrastructure impacted

string

_

_

 

 

 

 

type

1..1

Type of the infrastructure impacted

enum

Possible values:

DC_LINK
AC_LINK
SUBSTATION
TRANSFORMER

_

CARD

DESCRIPTION

TYPE

VALUES / FORMAT

RULES

reason

1..1

Cause of unavailability

string

_

_

status

0..1

Status of unavailability

enum

Possible values:

CANCELLED
FINISHED

_

values

 

1..1

Table of values {JSON} structured as shown below:

 

0..n

NAME

CARD

DESCRIPTION

TYPE

VALUES / FORMAT

RULES

sender_country_name

1..1

Name of sending country

enum

Possible values:

Belgium
England
France
Germany
Italy
Spain
Switzerland

_

receiver_country_name

1..1

 Name of receiving country

enum

Possible values:

Belgium
England
France
Germany
Italy
Spain
Switzerland

_

sender_country_eic_code

1..1

Receiving country's EIC code

enum

Possible values:

10YCB-GERMANY--8

10YGB----------A

10YBE----------2

10YIT-GRTN-----B

10YES-REE------0

10YCH-SWISSGRIDZ

_

receiver_country_eic_code

1..1

Receiving country's EIC code

enum

Possible values:

10YCB-GERMANY--8

10YGB----------A

10YBE----------2

10YIT-GRTN-----B

10YES-REE------0

10YCH-SWISSGRIDZ

_

start_date

1..1

Start time interval

date

YYYY-MM-DDThh:mm:sszzzzzz1

_

end_date

1..1

End time interval

date

YYYY-MM-DDThh:mm:sszzzzzz1

_

value

1..1

Data value

int

Integer

_

                             

1 The dates returned are expressed in French time (UTC + 2 hours in the summertime, UTC + 1 hour in the winter)

 

 

JSON format of the return:

GET  /open_api/unavailability_additional_information/v1/transmission_network_unavailabilities

 

HTTP/1.1 200 OK

{"transmission_network_unavailabilities": [

    {

      "start_date": "2015-10-16T17:00:00+02:00",

      "end_date": "2015-12-19T00:00:00+01:00",

      "type": "FORCED_UNAVAILABILITY",

      "identifier": "EC-OUSPIR-Indispo-1172",

      "version": "1",

      "creation_date": "2015-11-24T18:20:00+01:00",

      "updated_date": "2015-11-25T17:31:00+01:00",

      "impacted_asset": {

      "eic_code": "10T-FR-GB-000017",

      "name": "Mandarins-Sellindge 1",

      "type": "DC_LINK"

      },

      "reason": "Failure / Défaillance\n",

      "status": "FINISHED",

      "values": [

        {

          "start_date": "2015-10-16T17:00:00+02:00",

          "end_date": "2015-11-11T03:00:00+01:00",

          "sender_country_eic_code": "10YFR-RTE------C",

          "sender_country_name": "France",

          "receiver_country_eic_code": "10YGB----------A",

          "receiver_country_name": "England",

          "value": 1500

        },

        {

          "start_date": "2015-11-11T03:00:00+01:00",

          "end_date": "2015-11-11T08:00:00+01:00",

          "sender_country_eic_code": "10YFR-RTE------C",

          "sender_country_name": "France",

          "receiver_country_eic_code": "10YGB----------A",

          "receiver_country_name": "England",

          "value": 1000

        },

                .....

      ]

    },

    {...}

  ]

}

 

 

5.1.1.4 Control rules

Control rules for different input parameters:

 

input parameter

Description

Number

status

country_eic_code

date_type

start_date

end_date

 

empty

empty

empty

empty

empty

If no input parameter is given, the service returns the unavailability period published during the day, together with the network unavailability updates published during the day.

TNUN-RG01

empty

empty

filled in

filled in

filled in

If date_type is set to APPLICATION_DATE and thestart_date and end_date fields are filled in, the service returns all the versions of unavailability periods for which the start date and end date completely or partially include this period.

TNUN-RG02

If date_type is set to UPDATED_DATE and the start_date and end_date fields are filled in, the service only returns the versions of unavailability periods which have been updated during this period.

TNUN-RG03

empty

empty

filled in

empty

empty

If the start_date and end_date fields are not filled in and the date_type field is filled in, the date_type field is ignored.

TNUN-RG04

empty

empty

empty

filled in

filled in

If the start_date and end_date fields are filled in and the date_type field is not filled in, the date_type field is filled in by the system with the APPLICATION_DATE value.

empty

filled in

empty

empty

empty

If the country_eic_code field is filled in, the response only contains the unavailability periods which affect these borders.

If an Indipo1 unavailability impacts the German and Belgian borders, and if only the German border is requested as an input for the operation, indipo1 is returned to the calling application.

If an Indipo1 unavailability impacts the German and Belgian borders, an Indipo2 unavailability impacts the German border and an Indipo3 unavailability impacts the Belgian border. If as an input for the service, the German and Belgian borders are given, the service returns the 3 unavailabilities.

TNUN-RG06

filled in

empty

empty

empty

empty

If the status field is filled in, the response only contains the unavailabilities with the requested statuses.

TNUN-RG07

filled in

filled in

filled in

filled in

filled in

The status and country_eic_code fields, as well as date_type/start_date/end_date can all be filled in for the same query.

TNUN-RG08

If a value is duplicated in one of the listed parameters (status, country_eic_code, date_type), the Service only returns this value once.
For example, country_eic_code=10YES-REE------0,10YCH-SWISSGRIDZ,
10YES-REE------0 will return the same data as country_eic_code=10YES-REE------0,10YCH-SWISSGRIDZ

TNUN-RG09

 

 

Output control rules applied:

 

Number

Description

TNUN-RG05

The output data is sorted based on the identifier field, followed by the version field, from the most recent to the oldest

 

5.1.1.5 Error codes

 

The following table lists the error codes which may be returned when the resource is called.

Details of these errors are described in chapter 6 Details of errors.

 

Type of error

Error code

Details

Functional

UNADINFO_TRANSNETUN_F01

§6.1.1

Functional

UNADINFO_TRANSNETUN_F02

§6.1.1

Functional

UNADINFO_TRANSNETUN_F03

§6.1.1

Functional

UNADINFO_TRANSNETUN_F04

§6.1.1

Functional

UNADINFO_TRANSNETUN_F05

§6.1.1

Functional

UNADINFO_TRANSNETUN_F06

§6.1.1

Functional

UNADINFO_TRANSNETUN_F07

§6.1.1

Technical

401

§6.2

Technical

403

§6.2

Technical

404

§6.2

Technical

408

§6.2

Technical

413

§6.2

Technical

414

§6.2

Technical

429

§6.2

Technique

500

§6.2

Technical

503

§6.2

Technical

509

§6.2

 

 

5.2     Generation unavailabilities resource 5.2.1   GET /generation_unavailabilities

5.2.1.1  Call methods

 

The resource is exposed in the following way:

 

Exposure

REST / JSON

Method

GET

Resource URL

https://digital.iservices.rte-france.com/open_api/unavailability_additional_information/v1/generation_unavailabilities?status=<valeur>&date_type=<valeur> start_date=<valeur>&end_date=<valeur>

URL sandbox (1)

https://digital.iservices.rte-france.com/open_api/unavailability_additional_information/v1/sandbox/generation_unavailabilities

 

(1) The sandbox does not take the input parameters into account

 

Call recommendations

This operation is for retrieving information about the unavailability of generating facilities created/updated/cancelled during the day. For nominal use, the period's fields do not need to be filled in. The service automatically returns data received during the current day. Cf. GEUN-RG01. The search can:

·         either focus on all statuses if none of the input fields are filled in

·         or a list of statuses can be specified.

The data available is from 15/12/2010 onwards. Data for periods before this date is only available as archive files.

 

It is advisable to make one call to this service per hour, and not to exceed a period of 21 days per call.

 

 

 

5.2.1.2 Inputs

 

NAME

CARD

DESCRIPTION

TYPE

VALUES / FORMAT

RULES

start_date

0..1

Search start date

date

YYYY-MM-DDThh:mm:sszzzzzz1

GEUN-RG01

GEUN-RG02

GEUN-RG03

GEUN-RG07

end_date

0..1

Search end date

date

YYYY-MM-DDThh:mm:sszzzzzz1

GEUN-RG01

GEUN-RG02

GEUN-RG03

GEUN-RG07

Status

0..2

Status of unavailability

enum

Possible values:

CANCELLED

FINISHED

GEUN-RG01

GEUN-RG04

GEUN-RG07

GEUN-RG08

date_type

0..1

Type for specifying on what date the search is to be performed

enum

Possible values:

APPLICATION_DATE

UPDATED_DATE

GEUN-RG01

GEUN-RG02

GEUN-RG03

GEUN-RG07

GEUN-RG08

1 Dates used as parameters can be expressed in any time zone

 

Example:

Without parameters

 

URL:

GET  /open_api/unavailability_additional_information/v1/generation_unavailabilities

HTTP/1.1 200 OK

Headers:

Host: digital.iservices.rte-france.com

Authorization: Bearer CNAPbfmg7GjvtqTTlKqPm8ykP6R8YJFfJPnyjqW8p1v2PW2UX6bF8z

Body:

 

 

With all parameters

 

URL:

GET /open_api/unavailability_additional_information/v1/generation_unavailabilities? status=FINISHED&date_type=APPLICATION_DATE&start_date=2015-09-01T00:00:00%2B02:00&end_date=2015-10-01T00:00:00%2B02:00

HTTP/1.1 200 OK

Headers:

Host: digital.iservices.rte-france.com

Authorization: Bearer CNAPbfmg7GjvtqTTlKqPm8ykP6R8YJFfJPnyjqW8p1v2PW2UX6bF8z

Body:

 

 

5.2.1.3 Outputs

 

NAME

CARD

DESCRIPTION

generation_unavailabilities

1..1

Table of unavailabilities {JSON} containing n occurrences.

It is structured as shown below:

0..n

NAME

CARD

DESCRIPTION

TYPE

VALUES / FORMAT

RULES

identifier

1..1

Unavailability identifier

string

_

 

GEUN-RG05

version

1..1

version

string

_

GEUN-RG05

creation_date

1..1

Date and time the unavailability was created

date

YYYY-MM-DDThh:mm:sszzzzzz1

_

start_date

1..1

Unavailability start date

date

YYYY-MM-DDThh:mm:sszzzzzz1

_

end_date

1..1

Unavailability end date

date

YYYY-MM-DDThh:mm:sszzzzzz1

_

updated_date

1..1

Unavailability update date

date

YYYY-MM-DDThh:mm:sszzzzzz1

_

type

1..1

Type of unavailability

enum

Possible values:

PLANNED_MAINTENANCE
FORCED_UNAVAILABILITY

_

Production_type

1..1

Generating unit sector

enum

Possible values:
BIOMASS
FOSSIL_BROWN_COAL_LIGNITE
FOSSIL_COAL_DERIVED_GAS
FOSSIL_GAS
FOSSIL_HARD_COAL
FOSSIL_OIL
FOSSIL_OIL_SHALE
FOSSIL_PEAT
GEOTHERMAL
HYDRO_PUMPED_STORAGE
HYDRO_RUN_OF_RIVER_AND_POUNDAGE
HYDRO_WATER_RESERVOIR
MARINE
NUCLEAR
OTHER_RENEWABLE
SOLAR
WASTE
WIND_OFFSHORE
WINF_ONSHORE
OTHER

_

unit

1..1

Unité de production

Tableau {JSON} contenant 1 occurrence, structuré comme suit :

 

1..1

NAME

CARD

DESCRIPTION

TYPE

VALUES / FORMAT

RULES

 

eic_code

1..1

Unit's EIC code

string

_

_

 

name

1..1

Unit's name

string

_

_

 

 

 

 

type

1..1

Unit's type

enum

Possible values:

PRODUCTION_UNIT

GENERATION_UNIT

_

Installed_capacity

1..1

Unit’s rated output

int

Entier numérique

_

CARD

DESCRIPTION

TYPE

VALUES / FORMAT

RULES

reason

0..1

Cause of unavailability

string

_

_

status

0..1

Status of unavailability

enum

Possible values:

CANCELLED
FINISHED

_

values

 

1..1

Table of values {JSON} structured as shown below:

 

1..n

NAME

CARD

DESCRIPTION

TYPE

VALUES / FORMAT

RULES

start_date

1..1

Start date of the period for which the value is expressed

date

YYYY-MM-DDThh:mm:sszzzzzz1

GEUN-RG06

end_date

1..1

End date of the period for which the value is expressed

date

YYYY-MM-DDThh:mm:sszzzzzz1

GEUN-RG06

value

1..1

Remaining power available

int

Integer

_

                             

1 The dates returned are expressed in French time (UTC + 2 hours in the summertime, UTC + 1 hour in the winter)

JSON format of the return:

GET  /open_api/unavailability_additional_information/v1/generation_unavailabilities

HTTP/1.1 200 OK

{"generation_unavailabilities": [

    {

      "identifier": "EC-EDF-05470-EDF-T-00010021",

      "version": "5",

      "creation_date": "2014-12-17T04:22:00+01:00",

      "start_date": "2016-03-19T00:00:00+01:00",

      "end_date": "2016-03-31T02:42:00+02:00",

      "type": "PLANNED_MAINTENANCE",

      "production_type": "NUCLEAR",

      "unit": {

      "eic_code": "17W100P100P0130W",

       "name": "FR-NU-GRAV5T_1",

       "type": "GENERATING_UNIT",

       "installed_capacity": 910

      },

      "reason": "Foreseen Maintenance / Maintenance prévue",

      "status": [],

      "values": [

        {

          "updated_date": "2016-01-13T10:25:00+01:00",

          "value": 0

        }

      ]

    },

        .....

  ]

}

 

 

 

5.2.1.4 Control rules

Control rules for different input parameters:

 

input parameter

Description

Number

status

date_type

start_date

end_date

empty

empty

empty

empty

If no input parameter is given, the service returns the unavailability period published during the day, together with the generating facility unavailability updates published during the day.

GEUN-RG01

empty

filled in

filled in

filled in

If date_type is set to APPLICATION_DATE and thestart_date and end_date fields are filled in, the service returns all the versions of unavailability periods for which the start date and end date completely or partially include this period.

GEUN-RG02

If date_type is set to UPDATED_DATE and the start_date and end_date fields are filled in, the service only returns the versions of unavailability periods which have been updated during this period.

GEUN-RG03

filled in

empty

empty

empty

If the status field is filled in, the response only contains the unavailabilities with the requested statuses.

GEUN-RG04

filled in

filled in

filled in

filled in

The status field, as well as date_type/start_date/end_date can all be filled in for the same query.

GEUN-RG07

If a value is duplicated in one of the listed parameters (status, date_type), the Service only returns this value once.

GEUN-RG08

 

Output control rules applied:

 

Number

Description

GEUN-RG05

The output data is sorted based on the identifier field, followed by the version field, from the most recent to the oldest

GEUN-RG06

In the value structure, the values/start_date and values/end_date fields are only filled in when the power plant or generating facility are not unavailable all the time.

 

5.2.1.5 Error codes

 

The following table lists the error codes which may be returned when the resource is called.

Details of these errors are described in chapter 6 Details of errors.

 

Type of error

Error code

Details

Functional

UNADINFO_GENUN_F01

§6.1.2

Functional

UNADINFO_GENUN_F02

§6.1.2

Functional

UNADINFO_GENUN_F03

§6.1.2

Functional

UNADINFO_GENUN_F04

§6.1.2

Functional

UNADINFO_GENUN_F05

§6.1.2

Functional

UNADINFO_GENUN_F06

§6.1.2

Functional

UNADINFO_GENUN_F07

§6.1.2

Technical

401

§6.2

Technical

403

§6.2

Technical

404

§6.2

Technical

408

§6.2

Technical

413

§6.2

Technical

414

§6.2

Technical

429

§6.2

Technique

500

§6.2

Technical

503

§6.2

Technical

509

§6.2

 

 

 
6      Details of errors

 

The diagram below shows the codes returned to the API's User based on the sequencing of calls.

This paragraph details the errors that are common to all of the API's resources. As such, it does not describe the request errors (HTTP 400 code). These errors are described resource by resource in the corresponding paragraph.

 

In the event of an error encountered during the authentication phase (while validating the username and password), an HTTP 401 “unauthorised" code is returned to the caller.

The second stage involves checking that the User has not exceeded the maximum number of calls authorised for the operation. In the event of the maximum number being exceeded, the caller is informed by an HTTP 429 code. In such cases, the response from the server will contain a "Retry-After:" header giving the time (in seconds) that the client will need to wait before resubmitting their request.

The third stage involves checking that the application has been created/authorised to access the VESPA technical platform. Otherwise, the caller is informed by an HTTP 403 "forbidden" code.

The fourth stage involves checking that the application has actually subscribed to the API. Otherwise, the caller is informed by an HTTP 403 "forbidden" code.

The fifth stage involves accessing RTE’s resources. Various functional errors may occur. These are communicated to the User as JSON errors by an HTTP 400 code.

 

In the event of a technical incident upon the request treatment the caller is informed by an HTTP 500 code. 

JSON structure:

 

{

  "error": "short_name, error's explicit description",

  "error_description": “long name, readable by a user",

  "error_uri": "URI to the user guide on the VESPA technical platform or the FAQ/documentation on VESPA’s web portal"

   "error_details": {

        "transaction_id": "unique call identifier, useful in the event of an incident"

}

 

}

 

·         The short description ("error") is a code which enables the calling application to automatically process error messages. It is represented by a series of words separated by “_”.

·         The long description ("error description") is a description enabling users to understand the source of the error more precisely. This name needs to be approved by the business line so as to ascertain that it is explicit enough.

·         The URI to the user guide is present so as to provide more explanations depending on the API called.

·         The transaction_id field: provides a unique call identifier. This identifier can be communicated to RTE’s support services if there is an incident.

 

 

6.1        Functional errors 6.1.1   transmission network unavailabilities

 

The table below lists the functional errors returned by the resource for an error in a request (HTTP 400 code):

 

UNADINFO_TRANSNETUN_F01

RG

This error is generated if either of the start_date and end_date parameters are passed on their own.

Message

If one of the fields "start_date" or "end_date" is used, the two fields are mandatory. Please used either fields or neither.

Call example
 

GET open-api/unavailability_additional_information/v1/transmission_network_unavailabilities?start_date=2015-06-01T00:00:00%2B02:00

UNADINFO_TRANSNETUN_F02

RG

This error is generated if the start_date parameter is more recent than the end_date parameter.

Message

The field "start_date" in the API input is more recently than the field "end_date". Please correct the values of these fields

Call example
 

GET open-api/unavailability_additional_information/v1/transmission_network_unavailabilities?start_date=2015-06-02T00:00:00%2B02:00&end_date=2015-06-01T00:00:00%2B02:00

UNADINFO_TRANSNETUN_F03

RG

This error is generated if the period requested is longer than 366 days.

Message

The API does not provide feedback on such a long period in one call. To retrieve all the data please make it with severals calls to the API.

Call example
 

GET open-api/unavailability_additional_information/v1/transmission_network_unavailabilities?start_date=2014-06-01T00:00:00%2B02:00&end_date=2015-07-02T00:00:00%2B02:00

UNADINFO_TRANSNETUN_F04

RG

This error is generated if the end_date field is greater than D+1 relative to the system date and the date_type field’s value is set to “UPDATED_DATE”.

Message

The value of \"end_date\" field is incorrect. It is not possible to recover data to this term.

Call example
 

GET open_api/unavailability_additional_information/v1/transmission_network_unavailabilities?start_date=2016-01-01T00:00:00%2B01:00&end_date=2016-01-20T00:00:00%2B01:00&date_type=UPDATED_DATE

UNADINFO_TRANSNETUN_F05

RG

n/a

Message

n/a

Call example
 

n/a

UNADINFO_TRANSNETUN_F06

RG

This error is generated if the start_date or end_date are not in the expected format.

Message

One of the dates in the API input does not follow the format described in the user guide. Please verify compliance with the format for each field.

Call example
 

GET open_api/unavailability_additional_information/v1/transmission_network_unavailabilities?start_date=2015-06-01&end_date=2015-06-01

UNADINFO_TRANSNETUN_F07

RG

If the date_type and/or status and/or country_eic_code fields do not contain one of the expected values, the service generates this error.

Message

One of the enumerated field does not match with the list of expected values. Please verify compliance with the format for each field.

Call example
 

GET open_api/unavailability_additional_information/v1/transmission_network_unavailabilities?status=ABORTED

 

6.1.2   generation_unavailabilities

 

The table below lists the functional errors returned by the resource for an error in a request (HTTP 400 code):

 

UNADINFO_GENUN_F01

RG

This error is generated if either of the start_date and end_date parameters are passed on their own.

Message

If one of the fields "start_date" or "end_date" is used, the two fields are mandatory. Please used either fields or neither.

Call example
 

GET open-api/unavailability_additional_information/v1/generation_unavailabilities?start_date=2015-06-01T00:00:00%2B02:00

UNADINFO_GENUN_F02

RG

This error is generated if the start_date parameter is more recent than the end_date parameter.

Message

The field "start_date" in the API input is more recently than the field "end_date". Please correct the values of these fields

Call example
 

GET open-api/unavailability_additional_information/v1/generation_unavailabilities?start_date=2015-06-02T00:00:00%2B02:00&end_date=2015-06-01T00:00:00%2B02:00

UNADINFO_GENUN_F03

RG

This error is generated if the period requested is longer than 21 days.

Message

The API does not provide feedback on such a long period in one call. To retrieve all the data please make it with severals calls to the API.

Call example
 

GET open-api/unavailability_additional_information/v1/generation_unavailabilities?start_date=2014-06-01T00:00:00%2B02:00&end_date=2015-07-02T00:00:00%2B02:00

UNADINFO_GENUN_F04

RG

This error is generated if the end_date field is greater than D+1 relative to the system date and the date_type field’s value is set to “UPDATED_DATE”.

Message

The value of \"end_date\" field is incorrect. It is not possible to recover data to this term.

Call example
 

GET open_api/unavailability_additional_information/v1/generation_unavailabilities?start_date=2016-01-01T00:00:00%2B01:00&end_date=2016-01-20T00:00:00%2B01:00&date_type=UPDATED_DATE

UNADINFO_GENUN_F05

RG

The period between start_date and end_date must cover at least one whole calendar day

Message

The period filled by fields \"start_date\" and \"end_date\" is too short to return values. Please check the user guide to verify the minimum period for this API.

Call example
 

GET open_api/unavailability_additional_information/v1/generation_unavailabilities?start_date=2015-06-01T12:00:00+02:00&end_date=2015-06-02T20:00:00+02:00

UNADINFO_GENUN_F06

RG

This error is generated if the start_date or end_date are not in the expected format.

Message

One of the dates in the API input does not follow the format described in the user guide. Please verify compliance with the format for each field.

Call example
 

GET open_api/unavailability_additional_information/v1/generation_unavailabilities?start_date=2015-06-01&end_date=2015-06-01

UNADINFO_GENUN_F07

RG

If the date_type and/or status fields do not contain one of the expected values, the service generates this error.

Message

One of the enumerated field does not match with the list of expected values. Please verify compliance with the format for each field.

Call example
 

GET open_api/unavailability_additional_information/v1/generation_unavailabilities?status=ABORTED

 

 

 

 

6.2     Technical errors

401

HTTP code

401

Message

Unauthorized

Description

Error generated when authentication has failed

403

HTTP code

403

Message

Forbidden

Description

Error generated if the caller is not authorised to call the resource

404

HTTP code

404

Message

Not Found

Description

The resource called does not exist or no page was found

408

HTTP code

408

Message

Request Time-out

Description

Error generated when the service called does not reply or when the service called times out (HTTP 408).

413

HTTP code

413

Message

Request Entity Too Large

Description

The size of the response to the request is greater than 7 MB

414

HTTP code

414

Message

Request-URI Too Long

Description

The URI sent by the caller is longer than 2048 characters.

429

HTTP code

429

Message

Too Many Requests

Description

The maximum number of calls has been made in a given period of time.

500

HTTP code

500

Message

Internal Server Error

Description

All other technical errors.

(This error is accompanied by a JSON message with an error_code and error_description field)

503

HTTP code

503

Message

Service Unavailable

Description

Error generated during maintenance (HTTP 503).

509

HTTP code

509

Message

Bandwidth Limit Exceeded.

Description

The total number of client requests has reached the maximum limit.

 

7      Appendices
7.1     Sample files

Once the User is logged on the Data Portal, sample files (including API responses) are available online on the API description page.