Calculate savings

curl --request POST \
  --url https://api.nomos.energy/plans/{id}/savings \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "zip_code": "10115",
  "household": {
    "usage": 2500
  },
  "assets": {}
}
'

import requests

url = "https://api.nomos.energy/plans/{id}/savings"

payload = {
    "zip_code": "10115",
    "household": { "usage": 2500 },
    "assets": {}
}
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({zip_code: '10115', household: {usage: 2500}, assets: {}})
};

fetch('https://api.nomos.energy/plans/{id}/savings', 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/plans/{id}/savings",
  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([
    'zip_code' => '10115',
    'household' => [
        'usage' => 2500
    ],
    'assets' => [
        
    ]
  ]),
  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/plans/{id}/savings"

	payload := strings.NewReader("{\n  \"zip_code\": \"10115\",\n  \"household\": {\n    \"usage\": 2500\n  },\n  \"assets\": {}\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/plans/{id}/savings")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"zip_code\": \"10115\",\n  \"household\": {\n    \"usage\": 2500\n  },\n  \"assets\": {}\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.nomos.energy/plans/{id}/savings")

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  \"zip_code\": \"10115\",\n  \"household\": {\n    \"usage\": 2500\n  },\n  \"assets\": {}\n}"

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

{
  "object": "savings",
  "savings": 812.4,
  "resolution": "year",
  "cost": {
    "before": 2622.6,
    "after": 1810.2
  },
  "usage": {
    "consumption": 3907
  },
  "optimization_rate": 0.18,
  "grid_fee_reductions": {
    "14a_module_1": true,
    "14a_module_3": false
  },
  "components": [
    {
      "group": "tariff",
      "savings": 520.5,
      "subcomponents": [
        {
          "subgroup": "base",
          "name": "Grundgebühr",
          "savings": 18
        },
        {
          "subgroup": "variable",
          "name": "Arbeitspreis",
          "savings": 502.5
        }
      ]
    },
    {
      "group": "grid_fee_reductions",
      "savings": 148.7,
      "subcomponents": [
        {
          "subgroup": "14a_module_1",
          "name": "Pauschale Netzentgeltreduktion (§14a EnWG Modul 1)",
          "savings": 148.7
        },
        {
          "subgroup": "14a_module_3",
          "name": "Zeitvariable Netzentgelte (§14a EnWG Modul 3)",
          "savings": 0
        }
      ]
    },
    {
      "group": "optimization",
      "savings": 143.2,
      "subcomponents": [
        {
          "subgroup": "variable",
          "name": "Optimierung",
          "savings": 143.2
        }
      ]
    }
  ]
}

{
  "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",
  "errors": [
    {
      "code": "invalid_type",
      "field": "favoriteNumbers.1",
      "message": "Invalid input: expected string, received number"
    }
  ]
}

{
  "code": "UNAUTHORIZED",
  "message": "Invalid or malformed token",
  "requestId": "37a04f8f-e791-491c-81e1-86cd304649bb",
  "docs": "https://docs.nomos.energy/api-references/errors/UNAUTHORIZED",
  "errors": [
    {
      "code": "invalid_type",
      "field": "favoriteNumbers.1",
      "message": "Invalid input: expected string, received number"
    }
  ]
}

{
  "code": "PAYMENT_REQUIRED",
  "message": "Payment required",
  "requestId": "37a04f8f-e791-491c-81e1-86cd304649bb",
  "docs": "https://docs.nomos.energy/api-references/errors/PAYMENT_REQUIRED",
  "errors": [
    {
      "code": "invalid_type",
      "field": "favoriteNumbers.1",
      "message": "Invalid input: expected string, received number"
    }
  ]
}

{
  "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",
  "errors": [
    {
      "code": "invalid_type",
      "field": "favoriteNumbers.1",
      "message": "Invalid input: expected string, received number"
    }
  ]
}

{
  "code": "NOT_FOUND",
  "message": "Resource not found",
  "requestId": "37a04f8f-e791-491c-81e1-86cd304649bb",
  "docs": "https://docs.nomos.energy/api-references/errors/NOT_FOUND",
  "errors": [
    {
      "code": "invalid_type",
      "field": "favoriteNumbers.1",
      "message": "Invalid input: expected string, received number"
    }
  ]
}

{
  "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",
  "errors": [
    {
      "code": "invalid_type",
      "field": "favoriteNumbers.1",
      "message": "Invalid input: expected string, received number"
    }
  ]
}

{
  "code": "CONFLICT",
  "message": "Resource already exists",
  "requestId": "37a04f8f-e791-491c-81e1-86cd304649bb",
  "docs": "https://docs.nomos.energy/api-references/errors/CONFLICT",
  "errors": [
    {
      "code": "invalid_type",
      "field": "favoriteNumbers.1",
      "message": "Invalid input: expected string, received number"
    }
  ]
}

{
  "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",
  "errors": [
    {
      "code": "invalid_type",
      "field": "favoriteNumbers.1",
      "message": "Invalid input: expected string, received number"
    }
  ]
}

