Introduction

Welcome to EDF Store & Forecast API v1 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.

Version 2 of the API is out ! You can find the documentation here

Production

Production endpoint enables to get or put site production data.

Get production

GET renewable equipment example:

curl --cacert ca.cert.pem --cert cert.pem --key key.pem
"https://api-preprod.edf-sf.com/v1/100/production/renewable/1?from=1535104800000&to=1535133600000"

The above command returns JSON structured like this:

{
  "status_code": 1000,
  "status_message": "success",
  "results": [
    {
      "timestamp": 1535104800000,
      "id": 1,
      "p": 401.92,
      "q": 9.43
    },
    {
      "timestamp": 1535104801000,
      "id": 1,
      "p": 399.54,
      "q": 8.86
    }
  ]
}

GET method on this endpoint retrieves equipment records for the requested site ID, equipment type and equipment ID.

HTTP Request

GET https://api.edf-sf.com/v1/<site_id>/production/<equipment_type>/<equipment_id>

URL Parameters

Query Parameters

Put production

PUT method on this endpoint pushes equipment records for the given site ID and equipment type. Several equipment IDs can be pushed in a single request.

PUT renewable equipment example:

curl --cacert ca.cert.pem --cert cert.pem --key key.pem
-X PUT -H "Content-Type: application/json" -d
'{
  "values": [
   {
     "timestamp": 1535104800000,
     "id": 1,
     "p": 401.92,
     "q": 9.43
   }
  ]
}' "https://api-preprod.edf-sf.com/v1/100/production/renewable"

The above command returns JSON structured like this:

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

HTTP Request

PUT https://api.edf-sf.com/v1/<site_id>/production/<equipment_type>

URL Parameters

Equipment types

Supported equipment types

• anemometer: wind speed and direction measure
• battery: battery energy system storage
• flexible-load: controllable consumption load
• genset: genset
• hygrometer: hygrometry measure
• meter: AC single-phase meter
• meter-dc: DC meter
• meter-3p: AC 3-phases meter
• metric: metric (float)
• pyranometer: solar irradiance measure
• renewable: renewable production asset
• setpoint: setpoint sent to equipment
• status: status (integer)
• thermometer: temperature measure

anemometer

Example:

{
  "timestamp": 1535104800000,
  "id": 1,
  "speed": 12.67,
  "direction": 182
}

battery

Example:

{
  "timestamp": 1535104800000,
  "id": 1,
  "soc": 78.21,
  "e": 425.3,
  "p": 209.44,
  "p_ch": -1000.0,
  "p_disch": 1000.0,
  "q": -6.37,
  "q_max": 100.0,
  "q_min": -100.0,
  "state": 4
}

state possible values:

flexible-load

Example:

{
  "timestamp": 1535104800000,
  "id": 1,
  "p": 31.25,
  "state": 3
}

state possible values:

genset

Example:

{
  "timestamp": 1535104800000,
  "id": 1,
  "p": 82.36,
  "q": -7.12,
  "state": 3
}

state possible values:

hygrometer

Example:

{
  "timestamp": 1535104800000,
  "id": 1,
  "h": 65.25
}

meter

Example:

{
  "timestamp": 1535104800000,
  "id": 1,
  "p": 52.07,
  "q": -4.98,
  "f": 50.01,
  "u": 399.56,
  "i": 0.27
}

meter-dc

Example:

{
  "timestamp": 1535104800000,
  "id": 1,
  "p": 52.07,
  "u": 401.84
}

meter-3p

Example:

{
  "timestamp": 1535104800000,
  "id": 2,
  "l1_p": 48.34,
  "l2_p": 49.63,
  "l3_p": 50.88,
  "l1_q": 0.08,
  "l2_q": -0.41,
  "l3_q": 0.72,
  "l1_i": 0.52,
  "l2_i": 0.51,
  "l3_i": 0.49,
  "l12_u": 399.47,
  "l23_u": 401.21,
  "l31_u": 399.95,
  "f": 50.01
}

metric

Example:

{
  "timestamp": 1535104800000,
  "id": 54,
  "value": 49.97
}

pyranometer

Example:

{
  "timestamp": 1535104800000,
  "id": 1,
  "irr": 1338.50
}

renewable

Example:

{
  "timestamp": 1535104800000,
  "id": 1,
  "p": 561.77,
  "q": 17.91
}

setpoint

Example:

{
  "timestamp": 1535104800000,
  "id": 3,
  "p": 269.96,
  "q": 0.00,
  "command": 5
}

status

Example:

{
  "timestamp": 1535104800000,
  "id": 102,
  "value": 3
}

thermometer

Example:

{
  "timestamp": 1535104800000,
  "id": 10,
  "t": 25.50
}

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/v1/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/v1/<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/v1/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/v1/<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/v1/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/v1/<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/v1/100/commitment"

The above command returns JSON structured like this:

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

HTTP Request

PUT https://api.edf-sf.com/v1/<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/v1/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/v1/<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/v1/100/tariff"

The above command returns JSON structured like this:

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

HTTP Request

PUT https://api.edf-sf.com/v1/<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 battery 1
endpoint = "https://api-preprod.edf-sf.com/v1/100/production/battery/1"

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