Introduction

Welcome to EDF Store & Forecast API v2 documentation !

We have tried to make this documentation user-friendly and example-filled, but if you have any questions, please head to our support team: support@edf-sf.com.

Some major changes to production category were introduced in version 2 of the API, as well as a new site category. The documentation for version 1 of the API can be found here

ID

This section focuses on ids and their description.

{
  "id": "ess-1-p",
  "description": "ess id 1 - active power"
}

Add IDs description

Example

curl --cacert ca.cert.pem --cert cert.pem --key key.pem
-X PUT -H "Content-Type: application/json" -d
'{
  "production": {
    "statuses": [
      {
        "id": "ess-1-state",
        "description": "ess id 1 - state"
      }
    ]
  }
}' "https://api-preprod.edf-sf.com/v2/100/site"

{
  "status_code": 1000,
  "status_message": "success"
}

HTTP Request

PUT https://api.edf-sf.com/v2/<site_id>/site

URL Parameters

Body

Response

Production

Production types

Supported production type

• metric: value of type float64
• status: value of type uint32

Metric

{
  "id": "ess-1-p",
  "values": [
    {
      "timestamp": 1601624896000,
      "value": -491.2
    }
  ]
}

Metric value

Status

{
  "id": "ess-1-state",
  "values": [
    {
      "timestamp": 1601624896000,
      "value": 3
    }
  ]
}

Status value

Get production data

Example

curl --cacert ca.cert.pem --cert cert.pem --key key.pem
"https://api-preprod.edf-sf.com/v2/100/production/status/ess-1-state"

{
  "status_code": 1000,
  "status_message": "success",
  "results": [
    {
      "id": "ess-1-state",
      "values": [
        {
          "timestamp": 1601624896000,
          "value": 1
        }
      ]
    }
  ]
}

curl --cacert ca.cert.pem --cert cert.pem --key key.pem
"https://api-preprod.edf-sf.com/v2/100/production/metric/ess-1-p?from=1601624894000&to=1601624897000"

Example

{
  "status_code": 1000,
  "status_message": "success",
  "results": [
    {
      "id": "ess-1-p",
      "values": [
        {
          "timestamp": 1601624894000,
          "value": -494.7
        },
        {
          "timestamp": 1601624895000,
          "value": -492.6
        },
        {
          "timestamp": 1601624896000,
          "value": -491.2
        }
      ]
    }
  ]
}

HTTP Request

GET https://api.edf-sf.com/v2/<site_id>/production/<production_type>/<id>

URL Parameters

Example

curl --cacert ca.cert.pem --cert cert.pem --key key.pem
-H "Content-Type: application/json" -d
'{
  "ids": ["ess-1-p", "ess-1-q"]
}'
"https://api-preprod.edf-sf.com/v2/100/production/metric?from=1601624894000&to=1601624897000"

{
  "status_code": 1000,
  "status_message": "success",
  "results": [
    {
      "id": "ess-1-p",
      "values": [
        {
          "timestamp": 1601624894000,
          "value": -494.7
        },
        {
          "timestamp": 1601624895000,
          "value": -492.6
        },
        {
          "timestamp": 1601624896000,
          "value": -491.2
        }
      ]
    },
    {
      "id": "ess-1-q",
      "values": [
        {
          "timestamp": 1601624894000,
          "value": -2.4
        },
        {
          "timestamp": 1601624895000,
          "value": -2.5
        },
        {
          "timestamp": 1601624896000,
          "value": -2.6
        }
      ]
    }
  ]
}

Body

Query Parameters

Response

Forecast

The forecast endpoint can be used to GET or PUT forecast data for a given site.

Forecasts are stored as vectors of forecast periods.

Forecast periods obey the left convention (or beginning convention), which means that a forecast period is effective starting from its timestamp until the timestamp of the next forecast period.

Forecast attributes:

Get forecast

GET method on this endpoint returns forecast vector for the requested site ID, forecast type and forecast ID.

GET solar forecast example:

curl --cacert ca.cert.pem --cert cert.pem --key key.pem
"https://api-preprod.edf-sf.com/v2/100/forecast/solar/1?from=1535104800000&to=1535106600000"

