> ## Documentation Index
> Fetch the complete documentation index at: https://docs-dev.prezio.eu/llms.txt
> Use this file to discover all available pages before exploring further.

# Calculate Advanced API Endpoint

> Calculate detailed electricity costs for multiple component types with enhanced precision

<Warning>
  **Beta Endpoint**: This endpoint is currently in beta. Errors may happen and changes may occur. Contact [support@prezio.com](mailto:support@prezio.com) for assistance.
</Warning>

The `/calculate-advanced/` endpoint provides enhanced electricity cost calculations with support for multiple component types, Time-of-Use (TOU) pricing, and component-level input control.

Unlike the standard `/calculate/` endpoint, this advanced version allows to calculate multiple component types in a single request, and to control the calculation of individual tariff components.

For that reason, the `/calculate-advanced/` endpoint is more complex than the standard `/calculate/` endpoint, requires more input parameters, and can only be used one tariff at a time.

## Endpoint Overview

```bash
POST /calculate-advanced/
```

This endpoint processes component-level inputs to calculate detailed electricity costs across multiple component types including energy consumption, demand charges, capacity fees, fixed costs, reactive power charges, and taxes.

### Key Differences from Standard Calculate

<CardGroup cols={2}>
  <Card title="Component-Level Control" icon="sliders" color="#83b5ab">
    Target specific tariff components using their `prezio_code` identifiers from the tariffs endpoint.
  </Card>

  <Card title="Multiple Component Types" icon="layer-group" color="#3f8376">
    Support for KWH, DEMAND, CAPACITY, REACTIVE, EXCESS, FIXED, and TAX components in a single request.
  </Card>

  <Card title="Enhanced Input Types" icon="gear" color="#c7beff">
    Use `CALCULATION_INPUT` for usage data and `PRICE_PROPERTY` for component configuration.
  </Card>

  <Card title="TOU Precision" icon="clock" color="#ffb07c">
    Fine-grained Time-of-Use calculations with support for custom TOU levels.
  </Card>
</CardGroup>

## Key Parameters

### Required Parameters

<ParamField body="country" type="string" required>
  Country code (e.g., `DK`, `SE`) for the location to ensure geographic correctness.
</ParamField>

<ParamField body="tariff_id" type="string" required>
  Single tariff ID with `tar_` prefix (e.g., `tar_123`).
</ParamField>

<ParamField body="period_start" type="string" required>
  Start of calculation period (ISO 8601 format, e.g., `2025-01-01T00:00:00Z`).
</ParamField>

<ParamField body="period_end" type="string" required>
  End of calculation period (ISO 8601 format). Maximum 1 month from start.
</ParamField>

### Location Parameters

<ParamField body="address" type="string">
  Full address for location resolution. Required unless latitude/longitude are provided. Cannot be used with coordinates.
</ParamField>

<ParamField body="latitude" type="number">
  Latitude coordinate (must be used together with longitude). Cannot be used with address.
</ParamField>

<ParamField body="longitude" type="number">
  Longitude coordinate (must be used together with latitude). Cannot be used with address.
</ParamField>

### Input Parameters

<ParamField body="inputs" type="array">
  Array of component-level inputs with structure:

  ```json
  {
    "component_key": "kwh",
    "input_type": "CALCULATION_INPUT",
    "key": "consumption_total",
    "tou_level": "ON_PEAK",
    "value": 120.5
  }
  ```

  Required unless only FIXED components are being calculated (auto-calculated).
</ParamField>

### Filtering Parameters

<ParamField body="component_types" type="array" default="all types">
  Array of component types to include in calculation. Valid types: `KWH`, `FIXED`, `CAPACITY`, `DEMAND`, `REACTIVE`, `EXCESS`, `TAX`. If empty or not provided, all component types will be included.
</ParamField>

<ParamField body="component_ids" type="array">
  Array of specific component IDs to target, with `com_` prefix (e.g., `["com_123", "com_456"]`). Only components belonging to the specified tariff are allowed. If not provided, all components (filtered by component\_types if specified) will be included.
</ParamField>

