Nominations

Fetching Aggregated Nominations

To view your Aggregated Nominations as a Participant user using the getAggregatedNominations endpoint, it is required to supply the following parameters to the request. The endpoint specification does not outline these as it is for general use so please follow the below additional steps:

• specify a "Delivery Day" which fits your query in the deliveryDay query parameter
• always use the TIMESCALE option for the type query parameter
• always include the timescaleTypes query parameter, with at least one timescale
  • use the parameter 3 times for aggregated all 3 timescales
• always include the X-Participant-Ids header parameter, with your Participant ID as its single value

An example request by a Participant would look like this:

curl -X 'GET' \
  'https://<api_base_url>/v1/nominations/aggregated?deliveryDay=2022-01-04&type=TIMESCALE&timescaleTypes=LONG_TERM_NOMINATION&timescaleTypes=DAY_AHEAD_NOMINATION&timescaleTypes=INTRA_DAY_NOMINATION' \
  -H 'accept: application/json' \
  -H 'X-API-Key: <your_api_key>' \
  -H 'X-Participant-Ids: <your_participant_id>'

and result in the AggregatedNominations schema to be returned with a 200 OK response code

💡 Please do keep in mind that this will only return your Participant organisation's Aggregated Nominations. In case you need to see what is BritNed's overall Aggregated Netted Nominations, please use the getPublicAggregatedNominationsOverview endpoint.

Entering Nominations using the JSON API

Synchronising your system with Empire

To ensure that you submit a valid body, it is recommended to first GET the current nomination options for the desired delivery day, timescale and border direction. Use the getTimescaleNominations endpoint for this.

💡 It is always advised to first fetch the "current nominations" even if there has been none made, as Empire will take care of calculating the right MTUs to use, taking clock changes into consideration. First fetching the values and then mapping the mtu values into the response is the best way to avoid the MTU_LIST_MISALIGNED errors.

The endpoint returns a set of MTUs along with their status (being EDITABLE or LOCKED), your Transmission Rights for the provided timescale and any current nomination values in place.

Submit Nominations through the JSON API

The submitTimescaleNominations endpoint provides a straightforward way to submit your organisation's nominations via Empire's REST API.

The endpoint takes a deliveryDay, type (used for Timescale), borderDirection query parameters, the X-Participant-Id header, and a payload of MTUs along with their desired nomination values.

❗ Please note that with the JSON API Nomination you always have to send all nominations you wish to submit, change or keep for every EDITABLE MTUs at all times, in every payload. Submitting NULL nominations for the same delivery day, border direction and timescale will overwrite any previous nominations!

When submitting your new or edited nominations, ensure to:

• You can only submit values for EDITABLE MTUs only
• Always submit the nomination values in kW
• Submit no value for the MTU if the (LOCKED) MTU doesn't have a nomination value, or you wouldn't like to submit a nomination for it.

For example, if you'd like to submit 10MW nominations for MTUs 12:00-13:00 UTC and 14:00-15:00 UTC, use the following payload

{
  "mtus": [
    {
      "mtu": "2023-10-04T12:00:00.000Z",
      "value": 10000
    },
    {
      "mtu": "2023-10-04T13:00:00.000Z"
    },
    {
      "mtu": "2023-10-04T14:00:00.000Z",
      "value": 10000
    }
  ]
}

Please make sure to:

• Always include all MTUs of the Delivery Day in a sequence, i.e. don't leave gaps between subsequent MTUs
• Ensure you're using the correct delivery period and border direction to avoid errors related to "Locked MTUs"
• Always send all nominations you wish to submit, change or keep, in every payload. Submitting nominations for the same delivery day, border direction and timescale will overwrite any previous nominations!

Entering Nominations using XML file uploads

You can use XML files to enter or edit your nominations. The XML files should follow the attached nominations schema as Empire will validate the uploaded file against that.

The XML file can be uploaded to Empire via the UI, using the Manual File Upload feature, or via the API.

Uploading a Nominations XML via the API

To upload a nominations XML, first send a POST request to the uploadAttachment endpoint, with the XML in the file field of the body, as per the documentation. This will upload the XML file as an Attachment to Empire.

💡 Please bear in mind that no validation takes place at this point as Empire will not interpret the file, just store it. The file upload endpoint will return an id field in the response, please take a note of this.

Then, send a POST request to the uploadTimescaleNominations endpoint, with the attachmentId in the body being the id from the request above. This will apply and interpret the previously uploaded attachment as a nominations file - triggering all validations and checks. Should the request return an error, it means that no nominations have been entered and the errors should be fixed before they can be processed.

Example XML files can be found on BritNed's website, as well as examples to perform file uploads from Postman.

Common mistakes with XML nominations

The below problems are the most common pitfalls of XML nominations uploading.

MTU <timestamp> is not editable. The only accepted value is the one already in the system

You have included at least one MTU that is not in an editable status in Empire. An MTU is editable if you have Transmission Rights to nominate for it, and its nomination window hasn't been closed yet. If this error occurs, please double check the dates and times included in the XML as well as the direction of the intended nomination.

You can include non-editable (a.k.a LOCKED) MTUs in your nomination XML as long as their nomination values are exactly what Empire already has on record. The only exception from this is if you had no nomination for a now locked MTU and you wish to submit it in a subsequent nomination file. In this case, please ensure that you include 0 as the nomination value for the affected MTUs!

The number of points must be equal to the number of mtus in time interval

The number of <Point> tags, defining MTUs to nominate for, isn't consistent with the timeframe defined in the <timeInterval> and/or the <matching_Time_Period.timeInterval> tag. Please ensure that the start and end timestamps are in UTC and that the end time is not included as an additional MTU in the <Point> list.

For example:

<timeInterval>
        <start>2023-10-04T14:00Z</start>
        <end>2023-10-04T22:00Z</end>
</timeInterval>

must mean that exactly 8 <Point> tags are listed below it.

The uploaded file does not conform to any of the given schemas

There is most likely a syntactical or semantical issue with the XML file you submitted. Please check your XML's conformity to the above referred nominations schema. Pay special attention to ensuring that your organisation's EIC code is correct, as well as the timestamps and directions.