The above command returns JSON structured like this:

{
  "status_code": 1000,
  "status_message": "success",
  "results": [
    {
      "creation_timestamp": 1535104800000,
      "id": 1,
      "values": [
        {
          "timestamp": 1535104800000,
          "p": 1572.64,
          "quality": 1
        },
        {
          "timestamp": 1535106600000,
          "p": 1650.94,
          "quality": 1
        }
      ]
    }
  ]
}

Forecast vectors can be filtered according to their creation date with generated-after and generated-before parameters. A selected forecast vector can be filtered with from, to parameters.

See examples to get a visual example.

HTTP Request

GET https://api.edf-sf.com/v2/<site_id>/forecast/<forecast_type>/<forecast_id>

URL Parameters

Query Parameters

Put forecast

PUT method on this endpoint pushes forecast vectors for the given site ID and forecast type. Several forecast vectors with different forecast IDs can be pushed in a single request.

PUT wind forecast example:

curl --cacert ca.cert.pem --cert cert.pem --key key.pem
-X PUT -H "Content-Type: application/json" -d
'{
  "values": [
     {
        "creation_timestamp": 1535104800000,
        "id": 1,
        "values": [
          {
            "timestamp": 1535104800000,
            "p": 1572.64,
            "quality": 1
          },
          {
            "timestamp": 1535106600000,
            "p": 1650.94,
            "quality": 1
          }
        ]
     }
  ]
}' "https://api-preprod.edf-sf.com/v2/100/forecast/wind"

The above command returns JSON structured like this:

{
  "status_code": 1000,
  "status_message": "success",
}

HTTP Request

PUT https://api.edf-sf.com/v2/<site_id>/forecast/<forecast_type>

URL Parameters

Forecast types

Demand

Example:

{
  "timestamp": 1535104800000,
  "p": 411.08,
  "quality": 1
}

Forecast type: demand

Solar

Example:

{
  "timestamp": 1535104800000,
  "p": 350.66,
  "quality": 1
}

Forecast type: solar

Wind

Example:

{
  "timestamp": 1535104800000,
  "p": 1475.58,
  "quality": 1
}

Forecast type: wind

Aggregate

Example:

{
  "timestamp": 1535104800000,
  "p": 627.34,
  "quality": 1
}

Forecast type: aggregate

Commitment

The commitment endpoint can be used to GET or PUT commitment data for a given site.

Commitments are stored as vectors of commitment periods.

Commitment periods obey the left convention (or beginning convention), which means that a commitment period is effective starting from its timestamp until the timestamp of the next commitment period.

Commitment attributes:

Commitment period attributes:

Get commitment

GET method on this endpoint returns commitment vector for the requested site ID and commitment ID.

GET commitment example:

curl --cacert ca.cert.pem --cert cert.pem --key key.pem
"https://api-preprod.edf-sf.com/v2/100/commitment/1?from=1535104800000&to=1535106600000"

The above command returns JSON structured like this:

{
  "status_code": 1000,
  "status_message": "success",
  "results": [
    {
      "creation_timestamp": 1535104800000,
      "id": 1,
      "quality": 1,
      "values": [
        {
          "timestamp": 1535104800000,
          "value": 1100.0
        },
        {
          "timestamp": 1535106600000,
          "value": 950.4
        }
      ]
    }
  ]
}

Commitment vectors can be selected according to their creation date with generated-after and generated-before parameters. A selected commitment vector can be filtered with from, to parameters.

See examples to get a visual example.

HTTP Request

GET https://api.edf-sf.com/v2/<site_id>/commitment/<commitment_id>

URL Parameters

Query Parameters

Put commitment

PUT method on this endpoint pushes commitment vectors for the given site ID. Several commitment vectors with different commitment ID can be pushed in a single request.

PUT commitment example:

curl --cacert ca.cert.pem --cert cert.pem --key key.pem
-X PUT -H "Content-Type: application/json" -d
'{
  "values": [
     {
        "creation_timestamp": 1535104800000,
        "id": 1,
        "quality": 1,
        "values": [
            {
              "timestamp": 1535104800000,
              "value": 1100.0
            },
            {
              "timestamp": 1535106600000,
              "value": 950.4
            }
        ]
     }
  ]
}' "https://api-preprod.edf-sf.com/v2/100/commitment"

