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

# Quickstart

> Get started with the Prezio API in minutes

This quickstart guide will help you start using the Prezio API to access electricity pricing data across European markets.

## Authentication

Prezio uses key-based authentication for all API requests:

<Steps>
  <Step title="Get Your API Key">
    Obtain an API key by:

    * Registering at [dashboard.prezio.eu](https://dashboard.prezio.eu)
    * Contacting our [support team](mailto:support@prezio.eu) for sandbox access
  </Step>

  <Step title="Use the Key in Requests">
    Include your API key in the `Authorization` header with every API request:

    ```bash
    Authorization: Token YOUR_API_KEY
    ```
  </Step>
</Steps>

<Warning>
  Keep your API key secure. Don't expose it in client-side code or public repositories.
</Warning>

## API Workflow

<Info>
  Starting point: Before making API calls, you need a specific location (address or coordinates) for the end-user's price you're looking for. By providing a precise location, the API will be able to return the correct prices applicable to that specific area.
</Info>

The diagram below shows the typical workflow for retrieving electricity pricing data with the Prezio API:

```mermaid
flowchart LR
    A("Starting Point: Location<br>(address/coordinates)") --> B("**/organizations/**<br>Find applicable orgs.<br>for the location")
    B --> D("**/tariffs/**<br>Find appllicable tariffs<br>for the location<br>and selected org.")
    D --> E1("**/live/**<br>Get current prices")
    D --> E2("**/calculate/**<br>Calculate cost for<br>specific consumption")
    
    style A fill:#f8f9f7,stroke:#00211b,color:00211b,rx:10,ry:10
    style B fill:#83b5ab,stroke:#00211b,color:white
    style D fill:#c7beff,stroke:#00211b,color:#00211b
    style E1 fill:#ffb07c,stroke:#00211b,color:white
    style E2 fill:#ffb07c,stroke:#00211b,color:white
```

## API Request Flow

Follow this step-by-step process to retrieve accurate pricing data:

<Steps>
  <Step title="Find Applicable Organizations">
    First, determine which organizations (grid operators, retailers, authorities) serve your location:

    ```bash
    curl -X GET "https://sandbox.prezio.eu/api/organizations/?country=DK&address=Rådhuspladsen 1, Copenhagen" \
      -H "Authorization: Token YOUR_API_KEY"
    ```

    This returns organizations applicable to the address, including their IDs which you'll need for the next step.

    <Accordion title="Example Response">
      ```json
      {
        "count": 3,
        "next": null,
        "previous": null,
        "results": [
          {
            "id": "org_70",
            "name": "Andel Energi A/S",
            "type": "RETAILER",
            "website_url": "https://andelenergi.dk",
            "logo": "https://api.prezio.eu/media/logos/andel.png",
            "main_tariffs": [...]
          },
          {
            "id": "org_123",
            "name": "Radius Elnet",
            "type": "DSO",
            "website_url": "https://radiuselnet.dk",
            "logo": "https://api.prezio.eu/media/logos/radius.png",
            "main_tariffs": [...]
          }
        ]
      }
      ```
    </Accordion>

    Select the organization IDs you're interested in (e.g., a specific retailer and the local grid operator).
  </Step>

  <Step title="Get Applicable Tariffs">
    Next, retrieve the applicable tariffs for each selected organization:

    ```bash
    curl -X GET "https://sandbox.prezio.eu/api/tariffs/?country=DK&address=Rådhuspladsen 1, Copenhagen&organization_id=org_70" \
      -H "Authorization: Token YOUR_API_KEY"
    ```

    <Accordion title="Example Response">
      ```json
      {
        "count": 3,
        "next": null,
        "previous": null,
        "results": [
          {
            "id": "tar_456",
            "name": "Flex El",
            "description": "Variable rate electricity plan",
            "organization": {
              "id": "org_70",
              "name": "Andel Energi A/S"
            },
            "filters": {
              "consumer_type": "RESIDENTIAL",
              "consumption_minimum": null,
              "consumption_maximum": null
            }
          }
        ]
      }
      ```
    </Accordion>

    Select the tariff IDs that match your criteria (e.g., residential customer type, consumption range).
  </Step>

  <Step title="Get Current Prices or Calculate Costs">
    Finally, use the selected tariff IDs to either get current prices or calculate costs:

    <Tabs>
      <Tab title="Get Current Prices">
        ```bash
        curl -X GET "https://sandbox.prezio.eu/api/live/?country=DK&tariff_id=tar_456&tariff_id=tar_789&address=Rådhuspladsen 1, Copenhagen" \
          -H "Authorization: Token YOUR_API_KEY"
        ```

        This returns current electricity prices for all components of the selected tariffs.
      </Tab>

      <Tab title="Calculate Costs">
        ```bash
        curl -X POST "https://sandbox.prezio.eu/api/calculate/" \
          -H "Authorization: Token YOUR_API_KEY" \
          -H "Content-Type: application/json" \
          -d '{
            "country": "DK",
            "tariff_id": ["tar_456", "tar_789"],
            "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"
              }
            ]
          }'
        ```

        This calculates the cost of the specified consumption based on the selected tariffs.
      </Tab>
    </Tabs>
  </Step>
</Steps>

## Understanding Responses

API responses are in JSON format. Here's a simplified example of a response from the `/live/` endpoint:

```json
{
  "context": {
    "currency": "DKK",
    "unit": "per_kwh",
    "location": {
      "coordinates": {
        "latitude": 55.6761,
        "longitude": 12.5683
      }
    }
  },
  "results": [
    {
      "interval_start": "2023-10-15T14:00:00Z",
      "elements": [
        {
          "id": "com_123",
          "price": "0.521000"
        },
        {
          "id": "com_456",
          "price": "1.045000"
        }
      ],
      "interval_price": "1.566000"
    }
  ]
}
```

<Accordion title="Response Fields Explained">
  * `context`: Contains metadata about the response (currency, units, location)
  * `results`: Array of price intervals, each with:
    * `interval_start`: The timestamp for this price interval
    * `elements`: Individual price components
    * `interval_price`: Total price for this interval (sum of all elements)
</Accordion>

## API Environments

Use the same API key for both environments, but call different base URLs:

<CardGroup cols={2}>
  <Card title="Sandbox" icon="flask" color="#8b5cf6">
    **URL**: `https://sandbox.prezio.eu/api/`

    **Access**: Open to all registered users\
    **Purpose**: Development and testing with limited data coverage

    [Data availability →](/essentials/data-availability)
  </Card>

  <Card title="Production" icon="server" color="#16a34a">
    **URL**: `https://api.prezio.eu/api/`

    **Access**: Requires contract (contact support)\
    **Purpose**: Production applications with complete data coverage
  </Card>
</CardGroup>

<Note>
  Production access depends on your contract. Contact [support@prezio.eu](mailto:support@prezio.eu) to enable production access.
</Note>

## Beta Features

<Warning>
  **Beta Endpoints Available**: Some API endpoints are currently in beta. These features are subject to changes and errors.
</Warning>

For detailed information about beta endpoints, see the [API Reference](/api-reference), and don't hesitate to contact us.

## Next Steps

<CardGroup cols={3}>
  <Card title="API Reference" icon="code" href="/api-reference/organizations">
    Browse all available endpoints and parameters
  </Card>

  <Card title="Location Guide" icon="map-location-dot" href="/essentials/location">
    Learn how to specify locations correctly
  </Card>

  <Card title="Tariffs Guide" icon="file-invoice-dollar" href="/essentials/tariffs">
    Understand tariff structures and components
  </Card>
</CardGroup>

<Tip>
  Having questions? Contact our [support team](mailto:support@prezio.eu).
</Tip>