User Guide

signal API

 

 

 

Version 1.1

Effective date: February 26, 2018

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

Contents

1       Introduction_ 3

1.1      Definitions 3

1.2      Technical support 3

2       Functional description of the signal API 4

2.1      General description. 4

2.2      Prerequisites for using the APIs 4

2.2.1   Data confidentiality. 4

2.2.2   Termination. 4

2.3      "signals" resource. 4

3       Accessing the API 5

4       Resources exposed by the “signal” API 6

4.1      "signals" resource. 6

4.1.1   GET /signals. 6

4.1.1.1     Call methods. 6

4.1.1.2     Inputs. 7

4.1.1.3     Outputs. 8

4.1.1.4     Control rules. 10

4.1.1.5     Error codes. 11

5       Details of errors 12

5.1      Functional errors 14

5.1.1   signals. 14

5.2      Technical errors 15

6       Appendices 17

6.1      Sample Files 17

END OF DOCUMENT_ 17


 

 

This document describes version 1 of the signal API that RTE provides for its Clients in order to expose PP1 and PP2 peak period signal data.

 

Reference documents

 

Short reference

Name of the document

Complete reference

[R1]

Terms of use for RTE’s APIs

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 (Interface de programmation applicative)

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.

 

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

The API is used to obtain data emitted during Peak Period 1 and 2 signals. This resource can only be accessed as part of a GET type request.

2.2     Prerequisites for using the APIs

The signal 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     "signals" resource

This resource is for obtaining signalling data for a PP1 or PP2 day.

 

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      Resources exposed by the “signal” API
4.1     "signals" resource 4.1.1   GET /signals 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/signal/v1/signals?start_date=<valeur>&end_date=<valeur>

Sandbox URL (1)

https://digital.iservices.rte-france.com/open_api/signal/v1/sandbox/signals

 

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

 

Call recommendations

 

The purpose of this resource is to retrieve signalling information for a PP1 or PP2 day. For nominal use, the period's fields do not need to be filled in. The resource automatically returns data received for the next day

 

This service provides all data available which may be invoked after 01/01/2017. Data for periods before this date – from 01/07/2016 to 01/01/2017 excluded – is not available. 

 

It is advisable to make one call to this service per day at around 9:45 AM for PP1 and 7:15 PM for non-PP1 PP2 days.

 

It is advisable not to exceed a period of 366 days per call.

 

4.1.1.2  Inputs

 

NAME

CARD.

DESCRIPTION

TYPE

VALUES / FORMAT

RULES

start_date

0..1

Start date for data requested

date

YYYY-MM-DDThh:mm:sszzzzzz1

SIGNALS-RG01

SIGNALS-RG02

end_date

0..1

End date for data requested

date

YYYY-MM-DDThh:mm:sszzzzzz1

SIGNALS-RG01

SIGNALS-RG02

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

 

Call examples:

Without parameters

 

URL:

GET  /open_api/signal/v1/signals

HTTP/1.1

Headers:

Host: digital.iservices.rte-france.com

Authorization: Bearer CNAPbfmg7GjvtqTTlKqPm8ykP6R8YJFfJPnyjqW8p1v2PW2UX6bF8z

Body:

 

With all parameters

 

URL:

GET /open_api/signal/v1/signals?start_date=2015-06-08T00:00:00%2B02:00&end_date=2015-06-11T00:00:00%2B02:00

HTTP/1.1

Headers:

Host: digital.iservices.rte-france.com

Authorization: Bearer CNAPbfmg7GjvtqTTlKqPm8ykP6R8YJFfJPnyjqW8p1v2PW2UX6bF8z

Body:

 

 

4.1.1.3Outputs

 

NAME

CARD.

DESCRIPTION

signals

1..1

Table of values {JSON} structured as shown below:

0..2

NAME

CARD.

DESCRIPTION

TYPE

VALUES / FORMAT

RULES

start_date

1..1

Start date for data requested

date

YYYY-MM-DDThh:mm:sszzzzzz1

SIGNALS-RG03

SIGNALS-RG04

end_date

1..1

End date for data requested

date

YYYY-MM-DDThh:mm:sszzzzzz1

SIGNALS-RG03

SIGNALS-RG04

type

1..1

Signal type

enum

Contains one of the following values:

 PP1

 PP2

SIGNALS-RG03

SIGNALS-RG04

values

Table of values {JSON} structured as shown below, with one value per day:

 

0..n

NAME

CARD.

DESCRIPTION

TYPE

VALUES / FORMAT

start_date

1..1

Start date for which the signal is returned

date

YYYY-MM-DDThh:mm:sszzzzzz1

end_date

1..1

End date for which the signal is returned

date

YYYY-MM-DDThh:mm:sszzzzzz1

Updated_date

1..1

Data update date

date

YYYY-MM-DDThh:mm:sszzzzzz1

values

1..1

Value indicating if the day is PP1 or PP2 type

boolean

true/false

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/signal/v1/signals

HTTP/1.1 200 OK

{"signals":[

          {

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

          "end_date":"2015-06-02T00:00:00+01:00",

          "type":"PP1",

          "values":[{"start_date":"2015-06-02T00:00:00+01:00","end_date":"2015-06-02T00:00:00+01:00","value":true,"updated_date":"2015-06-02T00:00:00+01:00"}]

          }

        ,

          {

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

          "end_date":"2015-06-02T00:00:00+01:00",

          "type":"PP2",

          "values":[{"start_date":"2015-06-02T00:00:00+01:00","end_date":"2015-06-02T00:00:00+01:00","value":false,"updated_date":"2015-06-02T00:00:00+01:00"}]

          }

]

}

 


 

 

4.1.1.4 Control rules

Control rules for different input parameters:

 

Input parameters

Description

Number

start_date

end_date

empty

empty

If no input parameter is given, the service returns PP1 and PP2 signalling for the most recent day.

SIGNALS-RG01

filled in

filled in

If the start_date and end_date parameters are given, the service returns all signalling data for the days included in this period.

SIGNALS-RG02

 


Output control rules applied:

 

Number

Description

SIGNALS-RG03

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

SIGNALS-RG04

As the service's output, the PP1 and PP2 signalling data is returned as linked to calendar day.

 

 

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

SIGNAL_SIGNALS_F01

§5.1.1

Functional

SIGNAL_SIGNALS_F02

§5.1.1

Functional

SIGNAL_SIGNALS_F03

§5.1.1

Functional

SIGNAL_SIGNALS_F04

§5.1.1

Functional

SIGNAL_SIGNALS_F05

§5.1.1

Functional

SIGNAL_SIGNALS_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

 

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 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 operation. Should this number be exceeded, the caller receives 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   signals

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

 

SIGNAL_SIGNALS_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/signal/v1/signals?start_date=2015-06-01T00:00:00%2B02:00

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

SIGNAL_SIGNALS_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/signal/v1/signals?start_date=2015-06-01T00:00:00%2B02:00&end_date=2016-07-02T00:00:00%2B02:00

SIGNAL_SIGNALS_F04

RG

This error is generated if end_date is greater than D+2 compared with the system 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/signal/v1/signals?start_date=2015-10-31T00:00:00%2B02:00&end_date=2015-11-09T00:00:00%2B02:00

SIGNAL_SIGNALS_F05

RG

This error is generated if the time interval between start_date and end_date is less than 1 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/signal/v1/signals?start_date=2015-06-01T00:00:00%2B02:00&end_date=2015-06-01T12:00:00%2B02:00

SIGNAL_SIGNALS_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/signal/v1/signals?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

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.


 

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.