Version 1.3
Summary
Resource |
Operation |
Description |
---|---|---|
Asset |
Retrieve entity addresses of connections |
|
Control |
Download control signal from the platform |
|
Upload flexibility constraints to the platform |
||
Data |
Download meter data from the platform |
|
Download prognosis from the platform |
||
Upload meter data to the platform |
||
Upload price data to the platform |
||
Upload prognosis to the platform |
||
Upload weather data to the platform |
||
Public |
List available API versions |
|
Obtain an authentication token |
||
Obtain a service listing for this version |
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)
- GET /api/v1_3/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
Authorization – The authentication token
Content-Type – application/json
- Response Headers
Content-Type – application/json
- Status Codes
200 OK – PROCESSED
400 Bad Request – INVALID_MESSAGE_TYPE
401 Unauthorized – UNAUTHORIZED
403 Forbidden – INVALID_SENDER
405 Method Not Allowed – INVALID_METHOD
- GET /api/v1_3/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
Authorization – The authentication token
Content-Type – application/json
- Response Headers
Content-Type – application/json
- Status Codes
200 OK – PROCESSED
400 Bad Request – INVALID_MESSAGE_TYPE, INVALID_TIMEZONE, INVALID_DOMAIN, INVALID_UNIT, UNKNOWN_SCHEDULE, UNRECOGNIZED_CONNECTION_GROUP, or UNRECOGNIZED_UDI_EVENT
401 Unauthorized – UNAUTHORIZED
403 Forbidden – INVALID_SENDER
405 Method Not Allowed – INVALID_METHOD
422 Unprocessable Entity – UNPROCESSABLE_ENTITY
- GET /api/v1_3/getMeterData
API endpoint to get meter data.
Optional fields
“resolution” (see Resolutions)
“horizon” (see Tracking the recording time of beliefs)
“prior” (see Tracking the recording time of beliefs)
“source” (see Sources)
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
Authorization – The authentication token
Content-Type – application/json
- Response Headers
Content-Type – application/json
- Status Codes
200 OK – PROCESSED
400 Bad Request – INVALID_DOMAIN, INVALID_MESSAGE_TYPE, INVALID_SOURCE, INVALID_TIMEZONE, INVALID_UNIT, UNRECOGNIZED_ASSET, or UNRECOGNIZED_CONNECTION_GROUP
401 Unauthorized – UNAUTHORIZED
403 Forbidden – INVALID_SENDER
405 Method Not Allowed – INVALID_METHOD
- GET /api/v1_3/getPrognosis
API endpoint to get prognosis.
Optional fields
“resolution” (see Resolutions)
“horizon” (see Tracking the recording time of beliefs)
“prior” (see Tracking the recording time of beliefs)
“source” (see Sources)
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
Authorization – The authentication token
Content-Type – application/json
- Response Headers
Content-Type – application/json
- Status Codes
200 OK – PROCESSED
400 Bad Request – INVALID_MESSAGE_TYPE, INVALID_SOURCE, INVALID_TIMEZONE, INVALID_UNIT, UNRECOGNIZED_ASSET, or UNRECOGNIZED_CONNECTION_GROUP
401 Unauthorized – UNAUTHORIZED
403 Forbidden – INVALID_SENDER
405 Method Not Allowed – INVALID_METHOD
- GET /api/v1_3/getService
API endpoint to get a service listing for this version.
- Response Headers
Content-Type – application/json
- Status Codes
200 OK – PROCESSED
- POST /api/v1_3/postMeterData
API endpoint to post meter data.
Optional fields
“horizon” (see Setting the recording time)
Example request
This “PostMeterDataRequest” message posts measured consumption for 15-minute intervals between 0.00am and 1.30am for charging stations 1, 2 and 3 (negative values denote production).
{ "type": "PostMeterDataRequest", "groups": [ { "connections": [ "CS 1", "CS 3" ], "values": [ 306.66, 306.66, 0, 0, 306.66, 306.66 ] }, { "connections": [ "CS 2" ], "values": [ 306.66, 0, 0, 0, 306.66, 306.66 ] } ], "start": "2015-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
Authorization – The authentication token
Content-Type – application/json
- Response Headers
Content-Type – application/json
- Status Codes
200 OK – PROCESSED
400 Bad Request – INVALID_DOMAIN, INVALID_MESSAGE_TYPE, INVALID_TIMEZONE, INVALID_UNIT, REQUIRED_INFO_MISSING, UNRECOGNIZED_ASSET or UNRECOGNIZED_CONNECTION_GROUP
401 Unauthorized – UNAUTHORIZED
403 Forbidden – INVALID_SENDER
405 Method Not Allowed – INVALID_METHOD
- POST /api/v1_3/postPriceData
API endpoint to post price data.
Optional fields
“horizon” (see Setting the recording time)
Example request
This “PostPriceDataRequest” message posts prices for hourly intervals between midnight and midnight the next day for the EPEX SPOT day-ahead auction. The horizon indicates that the prices were published at 1pm on December 31st 2014 (i.e. 35 hours ahead of midnight the next day).
{ "type": "PostPriceDataRequest", "market": "ea1.2021-01.io.flexmeasures.company:epex_da", "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": "2015-01-01T15:00:00+09:00", "duration": "PT24H", "horizon": "PT35H", "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
Authorization – The authentication token
Content-Type – application/json
- Response Headers
Content-Type – application/json
- Status Codes
200 OK – PROCESSED
400 Bad Request – INVALID_DOMAIN, INVALID_MESSAGE_TYPE, INVALID_TIMEZONE, INVALID_UNIT, REQUIRED_INFO_MISSING, UNRECOGNIZED_ASSET or UNRECOGNIZED_MARKET
401 Unauthorized – UNAUTHORIZED
403 Forbidden – INVALID_SENDER
405 Method Not Allowed – INVALID_METHOD
- POST /api/v1_3/postPrognosis
API endpoint to post prognoses about meter data.
Optional fields
“horizon” (see Setting the recording time)
Example request
This “PostPrognosisRequest” message posts prognosed consumption for 15-minute intervals between 0.00am and 1.30am for charging stations 1, 2 and 3 (negative values denote production), prognosed at 6pm the previous day.
{ "type": "PostPrognosisRequest", "groups": [ { "connections": [ "CS 1", "CS 3" ], "values": [ 300, 300, 300, 0, 0, 300 ] }, { "connections": [ "CS 2" ], "values": [ 300, 0, 0, 0, 300, 300 ] } ], "start": "2015-01-01T00:00:00Z", "duration": "PT1H30M", "horizon": "PT7H30M", "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
Authorization – The authentication token
Content-Type – application/json
- Response Headers
Content-Type – application/json
- Status Codes
200 OK – PROCESSED
400 Bad Request – INVALID_MESSAGE_TYPE, INVALID_TIMEZONE, INVALID_UNIT, REQUIRED_INFO_MISSING, UNRECOGNIZED_ASSET or UNRECOGNIZED_CONNECTION_GROUP
401 Unauthorized – UNAUTHORIZED
403 Forbidden – INVALID_SENDER
405 Method Not Allowed – INVALID_METHOD
- POST /api/v1_3/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
Authorization – The authentication token
Content-Type – application/json
- Response Headers
Content-Type – application/json
- Status Codes
200 OK – PROCESSED
400 Bad Request – INCOMPLETE_UDI_EVENT, INVALID_MESSAGE_TYPE, INVALID_TIMEZONE, INVALID_DATETIME, INVALID_DOMAIN, INVALID_UNIT, OUTDATED_UDI_EVENT, PTUS_INCOMPLETE, OUTDATED_UDI_EVENT or UNRECOGNIZED_UDI_EVENT
401 Unauthorized – UNAUTHORIZED
403 Forbidden – INVALID_SENDER
405 Method Not Allowed – INVALID_METHOD
- POST /api/v1_3/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)
The sensor type is part of the unique entity address for each sensor, together with the sensor’s latitude and longitude.
Optional fields
“horizon” (see Setting the recording time)
Example request
This “PostWeatherDataRequest” message posts temperature forecasts for 15-minute intervals between 3.00pm and 4.30pm for a weather sensor located at latitude 33.4843866 and longitude 126.477859. The forecasts were made at noon.
{ "type": "PostWeatherDataRequest", "groups": [ { "sensor": "ea1.2021-01.io.flexmeasures.company:temperature:33.4843866:126.477859", "values": [ 20.04, 20.23, 20.41, 20.51, 20.55, 20.57 ] } ], "start": "2015-01-01T15:00:00+09:00", "duration": "PT1H30M", "horizon": "PT3H", "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
Authorization – The authentication token
Content-Type – application/json
- Response Headers
Content-Type – application/json
- Status Codes
200 OK – PROCESSED
400 Bad Request – INVALID_DOMAIN, INVALID_MESSAGE_TYPE, INVALID_TIMEZONE, INVALID_UNIT, REQUIRED_INFO_MISSING, UNRECOGNIZED_ASSET or UNRECOGNIZED_SENSOR
401 Unauthorized – UNAUTHORIZED
403 Forbidden – INVALID_SENDER
405 Method Not Allowed – INVALID_METHOD