Skip to main content
Version: Next 🚧

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: