General interface specifications for the data interface
Communication
The data interface is a REST based web service that utilises the HTTP protocol’s POST and GET methods.
The GET method will be removed in Datahub version 2.6.
The interface uses client certificates for authentication.
The following table lists the mandatory attributes needed to open a connection to the interface
Name | Type | Obligation | Value |
|---|---|---|---|
Connection: Client Certificate | Certificate | Mandatory | The certificate provided by the client |
Connection: Protocol | String | Mandatory | HTTPS (TLS 1.2 or TLS 1.3) |
Connection: Port | String | Mandatory | 443 |
Endpoint
Endpoint, POST method
The interface has only one endpoint that is called to invoke the desired function. The endpoint URL of the POST method has the following structure:
https://{hostname}/rest/FGR/{function}Endpoint, GET method
The interface has only one endpoint that is called to invoke the desired function. The endpoint URL of the GET method has the following structure:
https://{hostname}/rest/FGR/{function}?organisationUser={OrganisationUsername}&filter01={filter01}&filter02={filter02}&…Parameters
Parameters, POST method
Header parameters:
Name | Type | Obligation | Value |
HTTP: Method | String | Mandatory | POST |
HTTP: Accept | String | Mandatory | application/json |
Path parameters:
Name | Type | Obligation | Value |
{Function} | String | Mandatory | See DH-1000. |
Query string parameters:
The POST method does not use parameters in the URL.
Parameters, GET method
Header parameters:
Name | Type | Obligation | Value |
HTTP: Method | String | Mandatory | GET |
HTTP: Accept | String | Mandatory | application/json |
Path parameters:
Name | Type | Obligation | Value |
{Function} | String | Mandatory | See DH-1000. |
Query string parameters:
Name | Type | Obligation | Value |
{OrganisationUser} | String | Mandatory | Specific to each organisation. Defines that a B2B user created by Fingrid and registered in Datahub has specific user roles in B2B communication. |
{Filters} | {Varies} | {Varies} | functions can have multiple ampersand separated filters. For example: customerIdentification=1234&meteringPointEAN=12345&ViewDate=2019-10-14T21:00:00ZThe appropriate filter depends on the function. See DH-1000. Please use parameters with correct upper- and lower-case letters (meteringPointEAN vs. MeteringpointEAN). Using the wrong case will result in a HTTP 400 Bad Request error. |
Response Message
Only public data (Organisation details) or data to which the party has the right based on an agreement (sales/grid) or authorisation is returned. When the user-provided parameters together with the data authorisation filters do not result in response data, an empty JSON object response is returned instead of validation errors.
For empty attributes, Datahub will not send an empty element, instead, it will not send the element at all.
An example JSON response message from Datahub
{"GetAccountinPointDataResponse": {
"MeteringPoints": [{
"MeteringPointEAN": "640102010000532598",
"AccountingPointSubType": "AQ01"
},
{
"MeteringPointEAN": "640102010005902686",
"AccountingPointSubType ": "AQ02"
}]
}
}Data validity
All validations are done against the current status of the data based on the ViewDate. For functions without ViewDate as input field, the current datetime is used
Data authorisation
For all data requests, Datahub will check if the party has the proper data authorisation for the data requested. The rules are defined per function. Access to data where the party does not have an active (confirmed) agreement or authorisation is not allowed, unless explicitly indicated in the process.
A confirmed agreement or authorisation for a market party can be one of the following agreement or authorisation types:
Koodi | Kuvaus |
AP01 | Energy reporting |
AP02 | Invitation to tender |
AP03 | Competitive bidding for an agreement as a service |
AP04 | Invitation to tender (no access to metering data) |
AP05 | Competitive bidding for an agreement as a service (no access to metering data |
AP07 | Energy reporting and agreement information |
11 | Grid agreement |
12 | Sales agreement |
Technical details
The data interface does not support wildcard searches.
The data interface is not language aware. It will return the information as it is stored in Datahub. For example, domain codes are not translated but communicated as codes as in the B2B interface.
For numbers and dates, the default XML/JSON format is used.
All times in the data interface are in UTC. For example, “2019-05-14T12:30:00Z” is local Finnish time “2019-05-14T15:30:00”.
IDs based on the SI system are used as unit codes for values, e.g., kW, MW, kWh, MWh, kvar, Mvar, kvarh, Mvarh.
UUIDs (Universally Unique Identifiers) are used as message IDs.
Values for filters can be entered into the text-based data fields in upper and lower case. The retrieval does not differentiate between upper- and lower-case characters
Generic usage pattern
Accounting point identification or customer identification can be used to retrieve data.
Process | Description | Note |
Accounting point information | Get the details of the accounting point. GetAccountingPointDataPostor GetAccountingPointData | |
Contractual information (DSO or supplier)
| Show list of agreements the customer has/has had for the party whose portal he/she is using. GetContractDataPostor GetContractData | |
Time series data | Show the time series data for the customer. Preferably the party caches the raw hourly/15-minute values to limit the interaction with Datahub and then forwards the aggregated data to the client. GetTimeSeriesDataPostor GetTimeSeriesData | |
Authorization information (service provider or supplier) | Show list of authorizations the customer has/has had for the party whose portal he/she is using. GetAuthorisationDataPostor GetAuthorisationData | |
Customer information | After login get the customer information and the linked metadata of the customer agreements and accounting points. GetCustomerDataPostor GetCustomerData |