The above command returns JSON structured like this:

{
  "status_code": 1000,
  "status_message": "success"
}

HTTP Request

PUT https://api.edf-sf.com/v2/<site_id>/commitment

URL Parameters

Tariff

The tariff endpoint can be used to GET or PUT tariff data for a given site.

Tariffs are stored as vectors of tariff periods.

Tariff periods obey the left convention (or beginning convention), which means that a tariff period is effective starting from its timestamp until the timestamp of the next tariff period.

Tariff attributes:

Tariff period attributes:

Example:

{
    "id": 1,
    "values": [
        {
        "timestamp": 1535104800000,
        "label": "on-peak",
        "value": 9.85
        }
    ]
}

Get tariff

GET method on this endpoint returns tariff periods for the requested site ID and tariff ID.

GET tariff example:

curl --cacert ca.cert.pem --cert cert.pem --key key.pem
"https://api-preprod.edf-sf.com/v2/100/tariff/1?from=1535104800000&to=1535107000000"

The above command returns JSON structured like this:

{
    "status_code": 1000,
    "status_message": "success",
    "results": [
        {
            "id": 1,
            "values": [
                {
                    "timestamp": 1540486800000,
                    "label": "on-peak",
                    "value": 9.85
                },
                {
                    "timestamp": 1540501200000,
                    "label": "off-peak",
                    "value": 5.2
                },
                {
                    "timestamp": 1540573200000,
                    "label": "on-peak",
                    "value": 9.85
                },
                {
                    "timestamp": 1540587600000,
                    "label": "off-peak",
                    "value": 5.2
                }
            ]
        }
    ]
}

Tariff periods can be filtered with from, to parameters.

HTTP Request

GET https://api.edf-sf.com/v2/<site_id>/tariff/<tariff_id>

URL Parameters

Query Parameters

Put tariff

PUT method on this endpoint pushes tariff periods for the requested site ID. Several tariffs periods with different tariff IDs can be pushed in a single request.

PUT tariff example:

curl --cacert ca.cert.pem --cert cert.pem --key key.pem
-X PUT -H "Content-Type: application/json" -d
'{
    "values": [
        {
            "id": 1,
            "values": [
                {
                    "timestamp": 1540486800000,
                    "label": "on-peak",
                    "value": 9.85
                },
                {
                    "timestamp": 1540501200000,
                    "label": "off-peak",
                    "value": 5.2
                }
            ]
        }
    ]
}' "https://api-preprod.edf-sf.com/v2/100/tariff"

The above command returns JSON structured like this:

{
  "status_code": 1000,
  "status_message": "success"
}

HTTP Request

PUT https://api.edf-sf.com/v2/<site_id>/tariff

URL Parameters

Status codes

HTTP status codes

Here are the HTTP status codes that can be returned by our API:

API status codes

Here are the API status codes that can be returned by our API in response payloads:

Examples

Forecast and commitments parameters

• generated_before , generated_after:

The vector extracted is the most recent created in the [generated_after, generated_before[ interval.

• from, to:

The vector contains exclusively data with timestamps in the [from, to[ interval.

Python

Python GET request example on production endpoint:

import requests

# certification authority certificate
ca_cert = 'ca.cert.pem'

# client certificate and private key
client_certs = ('cert.pem', 'pkey.pem')

# request to production endpoint for site 100 and metric ess-1-p
endpoint = "https://api-preprod.edf-sf.com/v2/100/production/metric/ess-1-p"

headers = {
    'Accept': 'application/json',
}

# request data interval [2018-11-10 12:00:00 UTC, 2018-11-12 20:00:00 UTC[
# aggregated with average function over 1mn periods
params = {
    'from': 1541851200000,
    'to': 1541880000000,
    'agg': 'avg',
    'period': '1m'
}

r = requests.get(endpoint,
                 verify=ca_cert,
                 cert=client_certs,
                 headers=headers,
                 params=params)

if r.status_code != 200:
    print('request failed: unexpected HTTP status ({})'.format(r.status_code))
else:
    print(r.json())