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.

​
Data Flow Diagram

​
Key Parameters

​
country
string
required

Country code (e.g., DK, SE) for the location.

​
tariff_id
array
required

Array of tariff IDs to apply for cost calculations. Each tariff ID must include the tar_ prefix (e.g., tar_123).

​
kwh_consumed
array
required

Array of consumption entries, each with a timestamp and consumed amount:

{
  "datetime": "2023-10-15T14:00:00Z",
  "kwh_consumed": "1.25"
}
​
address
string

Location address to determine applicable pricing. Required if coordinates are not provided.

​
latitude
number

Latitude coordinate of the location. Required if address is not provided.

​
longitude
number

Longitude coordinate of the location. Required if address is not provided.

​
time_span
string
default:"60min"

Time resolution for calculations. Options: 60min, 30min, or 15min. All consumption timestamps must align with the chosen interval.

​
component_types
array
default:"['PER_KWH']"

Types of price components to include in the calculation (e.g., PER_KWH, FIXED, TAX).

​
detail
string
default:"full"

Level of detail in the response:

  • summarized: Only total cost
  • semi: Costs aggregated by organization type
  • full: Complete breakdown of all price components
​
vat
string
default:"excluded"

How to handle VAT in the response:

  • excluded: Prices exclude VAT
  • included: VAT included in each price component
  • separated: VAT shown as separate components

​
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.
  4. The endpoint will return a confidence score (1-10) for the location resolution.

​
Time Window Constraint

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

​
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_consumed": [
      {"datetime": "2023-10-15T14:00:00Z", "kwh_consumed": "1.5"},
      {"datetime": "2023-10-15T15:00:00Z", "kwh_consumed": "2.1"}
    ],
    "detail": "full",
    "time_span": "60min"
  }'

​
Response Structure

The response returns both total cost and interval-by-interval breakdown of electricity costs:

{
  "context": {
    "currency": "DKK",
    "unit": "per_kwh",
    "time_span": "60min",
    "location": {
      "input_address": "Rådhuspladsen 1, Copenhagen",
      "coordinates": {
        "latitude": 55.6761,
        "longitude": 12.5683,
        "confidence": 9
      }
    },
    "vat_handling": "excluded"
  },
  "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_cost": "0.567150",
  "results": [
    {
      "datetime": "2023-10-15T14:00:00Z",
      "elements": [
        {
          "id": "com_123",
          "cost": "0.078150"
        },
        {
          "id": "com_789",
          "cost": "0.156750"
        }
      ],
      "interval_cost": "0.234900"
    },
    {
      "datetime": "2023-10-15T15:00:00Z",
      "elements": [
        {
          "id": "com_123",
          "cost": "0.109410"
        },
        {
          "id": "com_789",
          "cost": "0.222840"
        }
      ],
      "interval_cost": "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.

​
VAT Handling

Control how Value Added Tax is represented in the response:

​
Best Practices

Provide consumption data aligned with the specified time_span. For example, if time_span is 60min, 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.

Use the detail parameter to control response size. If you only need total costs, use detail=summarized to minimize response payload size.

​
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 time_span values.

Ensure your application handles these errors gracefully and provides meaningful feedback to users.