Version 2.0

Summary

Resource

Operation

Description

Asset

DELETE /api/v2_0/asset/(id)

Delete an asset, together with its existing data.

GET /api/v2_0/asset/(id)

Get an asset

PATCH /api/v2_0/asset/(id)

Patch data for an existing asset

GET /api/v2_0/assets

Download asset list

POST /api/v2_0/assets

Post a new asset

GET /api/v2_0/getConnection

Retrieve entity addresses of connections

Chart

GET /api/v2_0/charts/power

Get a power chart

GET /api/v2_0/charts/power

Control

GET /api/v2_0/getDeviceMessage

Download control signal from the platform

POST /api/v2_0/postUdiEvent

Upload flexibility constraints to the platform

Data

GET /api/v2_0/getMeterData

Download meter data from the platform

GET /api/v2_0/getPrognosis

Download prognosis from the platform

POST /api/v2_0/postMeterData

Upload meter data to the platform

POST /api/v2_0/postPriceData

Upload price data to the platform

POST /api/v2_0/postPrognosis

Upload prognosis to the platform

POST /api/v2_0/postWeatherData

Upload weather data to the platform

Public

GET /api/

List available API versions

POST /api/requestAuthToken

Obtain an authentication token

GET /api/v2_0/getService

Obtain a service listing for this version

User

GET /api/v2_0/user/(id)

Get a user

PATCH /api/v2_0/user/(id)

Patch data for an existing user

PATCH /api/v2_0/user/(id)/password-reset

Password reset

GET /api/v2_0/users

Download user list

API Details

GET /api/

Public endpoint to list API versions.

POST /api/requestAuthToken

API endpoint to get a fresh authentication access token. Be aware that this fresh token has a limited lifetime (which depends on the current system setting SECURITY_TOKEN_MAX_AGE).

Pass the email parameter to identify the user. Pass the password parameter to authenticate the user (if not already authenticated in current session)

DELETE /api/v2_0/asset/(id)

API endpoint to delete an asset, and its sensed data.

This endpoint deletes an existing asset, as well as all measurements recorded for it. Only users who own the asset are allowed to delete the asset.

Warning

This API will be replaced by the new-style asset and sensor APIs. The former is already working at at /api/dev/generic_assets. See also A note on the ongoing data model transition.

Request Headers
Response Headers
Status Codes
GET /api/v2_0/asset/(id)

API endpoint to get an asset.

This endpoint gets an asset. Only users who own the asset can use this endpoint.

Warning

This API will be replaced by the new-style asset and sensor APIs. The former is already working at at /api/dev/generic_assets. See also A note on the ongoing data model transition.

Example response

{
    "asset_type": "battery",
    "capacity_in_mw": 2.0,
    "display_name": "Test battery",
    "event_resolution": 5,
    "id": 1,
    "latitude": 10,
    "longitude": 100,
    "market_id": 1,
    "max_soc_in_mwh": 5,
    "min_soc_in_mwh": 0,
    "name": "Test battery",
    "owner_id": 2,
    "soc_datetime": "2015-01-01T00:00:00+00:00",
    "soc_in_mwh": 2.5,
    "soc_udi_event_id": 203,
    "unit": "kW"
}
Request Headers
Response Headers
Status Codes
PATCH /api/v2_0/asset/(id)

API endpoint to patch asset data.

This endpoint sets data for an existing asset. Any subset of asset fields can be sent. Only users who own the asset are allowed to update its data.

Warning

This API will be replaced by the new-style asset and sensor APIs. The former is already working at at /api/dev/generic_assets. See also A note on the ongoing data model transition.

Several fields are not allowed to be updated, e.g. id. They are ignored.

Example request

{
    "latitude": 11.1,
    "longitude": 99.9,
}

Note that event_resolution is expected as the number of minutes and soc_datetime is expected as ISO8601 datetime string.

Example response

The whole asset is returned in the response:

{
    "asset_type": "battery",
    "capacity_in_mw": 2.0,
    "display_name": "Test battery",
    "event_resolution": 5,
    "id": 1,
    "latitude": 11.1,
    "longitude": 99.9,
    "market_id": 1,
    "max_soc_in_mwh": 5,
    "min_soc_in_mwh": 0,
    "name": "Test battery",
    "owner_id": 2,
    "soc_datetime": "2015-01-01T00:00:00+00:00",
    "soc_in_mwh": 2.5,
    "soc_udi_event_id": 203,
    "unit": "kW"
}
Request Headers
Response Headers
Status Codes
GET /api/v2_0/assets

