Geocoding and map matching

Fahrtenbuch uses external services for three things. All of them are set up under Administration › Geocoding and can be switched on individually:

Module	Used for	Without it
Address search (Photon)	Start and destination addresses of trips, address suggestions, home location	No automatic addresses, search hidden; the home location falls back to coordinates.
Map matching / routing (Valhalla, OSRM)	Snapping trips to the road network, road filling in the trip editor, Calculate distance for manual trips	Distance from the GPS points, gaps as straight lines.
Dawarich Atlas	Bundles Photon and Valhalla in one self-hosted installation	–

Dawarich Atlas

Dawarich Atlas bundles Photon (address search) and Valhalla (routing) for your own regions. Enter the Atlas server address (base URL without /api/v1; it only needs to be reachable from the Fahrtenbuch backend) and a timeout, then Save Atlas.

When Atlas is active, address search and map matching below can each be set to Via Dawarich Atlas. The system check shows Atlas' capabilities (geocoding, routing, POIs, public transport); routing that is still being built is reported as starting.

Address search (Photon)

Option	Description
Disabled	No automatic addresses, address search hidden.
Public server	photon.komoot.io – no own infrastructure needed. Start and destination coordinates are sent to that server.
Own Photon server	Your own address, e.g. http://192.168.1.12:2322 (base URL with protocol and port, without /api).
Via Dawarich Atlas	Uses the Photon passthrough of Atlas.

Map matching

Option	Description
Disabled	Distance from the GPS points, gaps as straight lines.
Own Valhalla server	Your own address, default port 8002.
Own OSRM server	Your own address, e.g. http://192.168.1.10:5000.
Via Dawarich Atlas	Uses the Valhalla map matching of Atlas.

Each section has Test connection. The system check at the top tests all saved modules and shows each as available, starting, unreachable, incomplete or inactive.

How map matching works

• Users switch automatic matching on or off in their profile. When it is on, every uploaded trip is matched after it is completed.
• Long trips are matched in sections of at most 100 km; GPS outliers are removed beforehand.
• Each matched section is checked against the GPS track. If the service leaves out the start or end of a trip (for example because it has no map data abroad), the GPS track fills the gap; sections with detours away from the track keep the GPS track. A section that cannot be matched at all no longer fails the whole trip.
• The road route is only applied when it is plausible. The raw GPS points always stay unchanged, and trips in closed periods are skipped.

Make sure your routing service covers the regions your users drive in. Trips outside its coverage keep their GPS route.

Background jobs

Administration › Background jobs shows the Redis queues (pending, processing, delayed, failed) and lets you retry or remove failed jobs.

• Map matching: start a run for only trips not matched yet, retry rejected and failed trips or re-match all trips. The counters show open, applied, rejected and failed trips; show reasons lists the trips that were not applied, with the reason.
• Photon reverse geocoding: queue address lookups for completed trips – only trips with missing addresses, or all trips (existing addresses are preserved); up to 500 per run.
• Redis Insight: link to the bundled Redis Insight with the Redis connection preconfigured. It has no login of its own and listens on 127.0.0.1:5540 by default; set REDIS_INSIGHT_URL if you publish it behind a reverse proxy with authentication.

After an update

After updates that improve map matching, run Re-match all trips once so existing trips are checked again.