> ## 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.

# Live API Endpoint

> Get real-time electricity prices for specific tariffs at a location

The `/live/` endpoint provides current electricity prices for specified tariffs at a given location. This endpoint returns a timeseries of price data covering recent hours and upcoming periods, making it ideal for applications needing current pricing information.

## Endpoint Overview

```bash
GET /live/
```

This endpoint returns electricity pricing data for specified tariffs, with options to control the level of detail and time resolution.

### Data Flow Diagram

```mermaid
flowchart LR
  A(Client Application) -->|Request Price Data| B(Prezio API)
  B -->|Return Current Prices| A
  subgraph Prezio Backend
    B
  end
```

## Key Parameters

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

<ParamField query="tariff_id" type="array" required>
  Tariff IDs to retrieve prices for. Multiple IDs can be specified by repeating the parameter.
  Each tariff ID must include the `tar_` prefix (e.g., `tar_123`).
</ParamField>

<ParamField query="address" type="string">
  Location address to determine applicable pricing. Required if coordinates not provided.
</ParamField>

<ParamField query="latitude" type="number">
  Latitude coordinate of the location. Required if address not provided.
</ParamField>

<ParamField query="longitude" type="number">
  Longitude coordinate of the location. Required if address not provided.
</ParamField>

<ParamField query="interval_minutes" type="integer" default="60">
  Time resolution of returned prices in minutes. Options: `60`, `30`, or `15`.
</ParamField>

<ParamField query="detail" type="string" default="full">
  Level of detail in the response:

  * `summarized`: Only total price
  * `semi`: Prices aggregated by organization type
  * `full`: Complete breakdown of all price components
</ParamField>

<ParamField query="vat" type="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
</ParamField>

## Location Specification

The Live 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 Range

The Live endpoint returns price data for approximately 3 days:

* Yesterday (from midnight yesterday in local time)
* Today
* Tomorrow (until end of day in local time)

This ensures you have access to recent historical prices and upcoming prices for live energy optimization.

<Note>
  The endpoint will return null values for future time periods if price data is not yet available (e.g. before day ahead spot market prices are published, for spot-based tariffs).
</Note>

## 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

<CodeGroup>
  ```bash cURL
  curl -X GET "https://api.prezio.dev/v1/live/?country=DK&tariff_id=tar_123&tariff_id=tar_456&address=Rådhuspladsen 1, Copenhagen&detail=full&interval_minutes=60"
  ```

  ```javascript Node.js
  const axios = require('axios');

  const response = await axios.get('https://api.prezio.dev/v1/live/', {
    params: {
      country: 'DK',
      tariff_id: ['tar_123', 'tar_456'],
      address: 'Rådhuspladsen 1, Copenhagen',
      detail: 'full',
      interval_minutes: 60
    },
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY'
    }
  });
  ```
</CodeGroup>

## Response Structure

The response contains a timeseries of pricing data with information about tariff components:

<Tabs>
  <Tab title="Full Detail">
    ```json
    {
      "count": 24,
      "context": {
        "currency": "DKK",
        "unit": "per_kwh",
        "interval_minutes": 60,
        "location": {
          "input_address": "Rådhuspladsen 1, Copenhagen",
          "coordinates": {
            "latitude": 55.6761,
            "longitude": 12.5683,
            "confidence": 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"
        }
      ],
      "results": [
        {
          "interval_start": "2023-10-15T14:00:00Z",
          "elements": [
            {
              "id": "com_123",
              "price": "0.052100"
            },
            {
              "id": "com_789",
              "price": "0.104500"
            }
          ],
          "interval_price": "0.156600"
        },
        {
          "interval_start": "2023-10-15T15:00:00Z",
          "elements": [
            {
              "id": "com_123",
              "price": "0.052100"
            },
            {
              "id": "com_789",
              "price": "0.119500"
            }
          ],
          "interval_price": "0.171600"
        }
      ]
    }
    ```
  </Tab>

  <Tab title="Semi Detail">
    ```json
    {
      "count": 24,
      "context": {
        "currency": "DKK",
        "unit": "per_kwh",
        "interval_minutes": 60,
        "location": {
          "input_address": "Rådhuspladsen 1, Copenhagen",
          "coordinates": {
            "latitude": 55.6761,
            "longitude": 12.5683,
            "confidence": 9
          }
        }
      },
      "tariff_elements": [
        {
          "element_id": "key_DSO",
          "organization_type": "DSO"
        },
        {
          "element_id": "key_RET",
          "organization_type": "RET"
        }
      ],
      "results": [
        {
          "interval_start": "2023-10-15T14:00:00Z",
          "elements": [
            {
              "id": "key_DSO",
              "price": "0.052100"
            },
            {
              "id": "key_RET",
              "price": "0.104500"
            }
          ],
          "interval_price": "0.156600"
        }
      ]
    }
    ```
  </Tab>

  <Tab title="Summarized">
    ```json
    {
      "count": 24,
      "context": {
        "currency": "DKK",
        "unit": "per_kwh",
        "interval_minutes": 60,
        "location": {
          "input_address": "Rådhuspladsen 1, Copenhagen",
          "coordinates": {
            "latitude": 55.6761,
            "longitude": 12.5683,
            "confidence": 9
          }
        }
      },
      "results": [
        {
          "interval_start": "2023-10-15T14:00:00Z",
          "interval_price": "0.156600"
        },
        {
          "interval_start": "2023-10-15T15:00:00Z",
          "interval_price": "0.171600"
        }
      ]
    }
    ```
  </Tab>
