User Guide

Exchange Schedule API

 

Version 1.2

Effective date: May 25, 2019

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

Contents

1       Document history_ 3

2       Introduction_ 4

2.1      Definitions 4

2.2      Technical support 5

3       Functional description of the Exchange Schedule 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      "Schedules" resource. 6

3.4      “Sum_rights_document” resource. 6

4       Accessing the API 7

5       Resource exposed by the “Exchange Schedule” API 8

5.1      "Schedules" resource. 8

5.1.1   GET /schedules. 8

5.1.1.1     Call methods. 8

5.1.1.2     Inputs. 9

5.1.1.3     Outputs. 10

5.1.1.4     Control rules. 12

5.1.1.5     Error codes. 14

5.2      Sum_rights_document resource. 15

5.2.1   GET / sum_rights_document 15

5.2.1.1     Call methods. 15

5.2.1.2     Inputs. 16

5.2.1.3     Outputs. 17

5.2.1.4     Control rules. 19

5.2.1.5     Error codes. 20

6       Details of errors_ 21

6.1      Functional errors 22

6.1.1   schedules. 22

6.1.2   sum_rights_document 23

6.2      Technical errors 25

7       Appendices_ 27

7.1      Sample Files 27

7.2      EIC code, ISO code and country name equivalents 27

7.3      Language – Translations of names 27

END OF DOCUMENT_ 27

1      Document history

 

Version

Date

Notes

1.2

22/02/2018

API created

2.1

25/05/2019

For the “schedules” resource:

Added the new country "England" in the input parameter "country_eic_code", as well as in the output parameters.

 

 

 


 

 

This document describes version 1 of the Exchange Schedule API that RTE provides for its Clients in order to obtain the following data:

·         long-term exchange schedules from annual and monthly, daily (D-1) and intra-daily (ID) allocations,

·         authorisations to schedule long-term capacities acquired in the long-term (annual and monthly auctions) before the opening of the daily market (D-1).

Reference documents

 

Short reference

Name of the document

Complete reference

[R1]

Terms of use for RTE’s APIs

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      Functional description of the Exchange Schedule API
3.1     General description

The exchange schedules represent commercial transits in MW that are the result of each cross-border capacity allocation.

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

·         long-term exchange schedules from annual and monthly, daily (D-1) and intra-daily (ID) allocations,

·         authorisations to schedule long-term capacities acquired in the long-term (annual and monthly auctions) before the opening of the daily market (D-1).

3.2     Prerequisites for using the APIs

The Exchange Schedule 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     "Schedules" resource

The exchange schedules represent commercial transits in MW that are the result of each cross-border capacity allocation. This service is for getting data about schedules for a range of different terms:

·         Long-term (LT)

·         Daily (D-1)

·         Intradaily (ID)

3.4     “Sum_rights_document” resource

The exchange schedules represent commercial transits in MW that are the result of each cross-border capacity allocation. This service is for getting data about authorisations to schedule in the long term.


 

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 FAQ topic - OAuth2 Hints.

 

 

 


 

5      Resource exposed by the “Exchange Schedule” API
5.1     "Schedules" resource 5.1.1    GET /schedules

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/exchange_schedule/v1/schedules? type=<valeur(s)>&start_date=<valeur>&end_date=<valeur>&country_eic_code=<valeur(s)>

Where the parameters type, start_date, end_date and country_eic_code are the same as those sent to the resource by the caller.

URL sandbox (1)

https://digital.iservices.rte-france.com/open_api/exchange_schedule/v1/sandbox/schedules

 

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

 

Call recommendations

 

The purpose of this operation is to be able to retrieve the exchange schedules. For nominal use, the period's fields do not need to be filled in. The service automatically returns the most up-to-date exchange schedules available. See SCH-RG01.

 

The search can:

 

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

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

 

It is advisable to make:

 

·         one call per day at around 10 AM for the long-term exchange schedules

·         two calls per day (the first at around 3 PM and the second at around 6 PM) for the daily exchange schedules

·         one call every hour at around Xxh40 for the intradaily exchange schedules

 

It is not possible to retrieve forecasts for periods of more than 31 days per call.

 

This service provides all data available after 20/06/2012. Data for periods before this date is only available as archive files.

 

5.1.1.2 Inputs

 

NAME

DESCRIPTION

CARD

TYPE

VALUES / FORMAT

RULES

start_date

Search start date

0..1

date
(2)

YYYY-MM-DDThh:mm:sszzzzzz

SCH-RG01

SCH-RG04

SCH-RG06

end_date

Search end date

0..1

date
(1) (2)