{
  "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",
  "errors": [
    {
      "code": "invalid_type",
      "field": "favoriteNumbers.1",
      "message": "Invalid input: expected string, received number"
    }
  ]
}

{
  "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",
  "errors": [
    {
      "code": "invalid_type",
      "field": "favoriteNumbers.1",
      "message": "Invalid input: expected string, received number"
    }
  ]
}

Plans

Calculate savings

Estimate what a household saves per year on this plan against the tariff it pays today, or against the market benchmark when none is given. All amounts are EUR per year, gross.

The household is described by its base consumption plus one object per asset it owns. Presence is the signal: send assets.ev and the household has an electric vehicle. The optimization rate and the §14a EnWG eligibility follow from that mix and from what the plan sells; they cannot be requested, because a household that qualifies is quoted as qualifying and whether it later declines the registration is a signup answer rather than a property of the setup.

The saving is the difference between two quotes on this plan with the same usage, one at market prices without §14a EnWG and one at the derived rate with the eligible modules, so components is that difference line by line and sums to savings. Nothing is read or written; the calculation is performed and discarded.

The fields the response and Calculate a quote share are named the same: post usage.consumption as usage, plus optimization_rate and grid_fee_reductions, to price the same household there and reconcile every figure. Feed-in plans are rejected with 400 BAD_REQUEST.

POST

plans

{id}

savings

Calculate savings

curl --request POST \
  --url https://api.nomos.energy/plans/{id}/savings \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "zip_code": "10115",
  "household": {
    "usage": 2500
  },
  "assets": {}
}
'

import requests

url = "https://api.nomos.energy/plans/{id}/savings"

payload = {
    "zip_code": "10115",
    "household": { "usage": 2500 },
    "assets": {}
}
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({zip_code: '10115', household: {usage: 2500}, assets: {}})
};

fetch('https://api.nomos.energy/plans/{id}/savings', 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/plans/{id}/savings",
  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([
    'zip_code' => '10115',
    'household' => [
        'usage' => 2500
    ],
    'assets' => [
        
    ]
  ]),
  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/plans/{id}/savings"

	payload := strings.NewReader("{\n  \"zip_code\": \"10115\",\n  \"household\": {\n    \"usage\": 2500\n  },\n  \"assets\": {}\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/plans/{id}/savings")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"zip_code\": \"10115\",\n  \"household\": {\n    \"usage\": 2500\n  },\n  \"assets\": {}\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.nomos.energy/plans/{id}/savings")

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  \"zip_code\": \"10115\",\n  \"household\": {\n    \"usage\": 2500\n  },\n  \"assets\": {}\n}"

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

{
  "object": "savings",
  "savings": 812.4,
  "resolution": "year",
  "cost": {
    "before": 2622.6,
    "after": 1810.2
  },
  "usage": {
    "consumption": 3907
  },
  "optimization_rate": 0.18,
  "grid_fee_reductions": {
    "14a_module_1": true,
    "14a_module_3": false
  },
  "components": [
    {
      "group": "tariff",
      "savings": 520.5,
      "subcomponents": [
        {
          "subgroup": "base",
          "name": "Grundgebühr",
          "savings": 18
        },
        {
          "subgroup": "variable",
          "name": "Arbeitspreis",
          "savings": 502.5
        }
      ]
    },
    {
      "group": "grid_fee_reductions",
      "savings": 148.7,
      "subcomponents": [
        {
          "subgroup": "14a_module_1",
          "name": "Pauschale Netzentgeltreduktion (§14a EnWG Modul 1)",
          "savings": 148.7
        },
        {
          "subgroup": "14a_module_3",
          "name": "Zeitvariable Netzentgelte (§14a EnWG Modul 3)",
          "savings": 0
        }
      ]
    },
    {
      "group": "optimization",
      "savings": 143.2,
      "subcomponents": [
        {
          "subgroup": "variable",
          "name": "Optimierung",
          "savings": 143.2
        }
      ]
    }
  ]
}

{
  "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",
  "errors": [
    {
      "code": "invalid_type",
      "field": "favoriteNumbers.1",
      "message": "Invalid input: expected string, received number"
    }
  ]
}

{
  "code": "UNAUTHORIZED",
  "message": "Invalid or malformed token",
  "requestId": "37a04f8f-e791-491c-81e1-86cd304649bb",
  "docs": "https://docs.nomos.energy/api-references/errors/UNAUTHORIZED",
  "errors": [
    {
      "code": "invalid_type",
      "field": "favoriteNumbers.1",
      "message": "Invalid input: expected string, received number"
    }
  ]
}

{
  "code": "PAYMENT_REQUIRED",
  "message": "Payment required",
  "requestId": "37a04f8f-e791-491c-81e1-86cd304649bb",
  "docs": "https://docs.nomos.energy/api-references/errors/PAYMENT_REQUIRED",
  "errors": [
    {
      "code": "invalid_type",
      "field": "favoriteNumbers.1",
      "message": "Invalid input: expected string, received number"
    }
  ]
}