API endpoint to get assets.

This endpoint returns all accessible assets for a given owner. The owner_id query parameter can be used to set an owner. If no owner is set, all accessible assets are returned. A non-admin user can only access their own assets.

Warning

This API will be replaced by the new-style asset and sensor APIs. The former is already working at at /api/dev/generic_assets. See also A note on the ongoing data model transition.

Example response

An example of one asset being returned:

[
    {
        "asset_type": "battery",
        "capacity_in_mw": 2.0,
        "display_name": "Test battery",
        "event_resolution": 10,
        "id": 1,
        "latitude": 10,
        "longitude": 100,
        "market_id": 1,
        "max_soc_in_mwh": 5,
        "min_soc_in_mwh": 0,
        "name": "Test battery",
        "owner_id": 2,
        "soc_datetime": "2015-01-01T00:00:00+00:00",
        "soc_in_mwh": 2.5,
        "soc_udi_event_id": 203,
        "unit": "MW"
    }
]

Note that event_resolution is returned as the number of minutes and soc_datetime is returned as ISO8601 datetime string.

Request Headers
Response Headers
Status Codes
POST /api/v2_0/assets

API endpoint to post a new asset.

This endpoint creates a new asset. Only users with the admin role are allowed to create assets.

Warning

This API will be replaced by the new-style asset and sensor APIs. The former is already working at at /api/dev/generic_assets. See also A note on the ongoing data model transition.

Example request

The following example contains the required fields only, plus the two state of charge (soc) fields which a battery asset needs to specify:

{
    "name": "Test battery",
    "asset_type": "battery",
    "unit": "kW",
    "owner_id": 2,
    "market_id": 1,
    "event_resolution": 5,
    "capacity_in_mw": 4.2,
    "latitude": 40,
    "longitude": 170.3,
    "max_soc_in_mwh": 5,
    "min_soc_in_mwh": 0
}

Note that event_resolution is expected as the number of minutes and soc_datetime is expected as ISO8601 datetime string.

Example response

The newly posted asset, including all fields, is returned in the response:

{
    "id": 1,
    "asset_type": "battery",
    "unit": "kW"
    "capacity_in_mw": 4.2,
    "display_name": "Test battery",
    "event_resolution": 5,
    "latitude": 40,
    "longitude": 170.3,
    "max_soc_in_mwh": 5,
    "min_soc_in_mwh": 0,
    "name": "Test battery",
    "owner_id": 2,
    "market_id": 1,
    "soc_datetime": null,
    "soc_in_mwh": null,
    "soc_udi_event_id": null
}
Request Headers
Response Headers
Status Codes
GET /api/v2_0/charts/power
GET /api/v2_0/charts/power

API endpoint to get a chart for power data which can be embedded in web pages.

This endpoint returns a Bokeh chart with power data which can be embedded in a website. It includes forecasts and even schedules, if available.

Example request

An example of a chart request:

{
    "resource": ""my-battery,
    "start_time": "2020-02-20:10:00:00UTC",
    "end_time": "2020-02-20:11:00:00UTC",
    "resolution": "PT15M",
    "consumption_as_positive": true
    "resolution": "PT6H",
    "show_individual_traces_for": "none"  // can be power or schedules
}

On your webpage, you need to include the Bokeh libraries, e.g.:

(The version needs to match the version used by the FlexMeasures server, see requirements/app.txt)

Then you can call this endpoint and include the result like this:

<script>
    fetch('http://localhost:5000/api/v2_0/charts/power?' + urlData.toString(),
    {
        method: "GET",
        mode: "cors",
        headers:
            {
                "Content-Type": "application/json",
                "Authorization": "<users auth token>"
            },
    })
    .then(function(response) { return response.json(); })
    .then(function(item) { Bokeh.embed.embed_item(item, "<ID of the div >"); });
</script>

where urlData is a URLSearchData object and contains the chart request parameters (see above).

Request Headers
Response Headers
Status Codes
GET /api/v2_0/getConnection

API endpoint to get the user’s connections as entity addresses ordered from newest to oldest.

