User Guide

Generation Installed Capacities API

 

Version 1.3

Effective date: February 22, 2018

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

Contents

1       Introduction_ 4

1.1      Definitions 4

1.2      Technical support 4

2       Functional description of the Generation Installed Capacities API 5

2.1      General description. 5

2.2      Prerequisites for using the APIs 5

2.2.1   Data confidentiality. 5

2.2.2   Termination. 5

2.3      capacities_per_production_type resource. 5

2.4      Capacities_per_production_unit resource. 5

2.5      capacities_cpc resource. 5

3       Accessing the API 6

4       Resource exposed by the “Generation Installed Capacities” API 7

4.1      Capacities_per_production_type resource. 7

4.1.1   GET /capacities_per_production_type. 7

4.1.1.1     Call methods. 7

4.1.1.2     Inputs. 8

4.1.1.3     Outputs. 9

4.1.1.4     Control rules. 10

4.1.1.5     Error codes. 11

4.2      Capacities_per_production_unit resource. 12

4.2.1   GET /capacities_per_production_unit 12

4.2.1.1     Call methods. 12

4.2.1.2     Inputs. 13

4.2.1.3     Outputs. 14

4.2.1.4     Control rules. 16

4.2.1.5     Error codes. 17

4.3      Capacities_cpc resource. 18

4.3.1   GET /capacities_cpc. 18

4.3.1.1     Call methods. 18

4.3.1.2     Inputs. 19

4.3.1.3     Outputs. 20

4.3.1.4     Control rules. 21

4.3.1.5     Error codes. 23

5       Details of errors 24

5.1      Functional errors 25

5.1.1   capacities_per_production_type. 25

5.1.2   capacities_per_production_unit 26

5.1.3   capacities_cpc. 28

5.2      Technical errors 29

6       Appendices 31

6.1      Sample Files 31

6.2      Language – Translations of names. 31

END OF DOCUMENT_ 31


 

This document describes the Generation Installed Capacities API that RTE provides in order to expose installed generating capacity data. The data available is produced by RTE by aggregating the installed capacities of production units of more than 1 MW sent by generators for each sector. The published capacities are totals of all the capacities of production units belonging to generators which are members of the UFE initiative. This information is updated at least once a year, during the last week of the year.

Reference documents

 

Short reference

Name of the document

Complete reference

[R1]

Terms of use for RTE’s APIs

Access link

 

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

Authentication

Protection Mode for ensuring that the identity of the Sender or Receiver has been verified 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.

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


 

2.1     General description

This API provides the services below for obtaining data about installed generating capacity is. The data available is produced by RTE by aggregating the installed capacities of production units of more than 1 MW sent by generators for each sector. The published capacities are totals of all the capacities of production units belonging to generators which are members of the UFE initiative. This information is updated at least once a year, during the last week of the year.

2.2     Prerequisites for using the APIs

The Generation Installed Capacities 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.

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

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

2.3     capacities_per_production_type resource

This service is for obtaining data about the installed capacities of production units of more than 1 MW sent by generators.

2.4     Capacities_per_production_unit resource

This service is for obtaining data about the installed capacities of power stations of more than 100 MW, located on the French mainland, excluding Corsica.

2.5     capacities_cpc resource

This service is for obtaining data about the installed capacities of production units that are bound by purchase obligation agreements with EDF.

 

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

4      Resource exposed by the “Generation Installed Capacities” API
4.1     Capacities_per_production_type resource 4.1.1   GET /capacities_per_production_type 4.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/generation_installed_capacities/v1/capacities_per_production_type ?start_date=2015-01-01T00:00:00%2B01:00&end_date=2016-01-01T00:00:00%2B01:00&production_type=OTHER_RENEWABLE

Sandbox URL (1)

https://digital.iservices.rte-france.com/open_api/generation_installed_capacities/v1/sandbox/capacities_per_production_type

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

 

Call recommendations

 

The purpose of this operation is to be able to retrieve installed capacities aggregated by sector. For nominal use, the period's fields do not need to be filled in. The service automatically returns the installed capacities for the current year. Cf. CPPT-RG01. The search can:

 

-          either focus on all sectors if none of the input fields are filled in

-          or a list of sectors can be specified.

 

It is advisable to make one call per day in December to retrieve aggregated installed capacities per sector and two calls per month during the other months of the year in order to retrieve any updates.

 

This service provides all data available after 01/01/2015. Data for periods before this date is not available.

 


 

4.1.1.2 Inputs

 

NAME