{
  "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",
  "errors": [
    {
      "code": "invalid_type",
      "field": "favoriteNumbers.1",
      "message": "Invalid input: expected string, received number"
    }
  ]
}

{
  "code": "NOT_FOUND",
  "message": "Resource not found",
  "requestId": "37a04f8f-e791-491c-81e1-86cd304649bb",
  "docs": "https://docs.nomos.energy/api-references/errors/NOT_FOUND",
  "errors": [
    {
      "code": "invalid_type",
      "field": "favoriteNumbers.1",
      "message": "Invalid input: expected string, received number"
    }
  ]
}

{
  "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",
  "errors": [
    {
      "code": "invalid_type",
      "field": "favoriteNumbers.1",
      "message": "Invalid input: expected string, received number"
    }
  ]
}

{
  "code": "CONFLICT",
  "message": "Resource already exists",
  "requestId": "37a04f8f-e791-491c-81e1-86cd304649bb",
  "docs": "https://docs.nomos.energy/api-references/errors/CONFLICT",
  "errors": [
    {
      "code": "invalid_type",
      "field": "favoriteNumbers.1",
      "message": "Invalid input: expected string, received number"
    }
  ]
}

{
  "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",
  "errors": [
    {
      "code": "invalid_type",
      "field": "favoriteNumbers.1",
      "message": "Invalid input: expected string, received number"
    }
  ]
}

{
  "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",
  "errors": [
    {
      "code": "invalid_type",
      "field": "favoriteNumbers.1",
      "message": "Invalid input: expected string, received number"
    }
  ]
}

{
  "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",
  "errors": [
    {
      "code": "invalid_type",
      "field": "favoriteNumbers.1",
      "message": "Invalid input: expected string, received number"
    }
  ]
}

Authorizations

Authorization

string

header

required

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

Path Parameters

string

required

Example:

"pln_1"

Body

application/json

The household to calculate the savings for

zip_code

string

required

ZIP code for the delivery address

Example:

"10115"

household

object

required

The household itself, before any of its assets.

Show child attributes

assets

object

What the household owns. Presence is the signal: send the object and the household has that asset, leave it out and it has none. The optimization rate and the §14a EnWG eligibility on the response are derived from this mix, they cannot be requested.

Show child attributes

current_tariff

object

What the household pays today, as their current bill prints it. Present compares the plan against it; absent compares against the market benchmark.

Show child attributes

Response

The savings breakdown

object

enum<string>

required

Available options:

savings

savings

number

required

What the household saves on this plan, EUR gross, over the period resolution names. The sum of every component, and exactly cost.before - cost.after.

Example:

812.4

resolution

enum<string>

required

The period every amount covers. Savings are always stated per year: the §14a EnWG modules and the load-shifting credit are seasonal, so a twelfth of a year is not a twelfth of the saving.

Available options:

year

Example:

"year"

cost

object

required

The two bills the saving is the difference between, EUR gross per year, all-in: supplier base fee, grid and metering fees, levies, taxes and energy. Neither includes the imputed cost of self-generated solar or feed-in revenue, so this is what gets invoiced. before is the market benchmark, or the current_tariff that was sent.

Show child attributes

usage

object

required

Show child attributes

optimization_rate

number

required

The share of the day-ahead price this asset mix is expected to shift, 0 to 1. A property of the mix rather than of the total, so it holds when the consumption is edited.

Example:

0.18

grid_fee_reductions

object

required

The §14a EnWG grid fee reductions this household is quoted with. Derived from its assets, from what the plan sells, and from what the grid operator publishes; they cannot be requested.

Show child attributes

components

object[]

required

Where the saving comes from, in the order it stacks up: tariff compares the plan against the comparison tariff before §14a EnWG and before optimization, grid_fee_reductions is what the modules deduct on top of that, and optimization is what load shifting adds again. Each line compares against what the ones before it left off, so the amounts are strictly additive and sum to savings.

Show child attributes

Example:

[
  {
    "group": "tariff",
    "savings": 520.5,
    "subcomponents": [
      {
        "subgroup": "base",
        "name": "Grundgebühr",
        "savings": 18
      },
      {
        "subgroup": "variable",
        "name": "Arbeitspreis",
        "savings": 502.5
      }
    ]
  },
  {
    "group": "grid_fee_reductions",
    "savings": 148.7,
    "subcomponents": [
      {
        "subgroup": "14a_module_1",
        "name": "Pauschale Netzentgeltreduktion (§14a EnWG Modul 1)",
        "savings": 148.7
      },
      {
        "subgroup": "14a_module_3",
        "name": "Zeitvariable Netzentgelte (§14a EnWG Modul 3)",
        "savings": 0
      }
    ]
  },
  {
    "group": "optimization",
    "savings": 143.2,
    "subcomponents": [
      {
        "subgroup": "variable",
        "name": "Optimierung",
        "savings": 143.2
      }
    ]
  }
]