YYYY-MM-DDThh:mm:sszzzzzz

SCH-RG01

SCH-RG04

SCH-RG06

type

Term type sought

0..n

enum
(3)

Possible values:
LT
D-1
ID

SCH-RG01

SCH-RG04

SCH-RG07

SCH-RG11

country_eic_code

EIC code of the country sought

0..n

enum
(3)

Possible values (4):
10YCB-GERMANY--8

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

10YIT-GRTN-----B

10YES-REE------0

10YCH-SWISSGRIDZ

10YFR-RTE------C

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

SCH-RG01

SCH-RG02

SCH-RG03

SCH-RG04

SCH-RG08

SCH-RG11

(1) By convention, the end_date data is excluded from the search, data from the Service's response.
(2) If the start_date has passed, then the end_date should be passed as a parameter.
(3) Several of these values can be passed as a parameter, separated by a comma: . . .&field=VALUE1,VALUE2
(4) For more information, consult
information about how EIC codes, ISO codes and country labels correspond at the bottom of the page in the appendix.


NB:

– The Service’s field names are in English. Consult the appendix on "Language – Field name translations" at the bottom of the page.
– Consult the section on "
Expected formats" for details of the parameters' expected formats.

 

Call examples:

Without parameters

URL:

GET  /open_api/exchange_schedule/v1/schedules

HTTP/1.1

Headers:

Host: digital.iservices.rte-france.com

Authorization: Bearer CNAPbfmg7GjvtqTTlKqPm8ykP6R8YJFfJPnyjqW8p1v2PW2UX6bF8z

Body:

With all parameters

URL:

GET /open_api/exchange_schedule/v1/schedules?type=LT&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.3 Outputs

 

NAME

CARD.

DESCRIPTION

exchange_schedules

1..1

Table of values {JSON} containing 1 occurrence.

It is structured as shown below:

0..n

NAME

CARD.

DESCRIPTION

TYPE

VALUES / FORMAT

RULES

type

1..1

Term sought

enum

One of the following values:
LT
D-1
IJ

SCH-RG05

start_date

1..1

Start date

date

YYYY-MM-DDThh:mm:sszzzzzz

SCH-RG10

end_date

1..1

End date

date

YYYY-MM-DDThh:mm:sszzzzzz

SCH-RG10

sender_country_name

1..1

Name of sending country

enum

One of the following values:

Belgium

England

France

Germany

Italy

Spain

Switzerland

receiver_country_name

1..1

Name of receiving country

enum

One of the following values:

Belgium

England

France

Germany

Italy

Spain

Switzerland

sender_country_eic_code

1..1

Sending country's EIC code

enum

One of the following values:
10YBE----------2

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

10YFR-RTE------C

10YCB-GERMANY--8

10YIT-GRTN-----B

10YES-REE------0

10YCH-SWISSGRIDZ

receiver_country_eic_code

1..1

Receiving country's EIC code

enum

One of the following values:
10YBE----------2

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

10YFR-RTE------C

10YCB-GERMANY--8

10YIT-GRTN-----B

10YES-REE------0

10YCH-SWISSGRIDZ

values

1..1

One value per time interval. Table of values {JSON} structured as shown below:

0..n

NAME

CARD.

DESCRIPTION

TYPE

VALUES / FORMAT

RULES

start_date

1..1

Start time interval

date

YYYY-MM-DDThh:mm:sszzzzzz

SCH-RG09

end_date

1..1

End time interval

date

YYYY-MM-DDThh:mm:sszzzzzz

SCH-RG09

updated_date

1..1

Data update date

date

YYYY-MM-DDThh:mm:sszzzzzz

value

1..1

Data value

int

Integer

 

NB: This structure is duplicated and repeated for each type and each country.

 

JSON format of the return:

GET  /open_api/exchange_schedule/v1/schedules

HTTP/1.1 200 OK

 

{"schedules":[

          {

          "start_date":"2015-12-02T00:00:00+01:00",

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

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

          "sender_country_name":"France",

          "receiver_country_eic_code":"10YBE----------2",

          "receiver_country_name":"Belgium",

          "type":"ID",

          "updated_date":"2015-12-02T00:00:00+01:00"

          "values":[{"start_date":"2015-12-02T00:00:00+01:00", "end_date":"2015-12-02T01:00:00+01:00","updated_date":"2015-12-02T00:00:00+01:00","value":16}, ... ]

          }

          ...

]}

 

5.1.1.4 Control rules

 

Control rules for different input parameters:

 

input parameter

Description

Number

type

start_date

end_date

Country_eic_code

empty

empty

empty

empty

If no parameters are entered, for each of the terms and each of the borders, the Service will return the most up-to-date schedule.

SCH-RG01

empty

empty

empty

filled in

If the country_eic_code parameter is entered, the response only contains the import and export borders of the countries requested.

SCH-RG02

If the country_eic_code parameter is entered with the Central Western European zone's country code, the service returns the schedules for Germany and Belgium.

SCH-RG08

empty

filled in

filled in

empty

If the start_date and end_date parameters are passed, the Service returns the schedules of all borders for each term.

SCH-RG03

if for one of the terms and one of the borders, there is no data for the period requested, the Service returns the type, the start_date, the end_date, the sender_country_eic_code, the sender_country_name, the receiver_country_eic_code and the receiver_country_name without filling in the value fields.

SCH-RG06

filled in

empty

empty

empty

If the type parameter is entered, the response only contains the schedule types requested.

SCH-RG07

filled in

filled in

filled in

filled in

The 4 parameters can be passed to the Service to obtain the target data.

SCH-RG04

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

SCH-RG11

 

Output control rules applied:

 

Number

Description

SCH-RG05

The output data is sorted by type in the following order:

·         ID

·         D-1

·         LT

SCH-RG09

·         When changing from daylight saving time to summertime, the 2 AM to 3 AM value (French time) is empty.

·         When changing from summertime to daylight saving time, the 2 AM to 3 AM value (French time) appears twice

SCH–RG10

As the service's output, the schedules are returned as linked to calendar day.

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 5 Details of errors.

 

Type of error

Error code

Details

Functional

EXCHSCHED_SCHED_F01

§6.1.1

Functional

EXCHSCHED_SCHED_F02

§6.1.1

Functional

EXCHSCHED_SCHED_F03

§6.1.1

Functional

EXCHSCHED_SCHED_F04

§6.1.1

Functional

EXCHSCHED_SCHED_F05

§6.1.1

Functional

EXCHSCHED_SCHED_F06

§6.1.1

Functional

EXCHSCHED_SCHED_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

Technical

500

§6.2

Technical

503

§6.2

Technical

509

§6.2

5.2     Sum_rights_document resource 5.2.1   GET / sum_rights_document

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/exchange_schedule/v1/sum_rights_document?start_date=<valeur>&end_date=<valeur>&country_eic_code=<valeur(s)>

Where the start_date, end_date and country_eic_code parameters are the same as those sent to the resource by the caller.

URL sandbox (1)

https://digital.iservices.rte-france.com/open_api/exchange_schedule/v1/sum_rights_document /

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

 

Call recommendations

 

The purpose of this operation is to be able to retrieve the authorisations to schedule. For nominal use, the period's fields do not need to be filled in. The service automatically returns the most up-to-date authorisations to schedule available. See SRD-RG01.

 

The search can:

 

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

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

 

It is advisable to make one call per day at around 9:00 AM in order to retrieve the authorisations to schedule for the next day.

 

It is not possible to retrieve forecasts for periods of more than 155 days per call.

 

 

This service provides all data available after 01/01/2012. Data for periods before this date is only available as archive files.


 

5.2.1.2 Inputs

 

NAME

DESCRIPTION

CARD

TYPE

VALUES / FORMAT

RULES

start_date

Search start date

0..1

date
(2)

YYYY-MM-DDThh:mm:sszzzzzz

SRD-RG01

SRD-RG03

SRD-RG04

SRD-RG06

end_date

Search end date

0..1

date
(1) (2)

YYYY-MM-DDThh:mm:sszzzzzz

SRD-RG01

SRD-RG03

SRD-RG04

SRD-RG06

country_eic_code

EIC code of the country sought

0..n

enum
(3)

Possible values (4):
10YCB-GERMANY--8

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

10YES-REE------0

10YIT-GRTN-----B

10YCH-SWISSGRIDZ

10YFR-RTE------C

SRD-RG01

SRD-RG02

SRD-RG04

SRD-RG09

(1)   By convention, the end_date data is excluded from the search, data from the Service's response.
(2) If the start_date has passed, then the end_date should be passed as a parameter.
(3) Several of these values can be passed as a parameter, separated by a comma: . . .&field=VALUE1,VALUE2
(4) For more information, consult information about how EIC codes, ISO codes and country labels correspond at the bottom of the page in the appendix.

(2)   NB:
– The Service’s field names are in English. Consult the paragraph on "Language – Field name translations" at the bottom of the page.
– Consult the section on "Expected formats" for details of the parameters' expected formats.

 

Call examples:

Without parameters

URL:

GET  /open_api/exchange_schedule/v1/sum_rights_document

HTTP/1.1