Example request

{
    "type": "GetConnectionRequest",
}

Example response

This “GetConnectionResponse” message indicates that the user had access rights to retrieve four entity addresses owned by three different users.

{
    "type": "GetConnectionResponse",
    "connections": [
        "ea1.2021-01.io.flexmeasures.company:3:4",
        "ea1.2021-01.io.flexmeasures.company:8:3",
        "ea1.2021-01.io.flexmeasures.company:9:2",
        "ea1.2021-01.io.flexmeasures.company:3:1"
    ],
    "names": [
        "CS 4",
        "CS 3",
        "CS 2",
        "CS 1"
    ]
}
Request Headers
Response Headers
Status Codes
GET /api/v2_0/getDeviceMessage

API endpoint to get device message.

Optional fields

  • “duration” (6 hours by default; can be increased to plan further into the future)

Example request

This “GetDeviceMessageRequest” message requests targeted consumption for UDI event 203 of device 10 of owner 7.

{
    "type": "GetDeviceMessageRequest",
    "event": "ea1.2021-01.io.flexmeasures.company:fm0.7:10:203:soc"
}

Example response

This “GetDeviceMessageResponse” message indicates that the target for UDI event 203 is to consume at various power rates from 10am UTC onwards for a duration of 45 minutes.

{
    "type": "GetDeviceMessageResponse",
    "event": "ea1.2021-01.io.flexmeasures.company:fm0.7:10:203:soc",
    "values": [
        2.15,
        3,
        2
    ],
    "start": "2015-06-02T10:00:00+00:00",
    "duration": "PT45M",
    "unit": "MW"
}
Request Headers
Response Headers
Status Codes
GET /api/v2_0/getMeterData

API endpoint to get meter data.

Optional fields

Example request

This “GetMeterDataRequest” message requests measured consumption between 0.00am and 1.30am for charging station 1.

{
    "type": "GetMeterDataRequest",
    "connection": "CS 1",
    "start": "2015-01-01T00:00:00Z",
    "duration": "PT1H30M",
    "unit": "MW"
}

Example response

This “GetMeterDataResponse” message indicates that consumption for charging station 1 was measured in 15-minute intervals.

{
    "type": "GetMeterDataResponse",
    "connection": "CS 1",
    "values": [
        306.66,
        306.66,
        0,
        0,
        306.66,
        306.66
    ],
    "start": "2015-01-01T00:00:00Z",
    "duration": "PT1H30M",
    "unit": "MW"
}
Request Headers
Response Headers
Status Codes
GET /api/v2_0/getPrognosis

API endpoint to get prognosis.

Optional fields

Example request

This “GetPrognosisRequest” message requests prognosed consumption between 0.00am and 1.30am for charging station 1, with a rolling horizon of 6 hours before the end of each 15 minute time interval.

{
    "type": "GetPrognosisRequest",
    "connection": "CS 1",
    "start": "2015-01-01T00:00:00Z",
    "duration": "PT1H30M",
    "horizon": "PT6H",
    "resolution": "PT15M",
    "unit": "MW"
}

Example response

This “GetPrognosisResponse” message indicates that a prognosis of consumption for charging station 1 was available 6 hours before the start of each 15 minute time interval.

{
    "type": "GetPrognosisResponse",
    "connection": "CS 1",
    "values": [
        306.66,
        306.66,
        0,
        0,
        306.66,
        306.66
    ],
    "start": "2015-01-01T00:00:00Z",
    "duration": "PT1H30M",
    "unit": "MW"
}
Request Headers
Response Headers
Status Codes
GET /api/v2_0/getService

API endpoint to get a service listing for this version.

Response Headers
Status Codes
POST /api/v2_0/postMeterData

API endpoint to post meter data.

Optional fields

Example request

This “PostMeterDataRequest” message posts measured consumption for 15-minute intervals between 0.00am and 1.30am for connections 3, 4 and 5 (negative values denote production).

{
    "type": "PostMeterDataRequest",
    "groups": [
        {
            "connections": [
                "ea1.2021-01.io.flexmeasures.company:fm1.3",
                "ea1.2021-01.io.flexmeasures.company:fm1.4"
            ],
            "values": [
                306.66,
                306.66,
                0,
                0,
                306.66,
                306.66
            ]
        },
        {
            "connections": [
                "ea1.2021-01.io.flexmeasures.company:fm1.5"
            ],
            "values": [
                306.66,
                0,
                0,
                0,
                306.66,
                306.66
            ]
        }
    ],
    "start": "2021-01-01T00:00:00Z",
    "duration": "PT1H30M",
    "unit": "MW"
}

