mirror of https://github.com/jpawlowski/hass.tibber_prices.git synced 2026-05-28 18:43:40 +00:00

Julian Pawlowski aa9a1200b8 chore(style): normalize Markdown list indentation across all docs

Convert four-space-indented list items (`-   item`) to standard two-space
(`- item`) in AGENTS.md, CONTRIBUTING.md, README.md, and all Docusaurus
documentation pages (developer and user, including versioned snapshots).
No content changes.

Release-Notes: skip

2026-04-12 14:15:31 +00:00

3.8 KiB

Raw Blame History

comments
false

API Reference

Documentation of the Tibber GraphQL API used by this integration.

GraphQL Endpoint

https://api.tibber.com/v1-beta/gql

Authentication: Bearer token in Authorization header

Queries Used

User Data Query

Fetches home information and metadata:

query {
    viewer {
        homes {
            id
            appNickname
            address {
                address1
                postalCode
                city
                country
            }
            timeZone
            currentSubscription {
                priceInfo {
                    current {
                        currency
                    }
                }
            }
            meteringPointData {
                consumptionEan
                gridAreaCode
            }
        }
    }
}

Cached for: 24 hours

Price Data Query

Fetches quarter-hourly prices:

query ($homeId: ID!) {
    viewer {
        home(id: $homeId) {
            currentSubscription {
                priceInfo {
                    range(resolution: QUARTER_HOURLY, first: 384) {
                        nodes {
                            total
                            startsAt
                            level
                        }
                    }
                }
            }
        }
    }
}

Parameters:

homeId: Tibber home identifier
resolution: Always QUARTER_HOURLY
first: 384 intervals (4 days of data)

Cached until: Midnight local time

Rate Limits

Tibber API rate limits (as of 2024):

5000 requests per hour per token
Burst limit: 100 requests per minute

Integration stays well below these limits:

Polls every 15 minutes = 96 requests/day
User data cached for 24h = 1 request/day
Total: ~100 requests/day per home

Response Format

Price Node Structure

{
    "total": 0.2456,
    "startsAt": "2024-12-06T14:00:00.000+01:00",
    "level": "NORMAL"
}

Fields:

total: Price including VAT and fees (currency's major unit, e.g., EUR)
startsAt: ISO 8601 timestamp with timezone
level: Tibber's own classification (VERY_CHEAP, CHEAP, NORMAL, EXPENSIVE, VERY_EXPENSIVE)

Currency Information

{
    "currency": "EUR"
}

Supported currencies:

EUR (Euro) - displayed as ct/kWh
NOK (Norwegian Krone) - displayed as øre/kWh
SEK (Swedish Krona) - displayed as öre/kWh

Error Handling

Common Error Responses

Invalid Token:

{
    "errors": [
        {
            "message": "Unauthorized",
            "extensions": {
                "code": "UNAUTHENTICATED"
            }
        }
    ]
}

Rate Limit Exceeded:

{
    "errors": [
        {
            "message": "Too Many Requests",
            "extensions": {
                "code": "RATE_LIMIT_EXCEEDED"
            }
        }
    ]
}

Home Not Found:

{
    "errors": [
        {
            "message": "Home not found",
            "extensions": {
                "code": "NOT_FOUND"
            }
        }
    ]
}

Integration handles these with:

Exponential backoff retry (3 attempts)
ConfigEntryAuthFailed for auth errors
ConfigEntryNotReady for temporary failures

Data Transformation

Raw API data is enriched with:

Trailing 24h average - Calculated from previous intervals
Leading 24h average - Calculated from future intervals
Price difference % - Deviation from average
Custom rating - Based on user thresholds (different from Tibber's level)

See utils/price.py for enrichment logic.

💡 External Resources:

3.8 KiB Raw Blame History