Create a load forecast

curl --request POST \
  --url https://api.nomos.energy/load-forecasts \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "scope": "subscription",
  "subscription": "sub_123456789",
  "resolution": "15min",
  "unit": "KW",
  "data": [
    {
      "start": "2025-03-31T22:00:00.000Z",
      "value": 0.2
    },
    {
      "start": "2025-03-31T22:15:00.000Z",
      "value": 0.22
    }
  ]
}
'

import requests

url = "https://api.nomos.energy/load-forecasts"

payload = {
    "scope": "subscription",
    "subscription": "sub_123456789",
    "resolution": "15min",
    "unit": "KW",
    "data": [
        {
            "start": "2025-03-31T22:00:00.000Z",
            "value": 0.2
        },
        {
            "start": "2025-03-31T22:15:00.000Z",
            "value": 0.22
        }
    ]
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    scope: 'subscription',
    subscription: 'sub_123456789',
    resolution: '15min',
    unit: 'KW',
    data: [
      {start: '2025-03-31T22:00:00.000Z', value: 0.2},
      {start: '2025-03-31T22:15:00.000Z', value: 0.22}
    ]
  })
};

fetch('https://api.nomos.energy/load-forecasts', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.nomos.energy/load-forecasts",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'scope' => 'subscription',
    'subscription' => 'sub_123456789',
    'resolution' => '15min',
    'unit' => 'KW',
    'data' => [
        [
                'start' => '2025-03-31T22:00:00.000Z',
                'value' => 0.2
        ],
        [
                'start' => '2025-03-31T22:15:00.000Z',
                'value' => 0.22
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.nomos.energy/load-forecasts"

	payload := strings.NewReader("{\n  \"scope\": \"subscription\",\n  \"subscription\": \"sub_123456789\",\n  \"resolution\": \"15min\",\n  \"unit\": \"KW\",\n  \"data\": [\n    {\n      \"start\": \"2025-03-31T22:00:00.000Z\",\n      \"value\": 0.2\n    },\n    {\n      \"start\": \"2025-03-31T22:15:00.000Z\",\n      \"value\": 0.22\n    }\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.nomos.energy/load-forecasts")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"scope\": \"subscription\",\n  \"subscription\": \"sub_123456789\",\n  \"resolution\": \"15min\",\n  \"unit\": \"KW\",\n  \"data\": [\n    {\n      \"start\": \"2025-03-31T22:00:00.000Z\",\n      \"value\": 0.2\n    },\n    {\n      \"start\": \"2025-03-31T22:15:00.000Z\",\n      \"value\": 0.22\n    }\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.nomos.energy/load-forecasts")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"scope\": \"subscription\",\n  \"subscription\": \"sub_123456789\",\n  \"resolution\": \"15min\",\n  \"unit\": \"KW\",\n  \"data\": [\n    {\n      \"start\": \"2025-03-31T22:00:00.000Z\",\n      \"value\": 0.2\n    },\n    {\n      \"start\": \"2025-03-31T22:15:00.000Z\",\n      \"value\": 0.22\n    }\n  ]\n}"

response = http.request(request)
puts response.read_body

{
  "scope": "subscription",
  "subscription": "<string>",
  "start": "2023-11-07T05:31:56Z",
  "end": "2023-11-07T05:31:56Z",
  "total": 123
}

{
  "code": "BAD_REQUEST",
  "message": "invalid_type in 'end': Required",
  "requestId": "37a04f8f-e791-491c-81e1-86cd304649bb",
  "docs": "https://docs.nomos.energy/api-references/errors/BAD_REQUEST"
}

{
  "code": "UNAUTHORIZED",
  "message": "Invalid or malformed token",
  "requestId": "37a04f8f-e791-491c-81e1-86cd304649bb",
  "docs": "https://docs.nomos.energy/api-references/errors/UNAUTHORIZED"
}

{
  "code": "PAYMENT_REQUIRED",
  "message": "Payment required",
  "requestId": "37a04f8f-e791-491c-81e1-86cd304649bb",
  "docs": "https://docs.nomos.energy/api-references/errors/PAYMENT_REQUIRED"
}

{
  "code": "FORBIDDEN",
  "message": "You are not allowed to access this resource",
  "requestId": "37a04f8f-e791-491c-81e1-86cd304649bb",
  "docs": "https://docs.nomos.energy/api-references/errors/FORBIDDEN"
}

{
  "code": "NOT_FOUND",
  "message": "Resource not found",
  "requestId": "37a04f8f-e791-491c-81e1-86cd304649bb",
  "docs": "https://docs.nomos.energy/api-references/errors/NOT_FOUND"
}

{
  "code": "METHOD_NOT_ALLOWED",
  "message": "Method not allowed",
  "requestId": "37a04f8f-e791-491c-81e1-86cd304649bb",
  "docs": "https://docs.nomos.energy/api-references/errors/METHOD_NOT_ALLOWED"
}

{
  "code": "CONFLICT",
  "message": "Resource already exists",
  "requestId": "37a04f8f-e791-491c-81e1-86cd304649bb",
  "docs": "https://docs.nomos.energy/api-references/errors/CONFLICT"
}

{
  "code": "UNPROCESSABLE_ENTITY",
  "message": "invalid_enum_value in 'status': Invalid enum value. Expected 'pending' | 'active' | 'ended'",
  "requestId": "37a04f8f-e791-491c-81e1-86cd304649bb",
  "docs": "https://docs.nomos.energy/api-references/errors/UNPROCESSABLE_ENTITY"
}

{
  "code": "TOO_MANY_REQUESTS",
  "message": "Wait 30 seconds before retrying.",
  "requestId": "37a04f8f-e791-491c-81e1-86cd304649bb",
  "docs": "https://docs.nomos.energy/api-references/errors/TOO_MANY_REQUESTS"
}

{
  "code": "INTERNAL_SERVER_ERROR",
  "message": "Internal Server Error",
  "requestId": "37a04f8f-e791-491c-81e1-86cd304649bb",
  "docs": "https://docs.nomos.energy/api-references/errors/INTERNAL_SERVER_ERROR"
}

Usage

Create a load forecast

This endpoint is used to transmit a load forecast for a subscription. A load forecast is a power curve: each data point is the average power draw in kilowatts (kW) during its 15-minute interval, not the energy consumed in kWh. Values must be submitted by 9:00 a.m. local time on the previous day to be considered in the day-ahead auction, and at least 15 minutes before delivery to be included in continuous intraday trading. Data points must be strictly consecutive and can only be provided for full days at a time (local time of the subscription).

POST

load-forecasts

curl --request POST \
  --url https://api.nomos.energy/load-forecasts \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "scope": "subscription",
  "subscription": "sub_123456789",
  "resolution": "15min",
  "unit": "KW",
  "data": [
    {
      "start": "2025-03-31T22:00:00.000Z",
      "value": 0.2
    },
    {
      "start": "2025-03-31T22:15:00.000Z",
      "value": 0.22
    }
  ]
}
'

import requests

url = "https://api.nomos.energy/load-forecasts"

payload = {
    "scope": "subscription",
    "subscription": "sub_123456789",
    "resolution": "15min",
    "unit": "KW",
    "data": [
        {
            "start": "2025-03-31T22:00:00.000Z",
            "value": 0.2
        },
        {
            "start": "2025-03-31T22:15:00.000Z",
            "value": 0.22
        }
    ]
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    scope: 'subscription',
    subscription: 'sub_123456789',
    resolution: '15min',
    unit: 'KW',
    data: [
      {start: '2025-03-31T22:00:00.000Z', value: 0.2},
      {start: '2025-03-31T22:15:00.000Z', value: 0.22}
    ]
  })
};