It is allowed to send higher resolutions (in this example for instance, 30 minutes) which will be upsampled.

Example response

This “PostMeterDataResponse” message indicates that the measurement has been processed without any error.

{
    "type": "PostMeterDataResponse",
    "status": "PROCESSED",
    "message": "Request has been processed."
}
Request Headers
Response Headers
Status Codes
POST /api/v2_0/postPriceData

API endpoint to post price data.

Optional fields

Example request

This “PostPriceDataRequest” message posts prices for hourly intervals between midnight and midnight the next day for the EPEX SPOT day-ahead auction, registered as sensor 12. The prior indicates that the prices were published at 1pm on December 31st 2020.

{
    "type": "PostPriceDataRequest",
    "market": "ea1.2021-01.io.flexmeasures.company:fm1.12",
    "values": [
        52.37,
        51.14,
        49.09,
        48.35,
        48.47,
        49.98,
        58.7,
        67.76,
        69.21,
        70.26,
        70.46,
        70,
        70.7,
        70.41,
        70,
        64.53,
        65.92,
        69.72,
        70.51,
        75.49,
        70.35,
        70.01,
        66.98,
        58.61
    ],
    "start": "2021-01-01T00:00:00+01:00",
    "duration": "PT24H",
    "prior": "2020-12-31T13:00:00+01:00",
    "unit": "EUR/MWh"
}

Example response

This “PostPriceDataResponse” message indicates that the prices have been processed without any error.

{
    "type": "PostPriceDataResponse",
    "status": "PROCESSED",
    "message": "Request has been processed."
}
Request Headers
Response Headers
Status Codes
POST /api/v2_0/postPrognosis

API endpoint to post prognoses about meter data.

Optional fields

Example request

This “PostPrognosisRequest” message posts prognosed consumption for 15-minute intervals between 0.00am and 1.30am for connections 3, 4 and 5 (negative values denote production), prognosed at 6pm the previous day.

{
    "type": "PostPrognosisRequest",
    "groups": [
        {
            "connections": [
                "ea1.2021-01.io.flexmeasures.company:fm1.3",
                "ea1.2021-01.io.flexmeasures.company:fm1.4"
            ],
            "values": [
                300,
                300,
                300,
                0,
                0,
                300
            ]
        },
        {
            "connections": [
                "ea1.2021-01.io.flexmeasures.company:fm1.5"
            ],
            "values": [
                300,
                0,
                0,
                0,
                300,
                300
            ]
        }
    ],
    "start": "2021-01-01T00:00:00Z",
    "duration": "PT1H30M",
    "prior": "2020-12-31T18:00:00Z",
    "unit": "MW"
}

It is allowed to send higher resolutions (in this example for instance, 30 minutes) which will be upsampled.

Example response

This “PostPrognosisResponse” message indicates that the prognosis has been processed without any error.

{
    "type": "PostPrognosisResponse",
    "status": "PROCESSED",
    "message": "Request has been processed."
}
Request Headers
Response Headers
Status Codes
POST /api/v2_0/postUdiEvent

API endpoint to post UDI event. (UDI is the Universal Device Interface proposed by USEF for flexible device states)

Example request A

This “PostUdiEventRequest” message posts a state of charge (soc) of 12.1 kWh at 10.00am as UDI event 203 of device 10 of owner 7.

{
    "type": "PostUdiEventRequest",
    "event": "ea1.2021-01.io.flexmeasures.company:7:10:203:soc",
    "value": 12.1,
    "unit": "kWh",
    "datetime": "2015-06-02T10:00:00+00:00"
}

Example request B

This “PostUdiEventRequest” message posts a state of charge (soc) of 12.1 kWh at 10.00am, and a target state of charge of 25 kWh at 4.00pm, as UDI event 204 of device 10 of owner 7. The minimum and maximum soc are set to 10 and 25 kWh, respectively. Roundtrip efficiency for use in scheduling is set to 98%.

