Routing

PickPoint's Routing API is built on Valhalla - an open-source C++ routing engine originally created by Mapzen, now running in production at Mapbox, Mapillary, and Tesla. It finds turn-by-turn routes for cars, trucks, bicycles, pedestrians, and more, respecting access rules, turn restrictions, and height limits across international borders.

The engine uses a hierarchical road graph, bidirectional A* search, and tile-based memory management to return country-scale routes in milliseconds. For a deep dive into how that works, see Routing: Under the Hood.

Costing models

Every route request requires a costing parameter that selects the travel mode. Each model applies a different set of rules and preferences to the road graph:

`auto`	Driving - obeys car access and turn restrictions, favors highways.
`truck`	Driving with width, height, and weight restrictions.
`bus`	Driving that checks for bus-lane access.
`taxi`	Driving that checks for taxi-lane access.
`motorcycle`	Two-wheeled motor travel, tunable between touring and off-road.
`motor_scooter`	Moped/scooter - avoids higher-class roads by default.
`bicycle`	Slight preference for cycleways; avoids roads without bicycle access.
`pedestrian`	Shortest walking - favors footpaths, avoids stairs where possible.
`bikeshare`	Pedestrian + bicycle, switching at a bike-share station.
`multimodal`	Pedestrian + public transit - walking legs connected by scheduled rides.

Fine-tuning with costing_options

Beyond picking a costing model, costing_options lets you adjust its behaviour. Three types of options exist:

Cost - seconds added to both route cost and time estimate (things that genuinely take time: gates, border crossings).
Penalty - seconds added only to cost, not the time estimate. Use to steer the route away from something without lying about duration - toll avoidance is the classic case.
Factor - a multiplier on edge cost (0.1–100000). Below 1.0 favours that road type, above 1.0 avoids it.

Example: a truck route that avoids tolls and prefers local roads:

{
  "locations": [
    { "lat": 52.5200, "lon": 13.4050 },
    { "lat": 48.1351, "lon": 11.5820 }
  ],
  "costing": "truck",
  "costing_options": {
    "truck": {
      "use_highways": 0.2,
      "use_tolls":    0.0,
      "toll_booth_penalty":       600,
      "country_crossing_penalty": 300
    }
  }
}

Turn-by-turn directions

The response includes a maneuvers array - one entry per instruction: turn type, street name, distance, and a human-readable narrative. Each maneuver also includes a verbal cue formatted for text-to-speech, suitable for navigation apps.

Optimized Route: best stop order

Given N locations, Optimized Route finds the visiting sequence that minimises total travel. It computes a full cost matrix between every pair of locations, solves a Travelling Salesman-style optimisation, then runs the same routing algorithm over the result to produce actual turn-by-turn directions.

Practical use: a delivery run with a dozen drop-off points - instead of visiting them in input order, PickPoint works out the shortest loop.

Input order: visited 1→2→3→4→5 as given - path crosses itself, longer overallOptimized order: same 5 stops, re-sequenced by cost - no crossings, shortest loop

POST /v2/route/optimized
{
  "locations": [
    { "lat": 52.52, "lon": 13.40 },
    { "lat": 48.85, "lon":  2.35 },
    { "lat": 51.50, "lon": -0.12 },
    { "lat": 40.71, "lon":-74.00 }
  ],
  "costing": "auto"
}

Locate: snap a coordinate to the road network

Locate exposes the first step of every routing request on its own: given a coordinate, which graph edge or intersection does it correspond to? Returns the matched node or edge, which side of the street, and how far along the edge the point falls. Useful for debugging why a route enters or leaves a road the way it does.

GET /v2/locate?json={"locations":[{"lat":52.52,"lon":13.40}],"costing":"auto"}

API Reference ↗Under the Hood Device Tracking