Skip to main content
The /calculate/ endpoint processes consumption data to provide detailed cost calculations based on specified tariffs and time periods. This endpoint is ideal for applications that need to determine costs for actual or estimated electricity usage, such as EV charging cost calculations or energy usage analysis.

​
Endpoint Overview

POST /calculate/
This endpoint accepts consumption data with timestamps and usage amounts, calculates costs using the specified tariffs, and returns detailed or summarized cost information.

​
Location Specification

The Calculate endpoint follows the same location specification pattern as other Prezio endpoints:
  1. You must provide either an address or the latitude/longitude coordinates, but not both.
  2. The provided location is used to determine which tariffs are applicable in that geographic area.
  3. For improved accuracy, prefer using an address with postal code when possible.

​
Time Window Constraint

The time window between the earliest and latest intervals in the kwh array must not exceed 48 hours. Requests violating this constraint will return an error.

​
Price Precision

All price fields in the response use 6 decimal places (e.g., "0.123456"), providing high precision for financial calculations and energy cost analysis.

​
Example Requests

curl -X POST "https://api.prezio.dev/v1/calculate/" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "country": "DK",
    "tariff_id": ["tar_123", "tar_456"],
    "address": "Rådhuspladsen 1, Copenhagen",
    "kwh": [
      {"interval_start": "2023-10-15T14:00:00Z", "amount": "1.5"},
      {"interval_start": "2023-10-15T15:00:00Z", "amount": "2.1"}
    ],
    "detail": "full",
    "interval_minutes": 60
  }'

​
Response Structure

The response returns both total cost and interval-by-interval breakdown of electricity costs: 
{
  "context": {
    "currency": "DKK",
    "unit": "per_kwh",
    "interval_minutes": 60,
    "location": {
      "input_address": "Rådhuspladsen 1, Copenhagen",
      "coordinates": {
        "latitude": 55.6761,
        "longitude": 12.5683,
        "confidence": 0.9
      }
    }
  },
  "tariff_elements": [
    {
      "element_id": "com_123",
      "element_name": "Grid Usage Fee",
      "tariff_id": "tar_123",
      "tariff_name": "Copenhagen DSO Standard",
      "organization_id": "org_456",
      "organization_name": "Copenhagen Energy Grid",
      "organization_type": "DSO"
    },
    {
      "element_id": "com_789",
      "element_name": "Energy Cost",
      "tariff_id": "tar_456",
      "tariff_name": "Variable Spot Price",
      "organization_id": "org_101",
      "organization_name": "Nordic Power Retail",
      "organization_type": "RET"
    }
  ],
  "total_price": "0.567150",
  "results": [
    {
      "interval_start": "2023-10-15T14:00:00Z",
      "elements": [
        {
          "id": "com_123",
          "unit_price": "0.052100",
          "calculated_price": "0.078150"
        },
        {
          "id": "com_789",
          "unit_price": "0.104500",
          "calculated_price": "0.156750"
        }
      ],
      "interval_price": "0.234900"
    },
    {
      "interval_start": "2023-10-15T15:00:00Z",
      "elements": [
        {
          "id": "com_123",
          "unit_price": "0.052100",
          "calculated_price": "0.109410"
        },
        {
          "id": "com_789",
          "unit_price": "0.106100",
          "calculated_price": "0.222840"
        }
      ],
      "interval_price": "0.332250"
    }
  ]
}

​
Detail Levels

Full Detail

Returns all price components individually with metadata about each component, ideal for detailed cost analysis.

Semi Detail

Aggregates costs by organization type (DSO, Retailer, etc.), providing a simplified but still informative breakdown.

Summarized

Returns only the total cost for the entire consumption period, useful when only the bottom line matters.
If you only need total costs, use detail=summarized to minimize response payload size and get a faster resonse.

​
VAT Handling

Control how Value Added Tax is represented in the response:

VAT Excluded

All prices exclude VAT (default behavior).
Each price component includes its applicable VAT.
VAT is shown as separate component(s).

​
Best Practices

Provide consumption data aligned with the specified interval_minutes. For example, if interval_minutes is 60, ensure timestamps are on the hour (e.g., 14:00:00). Misaligned timestamps will result in errors.
Ensure the total time window for consumption data does not exceed 48 hours between the earliest and latest timestamps. Exceeding this limit will trigger a validation error.

​
Common Use Cases

EV Charging Cost Calculation

Calculate the exact cost of charging sessions for electric vehicles based on actual consumption data.

Home Energy Billing

Determine costs for home energy usage over specific periods for billing or reimbursement purposes.

Energy Usage Analysis

Analyze cost breakdowns by component to understand the impact of different tariff elements on total expenses.

Fleet Management

Compute aggregated costs for EV fleets, supporting expense tracking and optimization.

​
Error Handling

The Calculate endpoint may return specific errors for invalid inputs:
  • 400 Bad Request: Invalid or misaligned timestamps, missing required fields, or time window exceeding 48 hours.
  • 401 Unauthorized: Missing or invalid API key.
  • 404 Not Found: Specified tariffs are not applicable for the given location.
  • 422 Validation Error: Consumption data format issues or unsupported interval_minutes values.
Ensure your application handles these errors gracefully and provides meaningful feedback to users.