Snap-to-roads (Mapbox map matching)

When a trip ends, segments classified as driving, cycling, or public transport are passed through the Mapbox Map Matching API. Their raw GPS is replaced with a snapped polyline that follows the actual road network — no more squiggly lines floating off the highway.

What changes visually

Before snap (raw GPS):

  • Polyline weaves across both lanes of a freeway.
  • Cuts through buildings at intersections.
  • Drifts to GPS noise (~5–15 m at urban speed).

After snap (matched):

  • Polyline follows the actual road centerline.
  • Turns are sharp at intersections, not GPS-jittered curves.
  • Tunnel and bridge sections that lost GPS are reconstructed along the road network's geometry.

Which segments get snapped

Only modes where snap-to-road makes sense:

  • Driving — yes
  • Cycling — yes (on roads / bike paths the road network knows about)
  • Public transport — yes (often follows a road or rail route)
  • Walking — no (walks happen on sidewalks, trails, and shortcuts the road network doesn't model — snap-to-road would pull the route off the actual path).
  • Running — no (same reason).
  • Horse / boat / flying — no.

When it runs

Three triggers:

  1. Trip auto-stop. When the auto-trigger ends a trip, the snap fires automatically.
  2. Manual "Snap now" in the trip detail. Useful if you re-classified a segment as driving after the snap already ran.
  3. Re-snap. Any time you edit the segment classification, the snap updates.

Why only on completed trips, not on live data

This is intentional, and a little against the grain — most tracking apps will silently "tidy up" your live position to the nearest road in real time. We don't, and here's why.

Snap-to-roads is opinionated, and the opinion is sometimes wrong. The road-matching engine assumes you're on a known road. Most of the time, that's right. But:

  • A hike on an unmapped forest path gets pulled to the nearest road, kilometres away.
  • A boat on a lake gets snapped to the nearest shoreline road.
  • A walk along a beach, a backcountry ski tour, a horse ride across a field, a paraglider landing — all of these are real movements that simply aren't on a road graph.
  • Even on roads, brand-new construction or recently rerouted one-ways may not be in the map yet, and snap will pull the trace to a parallel old road.

For driving in a city or on a highway, snap is almost always better than raw GPS — sharp turns at intersections, no GPS jitter across both lanes, gaps in tunnels and bridges reconstructed along the road. For walking, running, horse riding, boating, and most off-road movement, raw GPS is the truth and snap would be a confident-sounding lie.

So the rule is: you decide. After a trip ends, you can look at the route on the map, see whether snap would help or hurt, and click the Snap to roads button if it would help. If your trip was a hike along a coastline or a paddle on a river, you just leave it raw and the polyline shows what your phone actually recorded.

Live tracking always shows raw GPS. There's no behind-the-scenes polishing of your current position toward a road that may or may not be the road you're actually on.

If you want to see what your live data would look like road-snapped without having a real trip, the easiest workaround is to create a short throwaway trip covering the time window you care about, snap it, look at the result, and delete the trip again — the underlying GPS data stays in your live view unchanged.

API quota

Each snap call counts against your plan's match_requests_monthly quota:

Plan Snaps per month
Light 10
Traveler 50
Nomad 100

Snaps reset on the 1st of each calendar month. Hitting the limit doesn't break anything — the raw GPS keeps showing on the map until next month's quota refills.

The Mapbox API is paid; the quota is what we charge for. Going over isn't optional fail — your trip just shows raw GPS.

How it works internally

  1. The trip's GPS points are filtered to driving / cycling / PT segments.
  2. Points are sampled to ~50 per Mapbox API call (the API caps at 100; we leave headroom for retry).
  3. Each batch is POSTed to Mapbox Map Matching with geometries=geojson and tidy=true.
  4. The matched LineString replaces the raw polyline for that segment in route_matched.json.
  5. The public map prefers the matched polyline if present, falling back to the raw GPS otherwise.

What can go wrong

  • Off-road driving — Mapbox can't match driving on a 4×4 trail. The snap might pull your route to the nearest road (kilometres away). For these segments, manually re-classify to walking and the snap is skipped.
  • Brand-new roads — Mapbox's road graph updates monthly. A road built last week might not be in the graph yet; snap might fall to a parallel older road. Re-snap next month.
  • GPS gaps over bridges / tunnels — Mapbox uses straight-line interpolation across gaps. Usually fine; in a corkscrew underground tunnel it can show a too-direct line.

Need help? Contact support · Where Is Tereza?