Smart Energy Grids have been subjects to extensive research during the last few years. The rapid development of highly effective communication technologies, in combination with the ever increasing computation capacity of contemporary data centres have assisted towards the design of such Grids. However, not all technical barriers have been eradicated, rendering their implementation, in many cases, impractical. Furthermore, most of the times Energy Utilities rely on proprietary software to power their Smart Energy Systems, limiting their sustainability flexibility as value added services are hard to implement. In the same context, third parties are very difficult to integrate into the existing systems, increasing implementation costs and contributing to vendor lock-ins.
FINESCE, as a part of its value proposition to the European Energy sector and the FI-PPP Phase III projects, provides a unified, homogeneous Application Programming Interface (API) in an attempt to strictly define a common format of interaction among distinct Smart Energy Systems and facilitate access of third parties to the functionality of its seven trials. The FINESCE API has been built upon the functional requirements and characteristics of these trials, spanning numerous application domains ranging from Electric Vehicles monitoring, to Smart Factories and Energy Marketplaces. A detailed but not exhaustive list of supported categories is provided in the following paragraphs.
The FINESCE API specification has been integrated into a dedicated mediation service, provided in the form of an open-source Domain Specific Enabler (DSE), namely the FINESCE API Mediator DSE. The DSE has already been instantiated and can be graphically accessed through a dedicated web portal hosted in http://docs.fam.apiary.io. With the help of the FINESCE API and the aforementioned DSE, all interested parties are able to securely access the FINESCE trial infrastructures and experiment with the FINESCE API and the historical data gathered by the FINESCE partners for more than a year.
FINESCE, as a solution provider, exhibits the capabilities of Future Internet in a multitude of disciplines including, among others, low-latency Smart Grid, Smart Buildings, Electric Vehicles and Smart Factories monitoring. The functionality provided by the API as a whole is classified into 18 distinct categories, each one grouping services related to a single domain/functionality. Next, the API categories supported by the current FINESCE API specification are tabulated.
| Category | Method | Description |
|---|---|---|
| Authentication This set of APIs is used for authenticating users against oauth2 authentication and authorization services. 'Horsens', 'Malmo', 'Aachen' (VPP services), ‘Ireland’ and 'Terni' are the trials offering this service. |
Authenticate a user | Authenticates a user against a set of credentials. | Refresh a token | Retrieves a new authentication token based on a previously issued refresh token. 'Horsens', 'Malmo', 'Aachen' (VPP services) and ‘Ireland’ are the trials offering this service. |
| Building information This set of APIs provide access to information related to Smart Buildings presentation. |
List of buildings in trial | List the buildings known to the selected trial infrastructure. 'Horsens' is the only trial offering this service. | Building Description | List the properties of the identified building. The measurement types associated with the building are delivered as well. 'Horsens' is the only trial offering this service. | Get available measurement types for a specific building | Provides information regarding the available measurements types for the specific building.A valid {id} can be obtained by the /{version}/{trial}/buildings service. 'Horsens' is the only trial offering this service. | Get the available measurement for a specific building | Provides information regarding the available measurements of a specific type for a specific building, during a certain period of time. A valid {id} can be obtained by calling the /buildings service. A valid {type_id} can be obtained by calling the /buildings service and check the 'measurement_points' section of the answer. Valid {from} and {to} values are expressed in ISO8601 format. 'Horsens' is the only tria l offering this service. | Get the available building components/modules | Provides a list of devices or modules which status can be monitored by the Building Control Center.'Madrid' is the only trial offering this service. | Get the status of a building component/module | Provides information about the status of a specific building module. The available building modules may be retrieved via the /{version}/{trial}/buildings/{id}/modules service. 'Madrid' is the only trial offering this service. | Get the available building zones | Provides the provides a list of zones of a building.'Madrid' is the only trial offering this service. | Get the available measurements for a building zone | Provides measurements of a certain type of a building zone. Valid measurement types are PowerDemandGrid, EnergyConsumptionGrid, Temperature and RelativeHumidity. 'Madrid' is the only trial offering this service. | Get the available measurement types for the trial | Provides a detailed list of all the available building measurements types in the trial. 'Horsens' is the only trial offering this service. | Get the available measurement types for the trial, based on their id | Provides a detailed list of all the available measurements types that match a specific measurements type name. A valid {id} can be obtained by calling the /{version}/{trial}/buildings/measurement_types service. 'Horsens' is the only trial offering this service. | Get the available measurement types for buildings, based on their type | Provides a detailed list of all the available measurements types that match a specific measurements type. A valid {type} can be obtained by calling the /{version}/{trial}/buildings/measurement_types service and check the 'type' attribute of the answer.'Horsens' is the only trial offering this service. |
| Demand Response This group of APIs offers services related to demand/response and incentive plans, also exposing services related to contractual energy prices. |
Get the list of issue resolution plans sharing a common author | Allows a user to get a list of issue resolution plans based on their author name. 'Terni' is the only trial offering this service. | Get the list of issue resolution plans sharing a common state | Allows a user to get a list of issue resolution plans based on their state. 'Terni' is the only trial offering this service. | Get the list of issue resolution plans sharing common authors and states | Allows a user to get a list of issue resolution plans based on their state and author. 'Terni' is the only trial offering this service. | Get the list of incentive plans sharing a common author | Allows an energy retailer to get a list of incentive plans based on their author name. 'Terni' is the only trial offering this service. | Get the list of incentive plans sharing a common state | Allows an energy retailer to get a list of incentive plans based on their state. 'Terni' is the only trial offering this service. | Get the list of incentive plans sharing common authors and states | Allows an energy retailer to get a list of incentive plans based on their state and author. 'Terni' is the only trial offering this service. | Get the contracts corresponding to a customer, regardless of their state | Allows an energy retailer to get the list of contracts corresponding to a specific customer, regardless of their state. 'Terni' is the only trial offering this service. | Get the contracts characterized by a specific state | Allows an energy retailer to get the list of contracts corresponding to a specific state, regardless of the associated customer. 'Terni' is the only trial offering this service. | Get the contracts corresponding to a customer, characterized by a specific state | Allows an energy retailer to get the list of contracts sharing a common state, offered to a specific customer. 'Terni' is the only trial offering this service. | Get the user-contracted energy prices | Allows a user to get the contracted prices for electricity, based on their type. 'Terni' is the only trial offering this service. |
| Discrete Time Support This API set offers services related to supporting discrete timeslots for describing an energy report instead using of continuous entities related to normal, continuous date/time presentation. |
Get the available timeslots | Allows a user to retrieve a collection of the timeslots available in the trial infrastructure. 'Ireland' is the only trial offering this service. | Get a timeslots based on its id | Allows a user to retrieve a time slot record, based on its id. A valid {id} can be obtained by calling the /{version}/{trial}/timeslots service. 'Ireland' is the only trial offering this service. | Get the algorithmic weights associated with a timeslot, based on its id | Allows a user to retrieve a collection of algorithm weight records associated with a time slot. A valid {id} can be obtained by calling the /{version}/{trial}/timeslots service. 'Ireland' is the only trial offering this service. | Get the charging states associated with a timeslot, based on its id | Allows a user to retrieve a collection of charging state records associated with a time slot, based on its id. A valid {id} can be obtained by calling the /{version}/{trial}/timeslots service. 'Ireland' is the only trial offering this service. | Get the EVSE energy records associated with a timeslot, based on its id | Allows a user to retrieve a collection of aggregated regional electric vehicle supply equipment (EVSE) energy records associated with a specific timeslot, based on its id. A valid {id} can be obtained by calling the /{version}/{trial}/timeslots service. 'Ireland' is the only trial offering this service. |
| Energy demand / Power consumption This API set offers services for getting/updating information related to the electricity demand (consumption). |
Get the energy consumption profile of a sector | Retrieves information regarding the energy consumption profile of a specific sector, during a specific time period. A valid {sector} can be obtained by calling the /{version}/{trial}/meters/sectors service. Valid {from} and {to} values are expressed in ISO8601 format. 'Terni' is the only trial offering this service. | Get the energy consumption profile of a user | Retrieves information regarding the energy consumption profile of a specific user, during a specific time period. A valid {customer_id} can be obtained by calling the /{version}/{trial}/meters service and checking the 'customer_id' atribute of the response. Valid {from} and {to} values are expressed in ISO8601 format. 'Terni' is the only trial offering this service. | Get the total energy consumption of a user | Retrieves information regarding the total energy consumption of a specific user, during a specific time period. A valid {customer_id} can be obtained by calling the /{version}/{trial}/meters service and checking the 'customer_id' atribute of the response. Valid {from} and {to} values are expressed in ISO8601 format. 'Terni' is the only trial offering this service. | Get the power demand of a user | Retrieves information regarding the power demand of a specific user, during a specific time period. A valid {customer_id} can be obtained by calling the /{version}/{trial}/meters service and checking the 'customer_id' atributes of the response. Valid {from} and {to} values are expressed in ISO8601 format. 'Terni' is the only trial offering this service. |
| Energy supply / Power production This API set offers services for getting/updating information related to the electricity supply (production). |
Get the energy production profile of a sector | Retrieves information regarding the energy production profile of a specific sector, during a specific time period. A valid {sector} can be obtained by calling the /{version}/{trial}/meters/sectors service. Valid {from} and {to} values are expressed in ISO8601 format. 'Terni' is the only trial offering this service. | Get the energy production profile of a user | Retrieves information regarding the energy production profile of a specific user, during a specific time period. A valid {customer_id} can be obtained by calling the /{version}/{trial}/meters service and checking the 'customer_id' attribute of the response. Valid {from} and {to} values are expressed in ISO8601 format. 'Terni' is the only trial offering this service. | Get the total energy production of a user | Retrieves information regarding the total energy production of a specific user, during a specific time period. A valid {customer_id} can be obtained by calling the /{version}/{trial}/meters service and checking the 'customer_id' attribute of the response. Valid {from} and {to} values are expressed in ISO8601 format. 'Terni' is the only trial offering this service. | Get the power supply of a user | Retrieves information regarding the power supply of a specific user, during a specific time period. A valid {customer_id} can be obtained by calling the /{version}/{trial}/meters service and checking the 'customer_id' attribute of the response. Valid {from} and {to} values are expressed in ISO8601 format. 'Terni' is the only trial offering this service. | Get the power supply of a building module | Provides measurements regarding the power generated from a module of a building. Currently, 'pv' is the only module supported. Valid {date} values are expressed in ISO8601 format. 'Madrid' is the only trial site offering this service. | Get the mixed power of a building module | Provides measurements regarding the power generated & consumed (mixed) from a module of a building. Currently, 'inverter' is the only module supported. Valid {date} values are expressed in ISO8601 format. 'Madrid' is the only trial site offering this service. |
| Electric Vehicles This group of APIs offers access to information related to monitoring of Electric Vehicles and their supporting equipment. |
List of vehicles in trial | List the vehicles known to the selected trial infrastructure. 'Horsens' and 'Ireland' are the only trials offering this service. | Vehicle Description | GET /Horsens/vehicles/{id} Provides information regarding a single vehicle. A valid {id} can be found by calling the /{version}/{trial}/vehicles service. 'Horsens' and 'Ireland' are the only trials offering this service. | Vehicles measurement types | Provides a detailed list of all the available vehicle measurements types in the trial. 'Horsens' and 'Ireland' are the only trials offering this service. | Vehicles measurement types | Provides a detailed list of all the available measurements types that match a specific measurements type name. A valid {id} can be obtained by calling the /{version}/{trial}/vehicles/measurement_types service. 'Horsens' and 'Ireland' are the only trials offering this service. | Vehicles measurement types | Provides a detailed list of all the available measurements types that match a specific measurements type. A valid {type} can be obtained by calling the /{version}/{trial}/vehicles/measurement_types service and check the 'type' entries.'Horsens' and 'Ireland' are the only trials offering this service. | Measurement types of a single vehicle | Provides information regarding the available measurements types for the specific vehicle. A valid {id} can be obtained by calling the /{version}/{trial}/vehicles service. 'Horsens' and 'Ireland' are the only trials offering this service. | Measurement types of a single vehicle | Provides information regarding the available measurements of a specific type for a specific vehicle, during a certain period of time. A valid {id} can be obtained by calling the /{version}/{trial}/vehicles service. A valid {type_id} can be obtained by calling the /{version}/{trial}/vehicles service and check the 'measurement_points' section of the answer. Valid {from} and {to} values are expressed in ISO8601 format. 'Horsens' and 'Ireland' are the only trials offering this service. | Get the connections of an EV with an electric vehicle supply equipment component | Allows a user to retrieve a collection of electric vehicle - electric vehicle supply equipment (EVSE) connections associated with an electric vehicle. A valid {id} can be obtained by calling the /{version}/{trial}/vehicles/{id} service. 'Ireland' is the only trial offering this service. | Get the supported electric vehicle types | Provides information regarding the types of the electric vehicles of the trial. 'Ireland' is the only trial offering this service. | Get a specific electric vehicle type description, based on its id | Allows a user to retrieve an electric vehicle type, based on its id. A valid {id} can be obtained by calling the /{version}/{trial}/vehicle_types service. 'Ireland' is the only trial offering this service. | Get the electric vehicles sharing a common type, based on its id | Allows a user to retrieve a collection of electric vehicles associated with an electric vehicle type. A valid {id} can be obtained by calling the /{version}/{trial}/vehicle_types service. 'Ireland' is the only trial offering this service. | Get the EVs charging modes | Provides information regarding the charging modes of the electric vehicle supply equipment (EVSE) of the electric vehicles of the trial. 'Ireland' is the only trial offering this service. | Get the EVs charging modes | Allows a user to retrieve a chargingmode based on an id. A valid {id} can be obtained by calling the /{version}/{trial}/charging_modes service. 'Ireland' is the only trial offering this service. | Get the EVSEs related to a charging mode | Allows a user to retrieve a collection of evses associated with a charging mode. A valid {id} can be obtained by calling the /{version}/{trial}/charging_modes service. 'Ireland' is the only trial offering this service. | Get the EV types related to a charging mode | Allows a user to retrieve a collection of electric vehicle types associated with a charging mode. A valid {id} can be obtained by calling the /{version}/{trial}/charging_modes service. 'Ireland' is the only trial offering this service. | Get the EVs charging states | Provides information regarding the charging states of the electric vehicle supply equipment (EVSE) of the electric vehicles of the trial. 'Ireland' is the only trial offering this service. | Get an EV charging state through its id | Allows a user to retrieve a charging state based on an id. A valid {id} can be obtained by calling the /{version}/{trial}/charging_states service. 'Ireland' is the only trial offering this service. | Get the available EVSEs connections | Allows a user to retrieve a collection of the available EVSE connections. 'Ireland' is the only trial offering this service. | Get an EVSE connection through its id | Allows a user to retrieve an EVSE connection, based on its id. A valid {id} can be obtained by calling the /{version}/{trial}/connections service. 'Ireland' is the only trial offering this service. | Get an EVSE charging mode based on a connection id | Allows a user to retrieve a charging mode associated with an EVSE connection. A valid {id} can be obtained by calling the /{version}/{trial}/connections service. 'Ireland' is the only trial offering this service. | Get an EVSE connection state based on a connection id | Allows a user to retrieve an EVSE connection state associated with an ev evse connection. A valid {id} can be obtained by calling the /{version}/{trial}/connections service. 'Ireland' is the only trial offering this service. | Get the available EVSEs connection states | Allows a user to retrieve a collection of ev evse connection states. 'Ireland' is the only trial offering this service. | Get an EVSE connection state through its id | Allows a user to retrieve an EVSE connection state record, based on its id. A valid {id} can be obtained by calling the /{version}/{trial}/connection_states service. 'Ireland' is the only trial offering this service. | Get all the electric vehicle supply equipment components available | Allows a user to retrieve a collection of electric vehicle supply equipment (EVSE) components. 'Ireland' is the only trial offering this service. | Get an electric vehicle supply equipment component, based on its id | Allows a user to retrieve an electric vehicle supply equipment component (EVSE), based on its id. A valid {id} can be obtained by calling the /{version}/{trial}/supply_equipment/ service. 'Ireland' is the only trial offering this service. | Get the charging modes associated with an electric vehicle supply equipment component, based on its id | Allows a user to retrieve a collection of charging modes associated with an electric vehicle supply equipment component (EVSE), based on its id. A valid {id} can be obtained by calling the /{version}/{trial}/supply_equipment/ service. 'Ireland' is the only trial offering this service. | Get the connections associated with an electric vehicle supply equipment component, based on its id | Allows a user to retrieve a collection of electric vehicle supply equipment (EVSE) connections associated with an EVSE, based on its id. A valid {id} can be obtained by calling the /{version}/{trial}/supply_equipment/ service. 'Ireland' is the only trial offering this service. |
| External information This API is responsible for handling requests/responses from services that do not directly map to energy-related data. |
Get the latest known social events | This service is meant to offer a list of social events that can temporarily influence the electricity consumption. 'Terni' is the only trial offering this service. | Get a specific number of the latest known social events | This service is meant to offer a list containing a specific number of social events that can temporarily influence the electricity consumption. 'Terni' is the only trial offering this service. |
| Metering infrastructure details This set of APIs exposes services related to the presentation of the metering equipment of a Smart Energy site, be it a Smart Grid or a Smart Building. |
List all meters | Gets a list of the available meters along with the set of their accompanying information. | Get a specific meter description | Retrieves a meter based on a search string. | List all available sectors | Gets a list of the sectors that the meters may be deployed into. |
| Optimization This group of APIs offers access to supported optimization engines and their parametrization. |
List available algorithm weights | Allows a user to retrieve a collection of algoweights. 'Ireland' is the only trial offering this service. | List available algorithm weights | Allows a user to retrieve an algoweights record, based on its ID. A valid {id} can be obtained by calling the /algoweights service. 'Ireland' is the only trial offering this service. |
| Pricing This group of APIs provides information related to energy pricing at a regional level or customer level. |
Get the available energy prices in a trial | Allows a user to get information regarding the energy prices in the wider area of a trial. 'Malmo' is the only trial offering this service. | Get the available energy prices in a trial within a time range | Allows a user to get information regarding the energy prices regardless of location. Valid {from} and {to} values are expressed in ISO8601 format. 'Malmo' is the only trial offering this service. | Get the available energy prices in a trial location, based on its name | Allows a user to get information regarding the energy prices in a location. A valid {name} can be obtained by calling the /{version}/{trial}/prices service and checking the location_name fields. 'Malmo' is the only trial offering this service. | Get the available energy prices within a time range in a trial location, based on its name | Allows a user to get information regarding the energy prices in a location. A valid {name} can be obtained by calling the /{version}/{trial}/prices service and checking the location_name fields. Valid {from} and {to} values are expressed in ISO8601 format. 'Malmo' is the only trial offering this service. | Get the price locations available to the user | Allows a user to get information regarding the price locations available to the user. 'Malmo' is the only trial offering this service. | Get a price location based on its name | Allows a user to get information regarding a price location available to the user, based on the location name. A valid {name} can be obtained by calling the /{version}/{trial}/prices/locations service. 'Malmo' is the only trial offering this service. | Get a data stream for all the available pricing locations | Allows a user to get information regarding a data stream available for locations associated with the current user. 'Malmo' is the only trial offering this service. | Get a data stream for a specific pricing location | Allows a user to get information regarding a data stream available for locations associated with the current user. A valid {name} can be obtained by calling the /{version}/{trial}/prices/locations service. 'Malmo' is the only trial offering this service. | Get a data stream for a specific pricing location, for a specific period of time | Allows a user to get information regarding a data stream available for locations associated with the current user. A valid {name} can be obtained by calling the /{version}/{trial}/prices/locations service. 'Malmo' is the only trial offering this service. |
| Regional Energy-Related Information This API set offers services related to regional information related to energy resources. |
Get the available regions | Allows a user to retrieve a collection of regions supported by the trial. 'Ireland' is the only trial offering this service. | Get a region based on its ID | Allows a user to retrieve a region record, based on its ID. A valid {id} can be obtained by calling the /{version}/{trial}/regions service. 'Ireland' is the only trial offering this service. | Get the algorithmic optimization weights associated with a region | Allows a user to retrieve the algorithm weights set associated with a region. A valid {id} can be obtained by calling the /{version}/{trial}/regions service. 'Ireland' is the only trial offering this service. | Get an energy report associated with a region | Allows a user to retrieve a collection of aggregated regional electric vehicle supply equipment (EVSE) energy records. A valid {id} can be obtained by calling the /{version}/{trial}/regions service. 'Ireland' is the only trial offering this service. | Get an average energy report associated with a region | Allows a user to retrieve a collection of aggregate regional electric vehicle supply equipment (EVSE) energy records associated with a region, based on its ID. A valid {id} can be obtained by calling the /{version}/{trial}/regions service. 'Ireland' is the only trial offering this service. | Get the EVSE entities associated with a region | Allows a user to retrieve a collection of electric vehicle supply equipment (EVSE) entities associated with a region. A valid {id} can be obtained by calling the /{version}/{trial}/regions service. 'Ireland' is the only trial offering this service. | Get the energy status of the trial regions | Allows a user to retrieve a list of regional energy data objects. 'Ireland' is the only trial offering this service. | Get the energy status of a region | Allows a user to retrieve a regional energy record. A valid {id} can be obtained by calling the /{version}/{trial}/energy/regional service. 'Ireland' is the only trial offering this service. | Get a region associated with a regional energy record | Allows a user to retrieve a region associated with a regional energy record. A valid {id} can be obtained by calling the /{version}/{trial}/energy/regional service. 'Ireland' is the only trial offering this service. | Get a timeslot associated with a regional energy record | Allows a user to retrieve a timelsot associated with a regional energy record. A valid {id} can be obtained by calling the /{version}/{trial}/energy/regional service. 'Ireland' is the only trial offering this service. | Get the average EVSE regional energy records | Allows a user to retrieve a collection of aggregated regional electric vehicle supply equipment (EVSE) energy records. 'Ireland' is the only trial offering this service. | Get an average EVSE regional energy record | Allows a user to retrieve an aggregated regional electric vehicle supply equipment (EVSE) energy record. A valid {id} can be obtained by calling the /{version}/{trial}/energy/regional service. 'Ireland' is the only trial offering this service. |
| Simulation This set of APIs may be used to retrieve simulated values for various smart grid/city aspects. |
Prediction of user power demand | Returns a simulated power demand prediction for a specific user, based on his/her id. 'Terni' is the only trial offering this service. | Prediction of sector power demand | Returns a simulated power demand prediction for a specific sector. 'Terni' is the only trial offering this service. | Prediction of user power supply | Returns a simulated power supply prediction for a specific user, based on his/her id. 'Terni' is the only trial offering this service. | Prediction of sector power supply | Returns a simulated power supply for a specific sector. 'Terni' is the only trial offering this service. |
| Smart Factories This set of APIs offers information related to the monitoring and control of equipment of a smart factory. |
Available machines | Gets the list of available machines of the factory. | Information over a single machine | Gets detailed, historical information regarding a single machine, based on its id. |
| Virtual Power Plant This set of APIs offers information regarding the operation of Virtual Power Plants (VPP). |
Get VPP components data | Gets the available components of the VPP. Currently, 'Aachen' is the only trial offering this service. | Get the data of a specific VPP component | Gets the list of dates of available data for a component. The {comp_type} can be either 'production' or 'consumption'. A valid {comp_id} can be found from the /{version}/{trial}/vpp/components service. Currently, 'Aachen' is the only trial offering this service. | Get the measurements of a specific VPP component in a day | Gets measurement data for component for a specified data and data type. The {comp_type} can be either 'production' or 'consumption'. A valid {comp_id} can be found from the /{version}/{trial}/vpp/components service. A valid {date} can be found from the /{version}/{trial}/vpp/{comp_type}/{comp_id}/data service. Currently, 'Aachen' is the only trial offering this service. | Get the predictions for a specific VPP component in a day | Gets prediction data for component for a specified data and data type. The {comp_type} can be either 'production' or 'consumption'. A valid {comp_id} can be found from the /{version}/{trial}/vpp/components service. A valid {date} can be found from the /{version}/{trial}/vpp/{comp_type}/{comp_id}/data service.Currently, 'Aachen' is the only trial offering this service. |
| Weather forecast This API is responsible for fetching information related to the weather be it in the past or the near future. |
Available forecast descriptors | Delivers the available forecast descriptors of the specified trial infrastructure. 'Terni' and 'Madrid' are the only trials offering this service. | Detailed weather report | A weather report for a specific area. | Detailed weather report regarding a single descriptor | A weather report (only one weather descriptor) for a specific area. 'Terni' is the only trial offering this service. | Detailed weather report | A weather report (only one weather descriptor and a limited number of measurements) for a specific area. 'Madrid' is the only trial offering this service. |