Headers:

Host: digital.iservices.rte-france.com

Authorization: Bearer CNAPbfmg7GjvtqTTlKqPm8ykP6R8YJFfJPnyjqW8p1v2PW2UX6bF8z

Body:

 

With all parameters

URL:

GET /open_api/exchange_schedule/v1/sum_rights_document?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.2.1.3 Outputs

 

NAME

CARD.

DESCRIPTION

sum_rights_document

1..1

Table of values {JSON} containing 1 occurrence.

It is structured as shown below:

0..n

NAME

CARD.

DESCRIPTION

TYPE

VALUES / FORMAT

RULES

start_date

1..1

Start date

date

YYYY-MM-DDThh:mm:sszzzzzz

SRD-RG08

end_date

1..1

End date

date

YYYY-MM-DDThh:mm:sszzzzzz

SRD-RG08

sender_country_name

1..1

Name of sending country

enum

One of the following values:
Belgium
France
Germany
Italy
Spain
Switzerland

receiver_country_name

1..1

Name of receiving country

enum

One of the following values:
Belgium
France
Germany
Italy
Spain
Switzerland

sender_country_eic_code

1..1

Sending country's EIC code

enum

One of the following values:
10YBE----------2

10YFR-RTE------C

10YCB-GERMANY--8

10YIT-GRTN-----B

10YES-REE------0

10YCH-SWISSGRIDZ

receiver_country_eic_code

1..1

Receiving country's EIC code

enum

One of the following values:
10YBE----------2

10YFR-RTE------C

10YCB-GERMANY--8

10YIT-GRTN-----B

10YES-REE------0

10YCH-SWISSGRIDZ

values

 

1..1

One value per time interval. Table of values {JSON} structured as shown below:

SRD-RG07

0..n

NAME

CARD.

DESCRIPTION

TYPE

VALUES / FORMAT

start_date

1..1

Start time interval

date

YYYY-MM-DDThh:mm:sszzzzzz

end_date

1..1

End time interval

date

YYYY-MM-DDThh:mm:sszzzzzz

updated_date

1..1

Data update date

date

YYYY-MM-DDThh:mm:sszzzzzz

value

1..1

Data value

int

Entier numérique

 

NB: This structure is duplicated and repeated for each type and each country.

 

JSON format of the return:

GET  /open_api/exchange_schedule/v1/sum_rights_document

HTTP/1.1 200 OK

 

"sum_rights_document":[ 

      { 

         "start_date":"2016-01-06T00:00:00+01:00",

         "end_date":"2016-01-07T00:00:00+01:00",

         "sender_country_name":"France",

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

         "receiver_country_name":"Belgium",

         "receiver_country_eic_code":"10YBE----------2",

         "values":[ 

            { 

               "start_date":"2016-01-06T00:00:00+01:00",

               "end_date":"2016-01-06T01:00:00+01:00",

               "updated_date":"2016-01-04T00:00:00+01:00",

               "value":1762

            }, ... ]

              },...

   ]

}

 

5.2.1.4 Control rules

 

Control rules for different input parameters:

 

input parameter

Description

Number

start_date

end_date

Country_eic_code

empty

empty

empty

If no input parameters are entered, for each of the borders, the Service will return the most up-to-date authorisations to schedule.

SRD-RG01

empty

empty

filled in

If the country_eic_code field is filled in, the response only contains the import and export borders of the countries requested.

SRD-RG02

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

SRD-RG09

filled in

filled in

empty

If the start_date and end_date fields are filled in, the operation returns the authorisations to schedule for all borders.

SRD-RG03

if for one of the authorisation borders, there is no data for the period requested, the service returns the start_date, the end_date, the sender_country_eic_code, the sender_country_name, the receiver_country_eic_code and the receiver_country_name without filling in the value fields.

SRD-RG06

filled in

filled in

filled in

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

SRD-RG04

 

Output control rules applied:

 

Number

Description

SRD-RG07

·         When changing from daylight saving time to summertime, the 2 AM to 3 AM value (French time) is empty.

·         When changing from summertime to daylight saving time, the 2 AM to 3 AM value (French time) appears twice

SRD-RG08

As the service's output, the authorisations to schedule are returned as linked to calendar day.

 

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 5 Details of errors.

 

Type of error

Error code

Details

Functional

EXCHSCHED_SUMRGTSDOC_F01

§6.1.2

Functional

EXCHSCHED_SUMRGTSDOC _F02

§6.1.2

Functional

EXCHSCHED_SUMRGTSDOC _F03

§6.1.2

Functional

EXCHSCHED_SUMRGTSDOC _F04