{
    "type": "PostUdiEventRequest",
    "event": "ea1.2021-01.io.flexmeasures.company:fm0.7:10:204:soc-with-targets",
    "value": 12.1,
    "unit": "kWh",
    "datetime": "2015-06-02T10:00:00+00:00",
    "targets": [
        {
            "value": 25,
            "datetime": "2015-06-02T16:00:00+00:00"
        }
    ],
    "soc_min": 10,
    "soc_max": 25,
    "roundtrip_efficiency": 0.98
}

Example response

This “PostUdiEventResponse” message indicates that the UDI event has been processed without any error.

{
    "type": "PostUdiEventResponse",
    "status": "PROCESSED",
    "message": "Request has been processed."
}
Request Headers
Response Headers
Status Codes
POST /api/v2_0/postWeatherData

API endpoint to post weather data, such as:

  • “irradiance” (with kW/m² as unit)

  • “temperature” (with °C as unit)

  • “wind speed” (with m/s as unit)

Optional fields

Example request

This “PostWeatherDataRequest” message posts temperature forecasts for 15-minute intervals between 3.00pm and 4.30pm for a weather sensor with id 602. The forecasts were made at noon.

{
    "type": "PostWeatherDataRequest",
    "groups": [
        {
            "sensor": "ea1.2021-01.io.flexmeasures.company:fm1.602",
            "values": [
                20.04,
                20.23,
                20.41,
                20.51,
                20.55,
                20.57
            ]
        }
    ],
    "start": "2021-01-01T15:00:00+09:00",
    "duration": "PT1H30M",
    "prior": "2021-01-01T12:00:00+09:00",
    "unit": "°C"
}

It is allowed to send higher resolutions (in this example for instance, 30 minutes) which will be upsampled.

Example response

This “PostWeatherDataResponse” message indicates that the forecast has been processed without any error.

{
    "type": "PostWeatherDataResponse",
    "status": "PROCESSED",
    "message": "Request has been processed."
}
Request Headers
Response Headers
Status Codes
GET /api/v2_0/user/(id)

API endpoint to get a user.

This endpoint gets a user. Only admins or the user themselves can use this endpoint.

Example response

{
    'account_id': 1,
    'active': True,
    'email': 'test_prosumer@seita.nl',
    'flexmeasures_roles': [1, 3],
    'id': 1,
    'timezone': 'Europe/Amsterdam',
    'username': 'Test Prosumer User'
}
Request Headers
Response Headers
Status Codes
PATCH /api/v2_0/user/(id)

API endpoint to patch user data.

This endpoint sets data for an existing user. Any subset of user fields can be sent. Only the user themselves or admins are allowed to update its data, while a non-admin can only edit a few of their own fields.

Several fields are not allowed to be updated, e.g. id and account_id. They are ignored.

Example request

{
    "active": false,
}

Example response

The whole user is returned in the response:

{
    'account_id': 1,
    'active': True,
    'email': 'test_prosumer@seita.nl',
    'flexmeasures_roles': [1, 3],
    'id': 1,
    'timezone': 'Europe/Amsterdam',
    'username': 'Test Prosumer User'
}
Request Headers
Response Headers
Status Codes
PATCH /api/v2_0/user/(id)/password-reset

API endpoint to reset the user password. They’ll get an email to choose a new password.

Reset the user’s password, and send them instructions on how to reset the password. This endpoint is useful from a security standpoint, in case of worries the password might be compromised. It sets the current password to something random, invalidates cookies and auth tokens, and also sends an email for resetting the password to the user.

Users can reset their own passwords. Only admins can use this endpoint to reset passwords of other users.

Request Headers
Response Headers
Status Codes
GET /api/v2_0/users

API endpoint to get users.

This endpoint returns all accessible users. By default, only active users are returned. The include_inactive query parameter can be used to also fetch inactive users. Accessible users are users in the same account as the current user. Only admins can use this endpoint to fetch users from a different account (by using the account_id query parameter).

Example response

An example of one user being returned:

[
    {
        'active': True,
        'email': 'test_prosumer@seita.nl',
        'account_id': 13,
        'flexmeasures_roles': [1, 3],
        'id': 1,
        'timezone': 'Europe/Amsterdam',
        'username': 'Test Prosumer User'
    }
]
Request Headers
Response Headers
Status Codes