hass.tibber_prices/custom_components/tibber_prices/services.yaml

get_price:
  name: Get Price Data
  description: >-
    Fetch price data for a specific time range with automatic routing. Development and testing service for the price_info_for_range API function. Automatically uses PRICE_INFO, PRICE_INFO_RANGE, or both based on the time range boundary.    
  fields:
    entry_id:
      name: Entry ID
      description: The config entry ID for the Tibber integration.
      required: true
      example: "1234567890abcdef"
      selector:
        config_entry:
          integration: tibber_prices
    start_time:
      name: Start Time
      description: Start of the time range (inclusive, timezone-aware).
      required: true
      example: "2025-11-01T00:00:00+01:00"
      selector:
        datetime:
    end_time:
      name: End Time
      description: End of the time range (exclusive, timezone-aware).
      required: true
      example: "2025-11-02T00:00:00+01:00"
      selector:
        datetime:
get_apexcharts_yaml:
  name: Get ApexCharts Card YAML
  description: >-
    Returns a ready-to-copy YAML snippet for an ApexCharts card visualizing Tibber Prices for the selected day. Use this to easily add a pre-configured chart to your dashboard. The YAML will use the get_chartdata service for data.    
  fields:
    entry_id:
      name: Entry ID
      description: The config entry ID for the Tibber integration.
      required: true
      example: "1234567890abcdef"
      selector:
        config_entry:
          integration: tibber_prices
    day:
      name: Day
      description: Which day to visualize (yesterday, today, or tomorrow).
      required: false
      default: today
      example: today
      selector:
        select:
          options:
            - yesterday
            - today
            - tomorrow
          translation_key: day
    level_type:
      name: Level Type
      description: >-
        Select which price level classification to visualize: 'rating_level' (LOW/NORMAL/HIGH based on your configured thresholds) or 'level' (Tibber API levels: VERY_CHEAP/CHEAP/NORMAL/EXPENSIVE/VERY_EXPENSIVE).        
      required: false
      default: rating_level
      example: rating_level
      selector:
        select:
          options:
            - rating_level
            - level
          translation_key: level_type
    highlight_best_price:
      name: Highlight Best Price Periods
      description: >-
        Add a semi-transparent green overlay to highlight the best price periods on the chart. This makes it easy to visually identify the optimal times for energy consumption.        
      required: false
      default: true
      example: true
      selector:
        boolean:
get_chartdata:
  name: Get Chart Data
  description: >-
    Returns price data in a simple chart-friendly format compatible with the Tibber Core integration output structure. Perfect for use with popular chart cards like ha-price-timeline-card, ApexCharts Card, Plotly Graph Card, Mini Graph Card, or the built-in History Graph Card. Field names and data structure can be customized to match your specific chart requirements.    
  fields:
    # === REQUIRED ===
    entry_id:
      name: Entry ID
      description: The config entry ID for the Tibber integration.
      required: true
      example: "1234567890abcdef"
      selector:
        config_entry:
          integration: tibber_prices
    # === DATA SELECTION ===
    day:
      name: Day
      description: Which day(s) to fetch prices for. You can select multiple days. If not specified, returns all available data (today + tomorrow if available).
      required: false
      selector:
        select:
          options:
            - yesterday
            - today
            - tomorrow
          multiple: true
          translation_key: day
    resolution:
      name: Resolution
      description: >-
        Time resolution for the returned data. Options: 'interval' (default, 15-minute intervals, 96 points per day), 'hourly' (hourly averages, 24 points per day).        
      required: false
      default: interval
      example: hourly
      selector:
        select:
          options:
            - interval
            - hourly
          translation_key: resolution
    # === FILTERS ===
    level_filter:
      name: Level Filter
      description: >-
        Filter intervals to include only specific Tibber price levels (very_cheap, cheap, normal, expensive, very_expensive). If not specified, all levels are included.        
      required: false
      selector:
        select:
          options:
            - very_cheap
            - cheap
            - normal
            - expensive
            - very_expensive
          multiple: true
          translation_key: level_filter
    rating_level_filter:
      name: Rating Level Filter
      description: >-
        Filter intervals to include only specific rating levels (low, normal, high). If not specified, all rating levels are included.        
      required: false
      selector:
        select:
          options:
            - low
            - normal
            - high
          multiple: true
          translation_key: rating_level_filter
    period_filter:
      name: Period Filter
      description: >-
        Filter intervals to include only those within Best Price or Peak Price periods. Options: 'best_price' (only intervals in Best Price periods), 'peak_price' (only intervals in Peak Price periods). If not specified, all intervals are included. This uses the precomputed period data from binary sensors (binary_sensor.best_price_period / binary_sensor.peak_price_period).        
      required: false
      selector:
        select:
          options:
            - best_price
            - peak_price
          translation_key: period_filter
    # === FILTER BEHAVIOR ===
    insert_nulls:
      name: Insert NULL Values
      description: >-
        Control NULL value insertion for filtered data. 'none' (default): No NULL values, only matching intervals. 'segments': Add NULL points at segment boundaries for clean gaps in charts (recommended for stepline charts). 'all': Insert NULL for all timestamps where filter doesn't match (useful for continuous time series visualization).        
      required: false
      default: none
      selector:
        select:
          options:
            - none
            - segments
            - all
          translation_key: insert_nulls
    connect_segments:
      name: Connect Segments
      description: >-
        [ONLY WITH insert_nulls='segments'] When enabled, adds connecting points at segment boundaries to visually connect different price level segments in stepline charts. When price goes DOWN at a boundary, adds a point with the lower price at the end of the current segment. When price goes UP, adds a hold point before the gap. This creates smooth visual transitions between segments instead of abrupt gaps.        
      required: false
      default: false
      selector:
        boolean:
    # === OUTPUT FORMAT ===
    output_format:
      name: Output Format
      description: >-
        Output format for the returned data. Options: 'array_of_objects' (default, array of objects with customizable field names), 'array_of_arrays' (array of [timestamp, price] arrays).        
      required: false
      default: array_of_objects
      example: array_of_objects
      selector:
        select:
          options:
            - array_of_objects
            - array_of_arrays
          translation_key: output_format
    # === CURRENCY & PRECISION ===
    minor_currency:
      name: Minor Currency
      description: >-
        Return prices in minor currency units (cents for EUR, øre for NOK/SEK) instead of major currency units. Disabled by default.        
      required: false
      default: false
      example: true
      selector:
        boolean:
    round_decimals:
      name: Round Decimals
      description: >-
        Number of decimal places to round prices to (0-10). If not specified, uses default precision (4 decimals for major currency, 2 for minor currency).        
      required: false
      example: 2
      selector:
        number:
          min: 0
          max: 10
          mode: box
    # === ARRAY OF ARRAYS OPTIONS ===
    add_trailing_null:
      name: Add Trailing Null Point
      description: >-
        [BOTH FORMATS] Add a final data point with null values (except timestamp) at the end. Some chart libraries need this to prevent extrapolation/interpolation to the viewport edge when using stepline rendering. Leave disabled unless your chart requires it.        
      required: false
      default: false
      selector:
        boolean:
    array_fields:
      name: Array Fields (array_of_arrays only)
      description: >-
        [ONLY FOR array_of_arrays FORMAT] Define which fields to include. Use field names in curly braces, separated by commas. Available fields: start_time, price_per_kwh, level, rating_level, average. Fields will be automatically enabled even if include_* options are not set. Leave empty for default (timestamp and price only).        
      required: false
      selector:
        text:
    # === ARRAY OF OBJECTS OPTIONS ===
    include_level:
      name: Include Level (array_of_objects only)
      description: >-
        [ONLY FOR array_of_objects FORMAT] Include the Tibber price level field (VERY_CHEAP, CHEAP, NORMAL, EXPENSIVE, VERY_EXPENSIVE) in each data point.        
      required: false
      default: false
      example: true
      selector:
        boolean:
    include_rating_level:
      name: Include Rating Level (array_of_objects only)
      description: >-
        [ONLY FOR array_of_objects FORMAT] Include the calculated rating level field (LOW, NORMAL, HIGH) based on your configured thresholds in each data point.        
      required: false
      default: false
      example: true
      selector:
        boolean:
    include_average:
      name: Include Average (array_of_objects only)
      description: >-
        [ONLY FOR array_of_objects FORMAT] Include the daily average price in each data point for comparison.        
      required: false
      default: false
      selector:
        boolean:
    # === ARRAY OF OBJECTS - FIELD NAMES ===
    start_time_field:
      name: Start Time Field Name (array_of_objects only)
      description: >-
        [ONLY FOR array_of_objects FORMAT] Custom name for the start time field in the output. Defaults to "start_time" if not specified.        
      required: false
      example: time
      selector:
        text:
    end_time_field:
      name: End Time Field Name (array_of_objects only)
      description: >-
        [ONLY FOR array_of_objects FORMAT] Custom name for the end time field in the output. Defaults to "end_time" if not specified. Only used with period_filter.        
      required: false
      example: end
      selector:
        text:
    price_field:
      name: Price Field Name (array_of_objects only)
      description: >-
        [ONLY FOR array_of_objects FORMAT] Custom name for the price field in the output. Defaults to "price_per_kwh" if not specified.        
      required: false
      example: price
      selector:
        text:
    level_field:
      name: Level Field Name (array_of_objects only)
      description: >-
        [ONLY FOR array_of_objects FORMAT] Custom name for the level field in the output. Defaults to "level" if not specified. Only used when include_level is enabled.        
      required: false
      selector:
        text:
    rating_level_field:
      name: Rating Level Field Name (array_of_objects only)
      description: >-
        [ONLY FOR array_of_objects FORMAT] Custom name for the rating_level field in the output. Defaults to "rating_level" if not specified. Only used when include_rating_level is enabled.        
      required: false
      selector:
        text:
    average_field:
      name: Average Field Name (array_of_objects only)
      description: >-
        [ONLY FOR array_of_objects FORMAT] Custom name for the average field in the output. Defaults to "average" if not specified. Only used when include_average is enabled.        
      required: false
      selector:
        text:
    # === Top-Level Response Key (both formats) ===
    data_key:
      name: Data Key (both formats)
      description: >-
        [BOTH FORMATS] Custom name for the top-level data key in the response. Defaults to "data" if not specified. For ApexCharts compatibility with array_of_arrays, use "points".        
      required: false
      example: prices
      selector:
        text:
refresh_user_data:
  name: Refresh User Data
  description: >-
    Forces a refresh of the user data (homes, profile information) from the Tibber API. This can be useful after making changes to your Tibber account or when troubleshooting connectivity issues.    
  fields:
    entry_id:
      name: Entry ID
      description: The config entry ID for the Tibber integration.
      required: true
      example: "1234567890abcdef"
      selector:
        config_entry:
          integration: tibber_prices