§6.1.2

Functional

EXCHSCHED_SUMRGTSDOC _F05

§6.1.2

Functional

EXCHSCHED_SUMRGTSDOC _F06

§6.1.2

Functional

EXCHSCHED_SUMRGTSDOC _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

Technical

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 depending on the sequencing of calls.

This paragraph details the generic errors that are common to all of the API's resources. As such, it does not describe 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 organisation. If exceeded, the caller is notified with 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 caller (identified by its OAuth2 token or its PKI certificate) has created an application on the Data Portal. Otherwise, the caller is informed by an HTTP 403 "forbidden"

The fourth stage involves checking that the API is associated with the application (subscription). 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": "See the API User Guide or the FAQ on https://data.rte-france.com"

   "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   schedules

 

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

 

EXCHSCHED_SCHED_F01

Message

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

RG

If either of the start_date and end_date parameters are passed on their own, the Service generates this error.

Call example

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

EXCHSCHED_SCHED_F02

Message

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

RG

If the start_date field is more recent than the end_date field, the Service generates this error.

Call example

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

EXCHSCHED_SCHED_F03

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.

RG

If the period is greater than 31 days, the Service generates this error.

Call example

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

EXCHSCHED_SCHED_F04

Message

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

RG

If end_date field is greater than D-1 compared with the system date, the Service generates this error.

Call example

GET /open-api/exchange_schedule/v1/schedules/v1?start_date=2015-06-01T00:00:00%2B02:00&end_date=2025-07-02T00:00:00%2B02:00

EXCHSCHED_SCHED_F05

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.

RG

If the time interval between start_date and end_date is less than 1 calendar day, the Service generates this error.

Call example

GET /open-api/exchange_schedule/v1/schedules?start_date=2015-06-01T00:00:00%2B02:00&end_date=2015-06-01T12:00:00%2B02:00

EXCHSCHED_SCHED_F06

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.

RG

If the start_date or end_date are not in the expected format, the Service generates this error.

Call example

GET /open-api/exchange_schedule/v1/schedules?start_date=2015-06-01&end_date=2015-06-01

EXCHSCHED_SCHED_F07

Message

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

RG

If type and/or country_eic_code is not one of the expected values, the Service generates this error.

Call example

GET /open-api/exchange_schedule/v1/schedules?type=D-5

6.1.2   sum_rights_document

 

EXCHSCHED_SUMRGTSDOC_F01

Message

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

RG

If either of the start_date and end_date parameters are passed on their own, the Service generates this error.

Call example

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

EXCHSCHED_SUMRGTSDOC _F02

Message

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

RG

If the start_date field is more recent than the end_date field, the Service generates this error.

Call example

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

EXCHSCHED_SUMRGTSDOC _F03

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.

RG

If the period is greater than 155 days, the Service generates this error.

Call example

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

EXCHSCHED_SUMRGTSDOC _F04

Message

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

RG

If end_date field is greater than D-1 compared with the system date, the Service generates this error.

Call example

GET /open-api/exchange_schedule/v1/sum_rights_document?start_date=2015-06-01T00:00:00%2B02:00&end_date=2025-07-02T00:00:00%2B02:00

EXCHSCHED_SUMRGTSDOC _F05

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.

RG

If the time interval between start_date and end_date is less than 1 calendar day, the Service generates this error.

Call example

GET /open-api/exchange_schedule/v1/sum_rights_document?start_date=2015-06-01T00:00:00%2B02:00&end_date=2015-06-01T12:00:00%2B02:00

EXCHSCHED_SUMRGTSDOC _F06

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.

RG

If the start_date or end_date are not in the expected format, the Service generates this error.

Call example

GET /open-api/exchange_schedule/v1/sum_rights_document?start_date=2015-06-01&end_date=2015-06-01

EXCHSCHED_SUMRGTSDOC _F07

Message

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

RG

If country_eic_code is not one of the expected values, the Service generates this error.

Call example

GET /open-api/exchange_schedule/v1/sum_rights_document?country_eic_code=france

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.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.

7.2     EIC code, ISO code and country name equivalents

 

EIC Code

ISO Code

Country Name

10YFR-RTE------C

FR

France

10YCB-GERMANY--8

DE

Germany

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

BE

Belgium

10YES-REE------0

ES

Spain

10YIT-GRTN-----B

IT

Italy

10YCH-SWISSGRIDZ

CH

Switzerland

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

GB

England (Great Britain)

 

7.3     Language – Translations of names

ENGLISH

FRENCH

start_date

date_debut

end_date

date_fin

D-1

J-1

LT

Long Terme

ID

IJ