fetch('https://api.nomos.energy/load-forecasts', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.nomos.energy/load-forecasts",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'scope' => 'subscription',
    'subscription' => 'sub_123456789',
    'resolution' => '15min',
    'unit' => 'KW',
    'data' => [
        [
                'start' => '2025-03-31T22:00:00.000Z',
                'value' => 0.2
        ],
        [
                'start' => '2025-03-31T22:15:00.000Z',
                'value' => 0.22
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.nomos.energy/load-forecasts"

	payload := strings.NewReader("{\n  \"scope\": \"subscription\",\n  \"subscription\": \"sub_123456789\",\n  \"resolution\": \"15min\",\n  \"unit\": \"KW\",\n  \"data\": [\n    {\n      \"start\": \"2025-03-31T22:00:00.000Z\",\n      \"value\": 0.2\n    },\n    {\n      \"start\": \"2025-03-31T22:15:00.000Z\",\n      \"value\": 0.22\n    }\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.nomos.energy/load-forecasts")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"scope\": \"subscription\",\n  \"subscription\": \"sub_123456789\",\n  \"resolution\": \"15min\",\n  \"unit\": \"KW\",\n  \"data\": [\n    {\n      \"start\": \"2025-03-31T22:00:00.000Z\",\n      \"value\": 0.2\n    },\n    {\n      \"start\": \"2025-03-31T22:15:00.000Z\",\n      \"value\": 0.22\n    }\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.nomos.energy/load-forecasts")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"scope\": \"subscription\",\n  \"subscription\": \"sub_123456789\",\n  \"resolution\": \"15min\",\n  \"unit\": \"KW\",\n  \"data\": [\n    {\n      \"start\": \"2025-03-31T22:00:00.000Z\",\n      \"value\": 0.2\n    },\n    {\n      \"start\": \"2025-03-31T22:15:00.000Z\",\n      \"value\": 0.22\n    }\n  ]\n}"

response = http.request(request)
puts response.read_body

{
  "scope": "subscription",
  "subscription": "<string>",
  "start": "2023-11-07T05:31:56Z",
  "end": "2023-11-07T05:31:56Z",
  "total": 123
}

{
  "code": "BAD_REQUEST",
  "message": "invalid_type in 'end': Required",
  "requestId": "37a04f8f-e791-491c-81e1-86cd304649bb",
  "docs": "https://docs.nomos.energy/api-references/errors/BAD_REQUEST"
}

{
  "code": "UNAUTHORIZED",
  "message": "Invalid or malformed token",
  "requestId": "37a04f8f-e791-491c-81e1-86cd304649bb",
  "docs": "https://docs.nomos.energy/api-references/errors/UNAUTHORIZED"
}

{
  "code": "PAYMENT_REQUIRED",
  "message": "Payment required",
  "requestId": "37a04f8f-e791-491c-81e1-86cd304649bb",
  "docs": "https://docs.nomos.energy/api-references/errors/PAYMENT_REQUIRED"
}

{
  "code": "FORBIDDEN",
  "message": "You are not allowed to access this resource",
  "requestId": "37a04f8f-e791-491c-81e1-86cd304649bb",
  "docs": "https://docs.nomos.energy/api-references/errors/FORBIDDEN"
}

{
  "code": "NOT_FOUND",
  "message": "Resource not found",
  "requestId": "37a04f8f-e791-491c-81e1-86cd304649bb",
  "docs": "https://docs.nomos.energy/api-references/errors/NOT_FOUND"
}

{
  "code": "METHOD_NOT_ALLOWED",
  "message": "Method not allowed",
  "requestId": "37a04f8f-e791-491c-81e1-86cd304649bb",
  "docs": "https://docs.nomos.energy/api-references/errors/METHOD_NOT_ALLOWED"
}

{
  "code": "CONFLICT",
  "message": "Resource already exists",
  "requestId": "37a04f8f-e791-491c-81e1-86cd304649bb",
  "docs": "https://docs.nomos.energy/api-references/errors/CONFLICT"
}

{
  "code": "UNPROCESSABLE_ENTITY",
  "message": "invalid_enum_value in 'status': Invalid enum value. Expected 'pending' | 'active' | 'ended'",
  "requestId": "37a04f8f-e791-491c-81e1-86cd304649bb",
  "docs": "https://docs.nomos.energy/api-references/errors/UNPROCESSABLE_ENTITY"
}

{
  "code": "TOO_MANY_REQUESTS",
  "message": "Wait 30 seconds before retrying.",
  "requestId": "37a04f8f-e791-491c-81e1-86cd304649bb",
  "docs": "https://docs.nomos.energy/api-references/errors/TOO_MANY_REQUESTS"
}

{
  "code": "INTERNAL_SERVER_ERROR",
  "message": "Internal Server Error",
  "requestId": "37a04f8f-e791-491c-81e1-86cd304649bb",
  "docs": "https://docs.nomos.energy/api-references/errors/INTERNAL_SERVER_ERROR"
}

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

Load forecast input

scope

enum<string>

required

Reference point for the load forecast

Available options:

subscription

Example:

"subscription"

subscription

string

required

Required subscription ID when scope is 'subscription'

Example:

"sub_123456789"

resolution

enum<string>

required

Time resolution of the load forecast data points

Available options:

15min

Example:

"15min"

unit

enum<string>

required

Unit of measurement for the forecast values. Load forecasts are power curves: each data point is the average power draw in kilowatts (kW) during its 15-minute interval, not the energy consumed. The energy per interval in kWh equals the value divided by 4.

Available options:

KW

Example:

"KW"

data

object[]

required

Array of load forecast data points. Must be strictly consecutive with exactly 15-minute intervals and without overlaps or gaps and can only contain one data point per 15-minute interval.

Show child attributes

Example:

[
  {
    "start": "2025-03-31T22:00:00.000Z",
    "value": 0.2
  },
  {
    "start": "2025-03-31T22:15:00.000Z",
    "value": 0.22
  }
]

Response

Positive response

scope

enum<string>

required

Reference point of the stored load forecast

Available options:

subscription

subscription

string

required

ID of the subscription the forecast was stored for

start

string<date-time>

required

Start of the first forecast interval (UTC)

end

string<date-time>

required

End of the last forecast interval (UTC)

total

number

required

Sum of the submitted power values in kW across all 15-minute intervals. This is a checksum for the submission, not an energy amount. To convert to total energy in kWh, divide by 4.