### Calculation Parameters

<ParamField body="vat" type="string" default="excluded">
  How VAT should be handled in the response:

  * `excluded`: Prices exclude VAT (default)
  * `included`: VAT included in each component
</ParamField>

<ParamField body="prorate" type="boolean" default="false">
  Whether to prorate FIXED component costs based on the requested period duration. If `false` (default), charges whole periods that fall within the timeframe. If `true`, calculates proportional cost based on actual period duration.
</ParamField>

## Input Types

<AccordionGroup>
  <Accordion title="CALCULATION_INPUT" icon="calculator" defaultOpen>
    Used for providing usage data like consumption amounts or demand values.

    ```json
    {
      "component_key": "kwh",
      "input_type": "CALCULATION_INPUT",
      "key": "consumption_total",
      "tou_level": "ON_PEAK",  // Optional for TOU components
      "value": 120.5
    }
    ```
  </Accordion>

  <Accordion title="PRICE_PROPERTY" icon="gear">
    Used for configuring component behavior like fuse levels or subscription options.

    ```json
    {
      "component_key": "Subscription", 
      "input_type": "PRICE_PROPERTY",
      "key": "has_ev",
      "value": true
    }
    ```
  </Accordion>
</AccordionGroup>

## Response Structure

The response includes three main sections:

* **`context`**: Request metadata, location, tariff, period, and currency information
* **`inputs`**: Echo of input data with resolved component IDs and confidence scores
* **`results`**: Detailed component calculations with price versions showing rate breakdowns
* **`total_price`**: Sum of all component prices

## Example Requests

<CodeGroup>
  ```json Basic Request
  {
    "country": "DK",
    "address": "Copenhagen, Denmark",
    "tariff_id": "tar_45",
    "period_start": "2025-01-01T00:00:00Z",
    "period_end": "2025-01-31T23:59:59Z",
    "inputs": [
      {
        "component_key": "kwh",
        "input_type": "CALCULATION_INPUT",
        "key": "consumption_total",
        "tou_level": "ON_PEAK",
        "value": 120.5
      },
      {
        "component_key": "Subscription",
        "input_type": "PRICE_PROPERTY",
        "key": "has_ev",
        "value": true
      }
    ]
  }
  ```

  ```json Advanced Request with Filtering
  {
    "country": "DK",
    "latitude": 55.6761,
    "longitude": 12.5683,
    "tariff_id": "tar_45",
    "period_start": "2025-01-15T00:00:00Z",
    "period_end": "2025-02-14T23:59:59Z",
    "component_types": ["KWH", "DEMAND", "FIXED"],
    "component_ids": ["com_123", "com_456"],
    "vat": "included",
    "prorate": true,
    "inputs": [
      {
        "component_key": "kwh",
        "input_type": "CALCULATION_INPUT",
        "key": "consumption_total",
        "value": 1500
      },
      {
        "component_key": "demand-charge",
        "input_type": "CALCULATION_INPUT",
        "key": "peak_demand_single",
        "tou_level": "ON_PEAK",
        "value": 75.0
      }
    ]
  }
  ```
</CodeGroup>

## Getting Started

<Steps>
  <Step title="Retrieve Tariff Information">
    Use the `/tariffs/{tariff_id}/` endpoint to get `calculation_requirements` for available components and their input keys.
  </Step>

  <Step title="Prepare Component Inputs">
    Structure your inputs using the component `prezio_code` identifiers and required input keys from the tariff data.
  </Step>

  <Step title="Make Calculation Request">
    Send your component-level inputs to receive detailed cost breakdowns with price version details.
  </Step>
</Steps>

## Support & Demo

This endpoint supports complex electricity pricing scenarios with multiple component types and advanced configuration options.

<Tip>
  **Need Help?** Contact **[support@prezio.com](mailto:support@prezio.com)** for:

  * API integration assistance
  * Custom component configuration guidance
  * Live demo of advanced calculation features
  * Best practices for your specific use case
</Tip>

For additional API details, see the [API Reference](/api-reference/endpoint/calculate-advanced) documentation.