Parse duration string: as_timedelta

The as_timedelta template function parses an ISO 8601 duration string and returns a Python timedelta object. Give it a string like “PT1H30M” (1 hour and 30 minutes) or “P2DT6H” (2 days and 6 hours), and it returns a timedelta you can use in time calculations.

Some integrationsIntegrations connect and integrate Home Assistant with your devices, services, and more. [Learn more] and external services provide durations in ISO 8601 format. To use these values in calculations, such as adding a duration to the current time or comparing how long something will take, you need to convert them into timedelta objects first. as_timedelta does this for you. If you need to create a timedelta from numeric values (days, hours, minutes) rather than parsing a string, use timedelta instead.

Usage

Here’s how to use this template function. Copy any example and adjust it to your setup.

{{ as_timedelta("PT1H30M") }}

1:30:00

{{ "PT1H30M" | as_timedelta }}

1:30:00

Function signature

The signature is a technical summary of this template function. It shows the name of the function, the values (called parameters) it accepts, and what type of data each parameter expects (for example, a piece of text or a number).

Function parameters that have a = with a value after them are optional. If you leave them out, the default value shown is used automatically. Function parameters without a default are required.

as_timedelta(
    value: str,
) -> timedelta | None

Function parameters

The following parameters can be provided to this function.

ISO 8601 duration format

The ISO 8601 duration format uses P as a prefix, followed by date components and T to separate time components:

• P1D - 1 day
• PT1H - 1 hour
• PT30M - 30 minutes
• PT45S - 45 seconds
• P2DT6H30M - 2 days, 6 hours, 30 minutes

{{ as_timedelta("P2DT6H30M") }}

2 days, 6:30:00

Good to know

• Returns None when the string cannot be parsed, so guard against missing data before arithmetic.
• Only the ISO 8601 duration format is accepted. A plain string like "1h30m" will not work. For numeric inputs, use timedelta.
• Year and month components (Y, M before T) are not supported because their length in seconds is not fixed.

Try it yourself

Ready to test this? Open Developer tools > Template, paste the example into the Template editor, and watch the result update on the right. Edit the values to see how the function adapts to your own entitiesAn entity represents a sensor, actor, or function in Home Assistant. Entities are used to monitor physical properties or to control other entities. An entity is usually part of a device or a service. [Learn more].

More examples

Real scenarios where this function comes up in automations and templates. Copy any example and adapt it to your setup.

Add a duration to the current time

Calculate when an event will end by adding a duration from a sensor to now.

{{ now() + as_timedelta("PT2H30M") }}

2024-03-15 17:00:00.123456+01:00

Get total seconds from a duration

Convert an ISO 8601 duration string to a total number of seconds for use in numeric comparisons.

{{ as_timedelta("PT1H30M").total_seconds() | int }}

5400

Check if a remaining duration is short

Determine whether a timer or countdown is about to finish by comparing the duration to a threshold.

{{
  as_timedelta(states("sensor.washer_remaining"))
  < as_timedelta("PT10M")
}}

true

Still stuck?

The Home Assistant community is quick to help: join Discord for real-time chat, post on the community forum with your template and expected result, or share on our subreddit /r/homeassistant.

Related template functions

These functions work well alongside this one:

• Create a time duration: timedelta - Creates a timedelta object from numeric time components.

• Current local date and time: now - Returns the current date and time in your local time zone.

• Convert to datetime: as_datetime - Converts a string or timestamp to a datetime object.

• Convert to UNIX timestamp: as_timestamp - Converts a datetime object or string to a UNIX timestamp.