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

# Location-Based Pricing

> Using geographic information to access accurate electricity pricing

Electricity pricing varies by location due to different grid operators, market regions, and regulatory frameworks. The Prezio API uses precise location data to determine applicable tariffs.

## Specifying Location

<Warning>
  **Country code is ALWAYS required** for all location-based requests, regardless of whether you use an address or coordinates.
</Warning>

<AccordionGroup>
  <Accordion title="Country Code (Required)" icon="globe" defaultOpen>
    The country code is the primary market identifier and is **required** for all requests.

    It corresponds to the country code used in the [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) standard.

    ```bash
    # Required parameter for all location-based requests
    country=DK
    ```

    To get the most up-to-date list of supported countries:

    ```bash
    GET /countries/
    ```
  </Accordion>

  <Accordion title="Address (Optional)" icon="map-pin">
    Prezio automatically geocodes addresses to coordinates using [OpenStreetMap](https://openstreetmap.org/) services.

    ```bash
    # Full text address (must be used with country)
    country=DK&address=Rådhuspladsen 1, Copenhagen
    ```

    ### Geocoding Process

    1. The API converts your address to coordinates using OpenStreetMap
    2. Validates that the geocoded location is within the specified country
    3. Uses the resulting coordinates to determine applicable tariffs
    4. Includes a confidence score in the response (higher is better)

    <Tip>
      Include street number, street name, city, and postal code for best geocoding results.
      <br />For address conversion debugging, you can use the [OpenStreetMap UI](https://openstreetmap.org/).
    </Tip>
  </Accordion>

  <Accordion title="Coordinates (Optional)" icon="location-dot">
    For precise location targeting, provide direct geographic coordinates.

    ```bash
    # Latitude and longitude values (must be used with country)
    country=DK&latitude=55.6761&longitude=12.5683
    ```

    Both latitude and longitude must be provided together in decimal degrees (WGS84 coordinate system).
  </Accordion>
</AccordionGroup>

<CardGroup cols={1}>
  <Card title="Location Data in Responses" icon="reply" color="#83b5ab">
    API responses include the location data used for the request, allowing you to verify correct interpretation:

    ```json
    {
      "context": {
        "location": {
          "input_address": "Rådhuspladsen 1, Copenhagen",
          "coordinates": {
            "latitude": 55.6761,
            "longitude": 12.5683,
            "confidence": 9
          }
        }
      }
      // Other response data...
    }
    ```

    * `input_address`: The address you provided (if applicable)
    * `coordinates`: The exact coordinates used to determine pricing
    * `confidence`: Geocoding confidence score (1-10, with 10 being highest)
  </Card>
</CardGroup>

<Warning>
  Never provide both address and coordinates in the same request. Choose one method to specify location.
</Warning>

## How Location Affects Pricing

<CardGroup cols={3}>
  <Card title="Grid Operator" icon="tower-cell" color="#629f93">
    Your location determines which DSO (Distribution System Operator) serves your area, affecting grid costs.
  </Card>

  <Card title="Regional Tariffs" icon="map" color="#b4dbd3">
    Organizations may have different tariffs for different geographic regions within the same country.
  </Card>

  <Card title="Local Taxes" icon="receipt" color="#8099a8">
    Some electricity taxes and fees vary by municipality or region.
  </Card>
</CardGroup>

## Example Requests

<Tabs>
  <Tab title="Using Address">
    ```bash
    GET /tariffs/?country=DK&address=Rådhuspladsen 1, Copenhagen
    ```

    Returns tariffs applicable to the specified address in Denmark.
  </Tab>

  <Tab title="Using Coordinates">
    ```bash
    GET /tariffs/?country=DK&latitude=55.6761&longitude=12.5683
    ```

    Returns tariffs applicable to the specified coordinates in Denmark.
  </Tab>
</Tabs>

## Location Best Practices

<CardGroup cols={2}>
  <Card title="Use Exact Locations" icon="bullseye" color="#83b5ab">
    Provide the exact address where electricity is consumed, not approximate locations, to ensure correct tariff assignment.
  </Card>

  <Card title="Handle Geocoding Errors" icon="triangle-exclamation" color="#f4867e">
    Implement error handling for cases where addresses cannot be geocoded or return low confidence scores.
  </Card>

  <Card title="Verify Country Codes" icon="flag" color="#ffb07c">
    Double-check that you're using the correct country code for your location to avoid empty results.
  </Card>

  <Card title="Check Data Availability" icon="flask" color="#c7beff" href="/essentials/data-availability">
    Not all locations have data in the sandbox environment. Review our data availability guide for testing.
  </Card>
</CardGroup>

<Note>
  For most reliable results in production applications, we recommend caching the mapping between addresses and DSO service areas after initial lookups.
</Note>