DESCRIPTION

CARD.

TYPE

VALUES / FORMAT

RULES

start_date

Start date for data searched for

0..1

date
(2)

YYYY-MM-DDThh:mm:sszzzzzz

CPPT-RG01

CPPT-RG03

end_date

End date for data searched for

0..1

date
(1) (2)

YYYY-MM-DDThh:mm:sszzzzzz

CPPT-RG01

CPPT-RG03

production_type

Generating sector

0..n

enum
(3)

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

WIND_ONSHORE

OTHER

CPPT-RG02

CPPT-RG04

CPPT-RG07

(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

 

Call examples:

 

URL:

GET  /open_api/generation_installed_capacities/v1/capacities_per_production_type

HTTP/1.1

Headers:

Host: digital.iservices.rte-france.com

Authorization: Bearer CNAPbfmg7GjvtqTTlKqPm8ykP6R8YJFfJPnyjqW8p1v2PW2UX6bF8z

Body:

 

 


 

4.1.1.3 Outputs

 

 

NAME

CARD.

DESCRIPTION

capacities_per_production_type

1..1

 

0..n

NAME

CARD.

DESCRIPTION

TYPE

VALUES / FORMAT

RULES

start_date

1..1

Start date for data requested

date

YYYY-MM-DDThh:mm:sszzzzzz

CPPT-RG01

CPPT-RG03

end_date

1..1

End date for requested data

date

YYYY-MM-DDThh:mm:sszzzzzz

CPPT-RG01

CPPT-RG03

values

1..1

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

 

0..n

NAME

CARD.

DESCRIPTION

TYPE

VALUES / FORMAT

start_date

1..1

Time interval start

date

YYYY-MM-DDThh:mm:sszzzzzz

end_date

1..1

Time interval end

date

YYYY-MM-DDThh:mm:sszzzzzz

type

1..1

Generating sector

enum

One of the following 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

WIND_ONSHORE

OTHER

value

1..1

Installed capacity in MW

float

Decimal.

updated_date

1..1

Date updated

date

YYYY-MM-DDThh:mm:sszzzzzz

 

 

 

 

JSON return format:

GET /open_api/generation_installed_capacities/v1/capacities_per_production_type

 

HTTP/1.1 200 OK

{"capacities_per_production_type":[

          {

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

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

          "values":[{"start_date":"2015-01-01T00:00:00+01:00","end_date":"2016-01-01T00:00:00+01:00"," type":"FOSSIL_GAS","value":6121,"updated_date":"2015-07-05T00:30:00+02:00"},

{"start_date":"2015-01-01T00:00:00+01:00","end_date":"2016-01-01T00:00:00+01:00"," type":"OTHER","value":62,"updated_date":"2015-07-05T00:30:00+02:00"}]

          }

]}

 

 

4.1.1.4 Control rules

 

Control rules for different input parameters:

 

Input parameter

Description

Number

production_type

start_date

end_date

empty

empty

empty

If no input parameter is given, the service returns the installed capacity for the current year

CPPT-RG01

 

filled in

empty

empty

If the production_type field is filled in, the response only contains data for the requested sector.

CPPT-RG02

If listed type parameters (production_type) are entered with several identical values, duplicates will be deleted.

CPPT-RG07

empty

filled in

filled in

If the start_date and end_date parameters are given, the service returns the installed capacities for this period.

CPPT-RG03

filled in

filled in

filled in

The production_type AND the start_date / end_date pair can both be passed as parameters for the Service.

CPPT-RG04

 

Output control rules applied:

 

Number

Description

CPPT-RG05

The output data is ordered from the most recent start_date to the oldest.

CPPT-RG06

As the service's output, the installed capacities are returned as linked to calendar year.

 

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

GENINSCAP_CPPT_F01

§5.1.1

Functional

GENINSCAP_CPPT_F02

§5.1.1

Functional

GENINSCAP_CPPT_F03

§5.1.1

Functional

GENINSCAP_CPPT_F04

§5.1.1

Functional

GENINSCAP_CPPT_F05

§5.1.1

Functional

GENINSCAP_CPPT_F06

§5.1.1

Technical

401

§5.2

Technical

403

§5.2

Technical

404

§5.2

Technical

408

§5.2

Technical

413

§5.2

Technical

414

§5.2

Technical

429

§5.2

Technical

500

§5.2

Technical

503

§5.2

Technical

509

§5.2

 


 

4.2     Capacities_per_production_unit resource 4.2.1   GET /capacities_per_production_unit 4.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/generation_installed_capacities/v1/capacities_per_production_unit ?start_date=2015-01-01T00:00:00%2B01:00&end_date=2016-01-01T00:00:00%2B01:00

Sandbox URL (1)

https://digital.iservices.rte-france.com/open_api/generation_installed_capacities/v1/sandbox/capacities_per_production_unit

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

 

Call recommendations

 

The purpose of this operation is to be able to retrieve installed capacities per power station. For nominal use, the period's fields do not need to be filled in. The service automatically returns the installed capacities for all power stations in operation (“end_date” field empty or not present) Cf. CPPU-RG01.

 

It is advisable to make one call per day to retrieve installed capacities aggregated per sector.

 

This service provides all data available after 01/01/1935. Data for periods before this date is not available.

 


 

4.2.1.2 Inputs

 

NAME

DESCRIPTION

CARD.

TYPE

VALUES / FORMAT

RULES

start_date

Start date for
data searched for

0..1

date
(2)

YYYY-MM-DDThh:mm:sszzzzzz

CPPU-RG01

CPPU-RG02

end_date

End date for
data searched for

0..1

date
(1) (2)

YYYY-MM-DDThh:mm:sszzzzzz

CPPU-RG01

CPPU-RG02

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



Call examples:

 

URL:

GET  /open_api/generation_installed_capacities/v1/capacities_per_production_unit

HTTP/1.1

Headers:

Host: digital.iservices.rte-france.com

Authorization: Bearer CNAPbfmg7GjvtqTTlKqPm8ykP6R8YJFfJPnyjqW8p1v2PW2UX6bF8z

Body:

 


 

4.2.1.3 Outputs

 

 

NAME

CARD.

DESCRIPTION

capacities_per_production_unit

1..1

 

0..n

NAME

CARD.

DESCRIPTION

TYPE

VALUES / FORMAT

RULES

start_date

1..1

Start date for data requested

date

YYYY-MM-DDThh:mm:sszzzzzz

CPPU-RG01

CPPU-RG02

end_date

0..1

End date for requested data

date

YYYY-MM-DDThh:mm:sszzzzzz

CPPU-RG01

CPPU-RG02

production_unit

1..1

Object {JSON} structured as shown below:

0..n

NAME

CARD.

DESCRIPTION

TYPE

VALUES / FORMAT

code_eic

1..1

EIC code of the power station

string

Character string

name

1..1

Name of the power station

string

Character string

location

1..1

Location of the power station

string

Character string

values

 

1..1

Table of values {JSON} structured as shown below:

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

installed_capacity

1..1

Installed capacity in MW

float

Decimal.

voltage_level_connection

1..1

Connection voltage level (in KVT)

float

Decimal.

production_type

1..1

Generating sector

enum

One of the following 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

WIND_ONSHORE

OTHER

updated_date

1..1

Date updated

date

YYYY-MM-DDThh:mm:sszzzzzz

 

 

 

 

JSON return format:

GET /open_api/generation_installed_capacities/v1/capacities_per_production_unit

 

HTTP/1.1 200 OK

{"capacities_per_production_unit":[

          {

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

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

        "production_unit":{"code_eic":"17W100P100P0017S","name":"CORDEMAIS 4","location":"France"},

          "values":[{"start_date":"2000-01-01T00:00:00+01:00","installed_capacity":580,"voltage_level_connection":225,production_type":

"FOSSIL_HARD_COAL","updated_date":"2015-07-05T00:30:00+02:00"},{ ... }]

          }

        ,{ ... }

]}

 

 

4.2.1.4 Control rules

 

Control rules for different input parameters:

 

Input parameter

Description

Number

start_date

end_date

empty

empty

If no input parameter is given, the service returns the installed capacity for the power stations in operation.

CPPU-RG01

filled in

filled in

If the start_date and end_date parameters are given, the service returns the installed capacities for power stations in operation during this period.

CPPU-RG02

 

Output control rules applied:

 

Number

Description

CPPU-RG03

The output data is sorted by the production_type fields in alphabetical order, then by name in alphabetical order.

 

 

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

GENINSCAP_CPPU_F01

§5.1.2

Functional

GENINSCAP_CPPU_F02

§5.1.2

Functional

GENINSCAP_CPPU_F03

§5.1.2

Functional

GENINSCAP_CPPU_F04

§5.1.2

Functional

GENINSCAP_CPPU_F05

§5.1.2

Functional

GENINSCAP_CPPU_F06

§5.1.2

Technical

401

§5.2

Technical

403

§5.2

Technical

404

§5.2

Technical

408

§5.2

Technical

413

§5.2

Technical

414

§5.2

Technical

429

§5.2

Technical

500

§5.2

Technical

503

§5.2

Technical

509

§5.2

 


 

4.3     Capacities_cpc resource 4.3.1   GET /capacities_cpc 4.3.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/generation_installed_capacities/v1/capacities_cpc?start_date=2015-01-01T00:00:00%2B01:00&end_date=2016-01-01T00:00:00%2B01:00&department_code=FR&network_connection=RPT&production_type=SOLAR,BIOMASS,HYDRO

Sandbox URL (1)

https://digital.iservices.rte-france.com/open_api/generation_installed_capacities/v1/sandbox/capacities_cpc

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

 

Call recommendations

 

The purpose of this operation is to be able to retrieve installed capacities of the facilities bound by purchase obligations. For nominal use, the period's fields do not need to be filled in. The service automatically returns the installed capacities that have been most recently updated Cf. CCPC-RG01. The search can:

 

-          either focus on all departments, or networks and all sectors if none of the input fields are filled in

-          or a list of departments, a network and/or a list of sectors can be specified.

 

It is advisable to make one call per day to retrieve aggregated installed capacities of facilities bound by purchase obligations.

 

This service provides all data available after 09/02/2015. Data for periods before this date is not available.

 


 

4.3.1.2 Inputs

 

NAME

DESCRIPTION

CARD.

TYPE

VALUES / FORMAT

RULES

start_date

Start date for
data searched for

0..1

date
(2)

YYYY-MM-DDThh:mm:sszzzzzz

CCPC-RG01

CCPC-RG06

end_date

End date for
data searched for

0..1

date
(1) (2)

YYYY-MM-DDThh:mm:sszzzzzz

CCPC-RG01

CCPC-RG06

department_code

Department code

0..n

enum
(3)

Possible values:
Codes of departments in accordance with the ISO 3166-2 standard.
Use FR for aggregated France data.

CCPC-RG02

CCPC-RG03

CCPC-RG07

network_connection

Connection network

0..2

enum
(3)

Possible values:
RPD
RPT

CCPC-RG04

CCPC-RG07

production_type

Generating sector

0..n

enum
(3)

Possible values:
WIND
SOLAR
HYDRO
COGENERATION
BIOGAZ
BIOMASS
INCINERATION
GEOTHERMAL
OTHERS

CCPC-RG05

CCPC-RG07

 (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



Call examples:

 

URL:

GET  /open_api/generation_installed_capacities/v1/capacities_cpc

HTTP/1.1

Headers:

Host: digital.iservices.rte-france.com

Authorization: Bearer CNAPbfmg7GjvtqTTlKqPm8ykP6R8YJFfJPnyjqW8p1v2PW2UX6bF8z

Body:

 


 

4.3.1.3 Outputs

 

 

NAME

CARD.

DESCRIPTION

capacities_cpc

 

 

0..n

NAME

CARD.

DESCRIPTION

TYPE

VALUES / FORMAT

RULES

updated_date

1..1

Date updated

date

YYYY-MM-DDThh:mm:sszzzzzz

CCPC-RG08

department_code

1..1

Department code

enum

Department codes
ISO 3166-2 standard

CCPC-RG09

network_connection

1..1

Connection network

enum

One of the following values:
RPD
RPT

CCPC-RG09

production_type

1..1

Generating sector

enum

One of the following values:
WIND
SOLAR
HYDRO
COGENERATION
BIOGAZ
BIOMASS
INCINERATION
GEOTHERMAL
OTHERS

CCPC-RG09

value

1..1

Installed capacity aggregated by department, network and sector (in KW)

int

Integer.

CCPC-RG09

 

 

 

JSON return format:

 

GET /generation_installed_capacities/v1/capacities_cpc

 

HTTP/1.1 200 OK

{"capacities_cpc":[

          {"updated_date":"2016-02-01T00:00:00+01:00","department_code":"FR","network_connection":"RPD","production_type":"BIOGAS","values":323012},

          {"updated_date":"2016-02-01T00:00:00+01:00","department_code":"FR","network_connection":"RPT","production_type":"BIOGAS","values":2925},

          { ... }

]}

 

4.3.1.4 Control rules

 

Control rules for different input parameters:

 

Input parameter

Description

Number

start_date

end_date

department_code

network_connection

production_type

empty

empty

empty

empty

empty

If no input parameters are entered, the Service will return the most recently updated installed capacities. If a couple (sector, department) no longer has any facilities bound by obligations to purchase, but did have previously, the service will no longer return this sector in nominal mode. To retrieve the history, the CCPC-RG06 rule should be used.

CCPC-RG01

filled in

filled in

filled in

filled in

filled in

For the department_code field, the FR value has been added to the ISO department codes to signify that aggregated data for France is being requested.

CCPC-RG02

filled in

filled in

filled in

filled in

filled in

The department_code, network_connection, production_type and the start_date / end_date pair can be passed as parameters for the Service.

CCPC-RG07

filled in

filled in

filled in

filled in

filled in

If listed type fields are entered with several identical values, duplicates will be deleted.

CCPC-RG10

empty

empty

filled in

empty

empty

If the department_code field is filled in as a service parameter, the response only contains data for the requested department.

CCPC-RG03

empty

empty

empty

filled in

empty

If the network_connection field is filled in as a service parameter, the response only contains data for the requested network.

CCPC-RG04

empty

empty

empty

empty

 

 

filled in

If the production_type field is filled in as a service parameter, the response only contains data for the requested sector.

CCPC-RG05

filled in

filled in

empty

empty

empty

If the start_date and end_date fields are filled in, the service returns the installed capacities that have an update date within this period.

CCPC-RG06

 

Output control rules applied:

 

Number

Description

CCPC-RG08

The output data is ordered by the updated_date field, from the most recent to the oldest, then by department_codein alphabetical order, then by production_type in alphabetical order, then by network_connection in alphabetical order.

CCPC-RG09

If the service cannot find a response that satisfies all the parameters passed, it returns all the fields except updated_date and value. If the service cannot find any response, it returns the EC45_ERR01 error.

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

GENINSCAP_CCPC_F01

§5.1.3

Functional

GENINSCAP_CCPC_F02

§5.1.3

Functional

GENINSCAP_CCPC_F03

§5.1.3

Functional

GENINSCAP_CCPC_F04

§5.1.3

Functional

GENINSCAP_CCPC_F05

§5.1.3

Functional

GENINSCAP_CCPC_F06

§5.1.3

Technical

401

§5.2

Technical

403

§5.2

Technical

404

§5.2

Technical

408

§5.2

Technical

413

§5.2

Technical

414

§5.2

Technical

429

§5.2

Technical

500

§5.2

Technical

503

§5.2

Technical

509

§5.2

 

 

5         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": "URI to the API user guide or the FAQ/documentation on the Data 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.

 

 

 

5.1     Functional errors 5.1.1   capacities_per_production_type

 

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

 

GENINSCAP_CPPT_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/generation_installed_capacities/v1/capacities_per_production_type?start_date=2015-06-01T00:00:00%2B02:00

GENINSCAP_CPPT_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/generation_installed_capacities/v1/capacities_per_production_type?start_date=2015-06-02T00:00:00%2B02:00&end_date=2015-06-01T00:00:00%2B02:00

GENINSCAP_CPPT_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 366 days, the Service generates this error.

Call example

GET /open_api/generation_installed_capacities/v1/capacities_per_production_type?start_date=2015-06-01T00:00:00%2B02:00&end_date=2015-07-02T00:00:00%2B02:00

GENINSCAP_CPPT_F04

Message

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

RG

If end_date is greater than 1 January of the next year, the Service generates this error.

Call example

GET /open_api/generation_installed_capacities/v1/capacities_per_production_type?start_date=2015-10-31T00:00:00%2B02:00&end_date=2015-11-09T00:00:00%2B02:00 for a call on 30/10/2015

GENINSCAP_CPPT_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 year, the Service generates this error.

Call example

GET /open_api/generation_installed_capacities/v1/capacities_per_production_type?start_date=2015-06-01T00:00:00%2B02:00&end_date=2015-06-01T12:00:00%2B02:00

GENINSCAP_CPPT_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/generation_installed_capacities/v1/capacities_per_production_type?start_date=2015-06-01&end_date=2015-06-01

5.1.2   capacities_per_production_unit

 

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

 

GENINSCAP_CPPU_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/generation_installed_capacities/v1/capacities_per_production_unit?start_date=2015-06-01T00:00:00%2B02:00

GENINSCAP_CPPU_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/generation_installed_capacities/v1/capacities_per_production_unit?start_date=2015-06-02T00:00:00%2B02:00&end_date=2015-06-01T00:00:00%2B02:00

GENINSCAP_CPPU_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 366 days, the Service generates this error.

Call example

GET /open_api/generation_installed_capacities/v1/capacities_per_production_unit?start_date=2015-06-01T00:00:00%2B02:00&end_date=2015-07-02T00:00:00%2B02:00

GENINSCAP_CPPU_F04

Message

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

RG

If end_date is greater than 1 January of the next year, the Service generates this error.

Call example

GET /open_api/generation_installed_capacities/v1/capacities_per_production_unit?start_date=2015-10-31T00:00:00%2B02:00&end_date=2015-11-09T00:00:00%2B02:00 for a call on 30/10/2015

GENINSCAP_CPPU_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/generation_installed_capacities/v1/capacities_per_production_unit?start_date=2015-06-01T00:00:00%2B02:00&end_date=2015-06-01T12:00:00%2B02:00

GENINSCAP_CPPU_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/generation_installed_capacities/v1/capacities_per_production_unit?start_date=2015-06-01&end_date=2015-06-01

 


 

5.1.3   capacities_cpc

 

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

 

GENINSCAP_CCPC_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/generation_installed_capacities/v1/capacities_cpc?start_date=2015-06-01T00:00:00%2B02:00

GENINSCAP_CCPC_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/generation_installed_capacities/v1/capacities_cpc?start_date=2015-06-02T00:00:00%2B02:00&end_date=2015-06-01T00:00:00%2B02:00

GENINSCAP_CCPC_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 366 days, the Service generates this error.

Call example

GET /open_api/generation_installed_capacities/v1/capacities_cpc?start_date=2015-06-01T00:00:00%2B02:00&end_date=2015-07-02T00:00:00%2B02:00

GENINSCAP_CCPC_F04

Message

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

RG

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

Call example

GET /open_api/generation_installed_capacities/v1/capacities_cpc?start_date=2015-10-31T00:00:00%2B02:00&end_date=2015-11-09T00:00:00%2B02:00 for a call on 30/10/2015

GENINSCAP_CCPC_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/generation_installed_capacities/v1/capacities_cpc?start_date=2015-06-01T00:00:00%2B02:00&end_date=2015-06-01T12:00:00%2B02:00

GENINSCAP_CCPC_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/generation_installed_capacities/v1/capacities_cpc?start_date=2015-06-01&end_date=2015-06-01

 


 

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

Example
of a call

The resource called does not exist or no data was found

408

HTTP code

408

Message

Request Time-out

Example
of a call

Error generated when there is no response from the service called or when the call to the service times out (http 408).

413

HTTP code

413

Message

Request Entity Too Large

Example
of a call

The size of the request exceeds 5 MB

414

HTTP code

414

Message

Request-URI Too Long

Example
of a call

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

429

HTTP code

429

Message

Too Many Requests

Call example

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

500

HTTP code

500

Message

Internal Server Error

Call example

Any other technical error.

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

503

HTTP code

503

Message

Service Unavailable

Call example

Error generated during maintenance (HTTP 503).

509

HTTP code

509

Message

Bandwidth Limit Exceeded.

Call example

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

 


 

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

6.2     Language – Translations of names.

ENGLISH

FRENCH

start_date

date_debut

end_date

date_fin

updated_date

date de mise à jour

value

valeur

BIOMASS

BIOMASSE

FOSSIL_BROWN_COAL_LIGNITE

LIGNITE

FOSSIL_COAL_DERIVED_GAS

GAZ ISSU DU CHARBON

FOSSIL_GAS

GAZ

FOSSIL_HARD_COAL

CHARBON

FOSSIL_OIL

FIOUL

FOSSIL_OIL_SHALE

PETROLE DE SCHISTE

FOSSIL_PEAT

TOURBE

GEOTHERMAL

GEOTHERMIQUE

HYDRO_PUMPED_STORAGE

HYDRAULIQUE_STEP

HYDRO_RUN_OF_RIVER_AND_POUNDAGE

HYDRAULIQUE_FILEDELEAU_ECLUSEE

HYDRO_WATER_RESERVOIR

HYDRAULIQUE_LACS

MARINE

MARINE

NUCLEAR

NUCLEAIRE

OTHER_RENEWABLE

AUTRE-RENOUVELABLE

SOLAR

SOLAIRE

WASTE

DECHETS INDUSTRIELS

WIND_OFFSHORE

EOLIEN_OFFSHORE

WIND_ONSHORE

EOLIEN_TERRESTRE

OTHER

AUTRE