home-assistant.io/source/_components/sensor.history_stats.markdown

layout, title, description, date, sidebar, comments, sharing, footer, logo, ha_category, ha_iot_class, ha_release, ha_qa_scale

layout	title	description	date	sidebar	comments	sharing	footer	logo	ha_category	ha_iot_class	ha_release	ha_qa_scale
page	History Statistics Sensor	Instructions about how to integrate historical statistics into Home Assistant.	2017-02-10 12:00	true	false	true	true	home-assistant.png	Utility	Local Polling	0.39	internal

The history_stats sensor platform provides quick statistics about another component or platforms, using data from the history.

It can track how long the component has been in a specific state, in a custom time period.

Examples of what you can track:

• How long you were at home this week
• How long the lights were ON yesterday
• How long you watched TV today

{% linkable_title Configuration %}

To enable the history statistics sensor, add the following lines to your configuration.yaml:

{% raw %}

# Example configuration.yaml entry
sensor:
  - platform: history_stats
    name: Lamp ON today
    entity_id: light.my_lamp
    state: 'on'
    type: time
    start: '{{ now().replace(hour=0).replace(minute=0).replace(second=0) }}'
    end: '{{ now() }}'

{% endraw %}

{% configuration %} entity_id: description: The entity you want to track. required: true type: string state: description: The state you want to track. required: true type: string name: description: Name displayed on the frontend. required: false default: unnamed statistics type: string type: description: "The type of sensor: time, ratio, or count." required: false default: time type: string start: description: When to start the measure (timestamp or datetime). required: false type: template end: description: When to stop the measure (timestamp or datetime). required: false type: template duration: description: Duration of the measure. required: false type: time {% endconfiguration %}

You have to provide **exactly 2** of `start`, `end` and `duration`.
You can use [template extensions](/topics/templating/#home-assistant-template-extensions) such as `now()` or `as_timestamp()` to handle dynamic dates, as shown in the examples below.

{% linkable_title Sensor type %}

Depending on the sensor type you choose, the history_stats component can show different values:

• time: The default value, which is the tracked time, in hours
• ratio: The tracked time divided by the length of your period, as a percentage
• count: How many times the component you track was changed to the state you track

{% linkable_title Time periods %}

The history_stats component will execute a measure within a precise time period. You should always provide 2 of the following :

• When the period starts (start variable)
• When the period ends (end variable)
• How long is the period (duration variable)

As start and end variables can be either datetimes or timestamps, you can configure almost any period you want.

{% linkable_title Duration %}

The duration variable is used when the time period is fixed. Different syntaxes for the duration are supported, as shown below.

# 6 hours
duration: 06:00

# 1 minute, 30 seconds
duration: 00:01:30

# 2 hours and 30 minutes
duration:
  # supports seconds, minutes, hours, days
  hours: 2
  minutes: 30

{% linkable_title Examples %}

Here are some examples of periods you could work with, and what to write in your configuration.yaml:

Today: starts at 00:00 of the current day and ends right now.

{% raw %}

    start: '{{ now().replace(hour=0).replace(minute=0).replace(second=0) }}'
    end: '{{ now() }}'

{% endraw %}

Yesterday: ends today at 00:00, lasts 24 hours.

{% raw %}

    end: '{{ now().replace(hour=0).replace(minute=0).replace(second=0) }}'
    duration:
      hours: 24

{% endraw %}

This morning (6AM - 11AM): starts today at 6, lasts 5 hours.

{% raw %}

    start: '{{ now().replace(hour=6).replace(minute=0).replace(second=0) }}'
    duration:
      hours: 5

{% endraw %}

Current week: starts last Monday at 00:00, ends right now.

Here, last Monday is today as a timestamp, minus 86400 times the current weekday (86400 is the number of seconds in one day, the weekday is 0 on Monday, 6 on Sunday).

{% raw %}

    start: '{{ as_timestamp( now().replace(hour=0).replace(minute=0).replace(second=0) ) - now().weekday() * 86400 }}'
    end: '{{ now() }}'

{% endraw %}

Last 30 days: ends today at 00:00, lasts 30 days. Easy one.

{% raw %}

    end: '{{ now().replace(hour=0).replace(minute=0).replace(second=0) }}'
    duration:
      days: 30

{% endraw %}

All your history starts at timestamp = 0, and ends right now.

{% raw %}

    start: '{{ 0 }}'
    end: '{{ now() }}'

{% endraw %}

The `/dev-template` page of your home-assistant UI can help you check if the values for `start`, `end` or `duration` are correct. If you want to check if your period is right, just click on your component, the `from` and `to` attributes will show the start and end of the period, nicely formatted.