Calculate distance: distance

The distance template function calculates the distance in kilometers between two locations. If you only provide one location, it calculates the distance from your home to that point. Locations can be specified as entityAn 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] IDs (for entities with GPS coordinates), zoneZones allow you to specify certain regions on a map. They enable zone presence-detection and can be used in automations. For example, to start the vacuum after you left home or start the heating at home when you leave the office. [Learn more] names, or latitude/longitude pairs.

This is useful for proximity-based automationsAutomations in Home Assistant allow you to automatically respond to things that happen in and around your home. [Learn more]. You could send a notificationYou can use notifications to send messages, pictures, and more, to devices. [Learn more] when someone is within a certain distance of home, calculate driving distances between family members, or determine how far away an entity is from a specific zone. The result is a number in kilometers that you can use in conditionsConditions are an optional part of an automation that will prevent an action from firing if they are not met. [Learn more] and comparisons.

Usage

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

{{ distance("device_tracker.phone") }}

5.2

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.

distance(
    *args: str | State | float,
) -> float | None

Function parameters

The following parameters can be provided to this function.

Good to know

• Returns None when any location lacks GPS coordinates, so guard your comparisons for missing data.
• The result is always in kilometers, regardless of the unit system configured in Home Assistant.
• With a single location argument, distance is measured from your Home Assistant home location.

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.

Distance from home

Calculate how far a device tracker is from home.

{{ distance("device_tracker.phone") | round(1) }}

5.2

Distance between two entities

Calculate the distance between two people.

{{
  distance("device_tracker.phone_a",
  "device_tracker.phone_b") | round(1)
}}

12.7

Distance using coordinates

Calculate the distance from home to a specific latitude/longitude.

{{ distance(52.5, 13.4) | round(1) }}

847.3

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:

• Find closest entity: closest - Finds the entity closest to a given location, home, or another entity.

• Get entity state: states - Returns the state value of an entity, or lets you iterate over all entity states.