</Tabs>

## Detail Levels

<CardGroup cols={3}>
  <Card title="Full Detail" icon="list-check" color="#83b5ab">
    Returns all price components individually with metadata about each component, ideal for detailed cost analysis.
  </Card>

  <Card title="Semi Detail" icon="layer-group" color="#3f8376">
    Aggregates costs by organization type (DSO, Retailer, etc.), providing simplified but still informative breakdown.
  </Card>

  <Card title="Summarized" icon="calculator" color="#c7beff">
    Returns only total price for each time interval, useful when only the bottom line matters.
  </Card>
</CardGroup>

## VAT Handling

Control how Value Added Tax is represented in the response:

<AccordionGroup>
  <Accordion title="VAT Excluded" icon="circle-minus" defaultOpen>
    All prices exclude VAT (default behavior).

    ```json
    {
      "elements": [
        {"id": "com_123", "price": "0.052100"},
        {"id": "com_456", "price": "0.104500"}
      ],
      "interval_price": "0.156600"
    }
    ```
  </Accordion>

  <Accordion title="VAT Included" icon="circle-plus">
    Each price component includes its applicable VAT.

    ```json
    {
      "elements": [
        {"id": "com_123", "price": "0.065125"},
        {"id": "com_456", "price": "0.130625"}
      ],
      "interval_price": "0.195750"
    }
    ```
  </Accordion>

  <Accordion title="VAT Separated" icon="layer-group">
    VAT is shown as separate component(s).

    ```json
    {
      "elements": [
        {"id": "com_123", "price": "0.052100"},
        {"id": "com_456", "price": "0.104500"},
        {"id": "vat_25_com_123", "price": "0.013025"},
        {"id": "vat_25_com_456", "price": "0.026125"}
      ],
      "interval_price": "0.195750"
    }
    ```
  </Accordion>
</AccordionGroup>

## Best Practices

<Tip>
  For most applications, request only the tariffs you need. If you know exactly which tariffs apply to a user, specify those tariff IDs directly rather than retrieving all possible tariffs.
</Tip>

<Warning>
  The Live endpoint may return null values for future time periods if price data (especially spot market prices) is not yet available. Handle these cases gracefully in your application.
</Warning>

<Check>
  Use the detail parameter to control response size. If you only need total prices, use `detail=summarized` to minimize response payload size.
</Check>

## Common Use Cases

<CardGroup cols={2}>
  <Card title="Real-Time Pricing Display" icon="gauge-high" color="#83b5ab">
    Show current and upcoming electricity prices to help users make informed decisions about energy usage.
  </Card>

  <Card title="Smart Device Control" icon="bolt" color="#3f8376">
    Power automated systems that activate or deactivate devices based on current electricity prices.
  </Card>

  <Card title="Cost Forecasting" icon="chart-line" color="#c7beff">
    Provide users with near-term cost projections for planned energy consumption.
  </Card>

  <Card title="Price Alerts" icon="bell" color="#ffb07c">
    Notify users when electricity prices fall below or rise above specified thresholds.
  </Card>
</CardGroup>