Valhalla Map Match for Home Assistant

This is a custom integration for Home Assistant that adds a service action to match a device tracker's coordinate history to roads and paths that have been mapped in OpenStreetMap using Valhalla.

You could, for example, use it to more accurately estimate the distance travelled at the end of a journey or to identify the road and heading when a vehicle enters a zone.

Caution

This project includes code produced with a "generative AI". This is documented here for transparency.

License

This project uses the MIT license. It is not part of the Valhalla organisation. The Valhalla logo, used as the 'brand' image for this integration, is by Jordan.

Valhalla uses data from several different open data sets, include OpenStreetMap data licensed under the ODbL.

Demo Valhalla server

FOSSGIS e.V. hosts a demo Valhalla server open to the public. Usage of the demo server follows the usual fair-usage policy as OSRM & Nominatim demo servers.

Warning

Don't hammer this public demo server. You probably don't need an automation that runs map-matching every time your device tracker updates.

To use this demo server in this integration, enter the following connection details:

Option	Value
Hostname	valhalla1.openstreetmap.de
Port	443
Use SSL/HTTPS	✔

Example action call and response

The data behind this example was generated by a mobile phone using the Home Assistant companion app.

action: valhalla_map_match.map_match
data:
  costing: auto
  entity_id: device_tracker.my_car
  attributes:
    - shape
    - edge.names
    - edge.end_heading
    - edge.roundabout
    - edge.tunnel
    - edge.bridge
    - matched.point
  # https://valhalla.github.io/valhalla/api/map-matching/api-reference/#attribute-filters-trace_attributes-only
  timestamp: "2026-05-30 09:45:00"
  time_window: 2 # minutes
  max_points: 6

edges:
  - roundabout: false
    bridge: false
    tunnel: false
    end_heading: 256
    names:
      - M4
      - E 30
  - roundabout: false
    bridge: false
    tunnel: true
    end_heading: 257
    names:
      - M4
      - E 30
      - Brynglas Tunnel
  - roundabout: false
    bridge: false
    tunnel: false
    end_heading: 250
    names:
      - M4
      - E 30
  # ...
  - roundabout: false
    bridge: true
    tunnel: false
    end_heading: 235
    names:
      - M4
      - E 30
matched_points:
  - lon: -2.992801
    lat: 51.603951
  - lon: -3.000188
    lat: 51.602845
  - lon: -3.007784
    lat: 51.599479
# Shape encoded as a polyline
shape: >-
  }}slaB`ituD`LnqAxk@b{HxHdw@rBnPvAfKbApHxFr^rCdN|DpQxF~QbOjb@lLzZtQdd@d_Al~Bzr@hfBxIdU~@pC
entity_id: device_tracker.my_car
costing: auto
shape_point_count: 3

View the shape produced in this example here.