General interface specifications for the data interface

1 Communication
2 Endpoint
3 Parameters
4 Response Message
5 Data validity
6 Data authorization
7 Technical details
8 Generic usage pattern

Communication

The data interface is a REST based web service that utilises the HTTP protocol’s POST and GET methods.

The GET method is 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

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

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}

Parameters

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.

Response Message

Only public data (Organization details) or data to which the party has the right based on an agreement (sales/grid) or authorization is returned. When the user-provided parameters together with the data authorization 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 authorization

For all data requests, Datahub will check if the party has the proper data authorization for the data requested. The rules are defined per function. Access to data where the party does not have an active (confirmed) agreement or authorization is not allowed, unless explicitly indicated in the process.

A confirmed agreement or authorization for a market party can be one of the following agreement or authorization 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
DH-1000	Accounting point information	Get the details of the accounting point. `GetAccountingPointDataPost` or `GetAccountingPointData`
DH-1001	Contractual information (DSO or supplier)	Show list of agreements the customer has/has had for the party whose portal he/she is using. `GetContractDataPost` or `GetContractData`
DH-1002	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. `GetTimeSeriesDataPost` or `GetTimeSeriesData`
DH-1003	Authorization information (service provider or supplier)	Show list of authorizations the customer has/has had for the party whose portal he/she is using. `GetAuthorisationDataPost` or `GetAuthorisationData`
DH-1005	Customer information	After login get the customer information and the linked metadata of the customer agreements and accounting points. `GetCustomerDataPost` or `GetCustomerData`