Routing

The routing queries: directions between waypoints, suggestions shaped to a target distance, isochrones for reachable area, and matrix for travel-time and distance grids. Every routing query takes an activity that selects a routing profile tuned to its terrain and movement style.

Each activity routes on a profile tuned to its terrain and movement style. Directions availability varies: most activities support turn-by-turn routing, backcountry skiing is freehand-line only, and cycling activities are not yet available for routing. The GraphQL ActivitySlug enum uses the uppercase value; the Map Studio and Tile APIs use the lowercase, underscore-free wire form.

All coordinates are [longitude, latitude] in WGS 84. Distances are in meters, durations in seconds, elevations in meters above sea level, and gradients in degrees.

How activities route

Each activity selects a routing profile tuned to its terrain, together with a preference and a waypoint snapping tolerance:

• Preference. Most activities use balanced routing that favors pleasant, terrain-appropriate ways. Running and road cycling favor the fastest way. Professional trail takes the most-direct line, with no scenic bias.
• Waypoint snapping. A waypoint must lie within a snapping distance of a routable way, or the query is rejected. Most activities use the standard ~400 m tolerance; snowshoe walking relaxes it to a few kilometers for off-trail points; ski touring and professional trail remove the limit entirely, snapping each waypoint to the nearest way at any distance, so routes can start or end far off-network.
• Default speed. Each activity has a default speed used to estimate duration (for example ~4.5 km/h hiking, ~8 km/h professional trail, ~25 km/h road cycling). Override it per request with speed.

Backcountry skiing is freehand-only: it has no routing profile, so directions, suggestions, isochrones, and matrix are not available for it. Cycling activities (gravel, mountain, road) are not yet available for routing.

directions

Compute a route between an ordered list of waypoints for a given activity. Returns one or more routes with distance, duration, elevation, geometry, and a surface and way type analysis.

Input

directions(input: DirectionsInput!)

Example

query Directions($input: DirectionsInput!) {
  directions(input: $input) {
    routes {
      distance
      duration
      summary
      geometry
      elevation {
        ascent
        descent
        altitude {
          min
          max
        }
        gradient {
          min
          max
        }
      }
      analysis {
        surfaceInfo {
          fromIndex
          toIndex
          value
        }
      }
    }
  }
}

Response

DirectionsResult.routes is a list of DirectionsRoute. Each route carries:

Run this query live: open it in the playground and try it against the schema.

Hazards and avoidance

Some ways carry a toll, and some carry an access restriction — private, destination-only, customers, delivery, permit, or forbidden outright. Every routed result reports what it crosses on analysis.advisories:

suggestions never proposes a route through either. There is no avoid input and no opt-out: when no hazard-free candidate can be generated from the given points, the query fails with a validation error rather than returning one that crosses something. Proposing somewhere to go is a different act from a user deliberately routing across a private track.

directions can return one, because sometimes that is exactly what the user wants — a right of way they hold, a toll they will pay. It is the only query that does, so read advisories before you present the result. Pass avoid to route around them, and read avoidance to learn what happened:

suggestions

Generate route candidates that match a target distance for a given activity. Each candidate uses a different seed, producing a different route shape, so a client can offer the user several options ranked by proximity to the target.

No candidate crosses a tollway or an access-restricted way — see hazards and avoidance.

Input

suggestions(input: SuggestionsInput!)

Example

query Suggestions($input: SuggestionsInput!) {
  suggestions(input: $input) {
    routes {
      distance
      duration
      summary
      seed
      elevation {
        ascent
        descent
      }
      geometry
    }
  }
}

Response

SuggestionsResult.routes is a list of SuggestionRoute, sorted by proximity to the target distance. Each carries the same distance, duration, elevation, geometry, analysis, and summary as a directions route, plus:

isochrones

Compute reachability polygons from one or more origins for a given activity. Each range value yields one isochrone, so several ranges produce concentric polygons.

Input

isochrones(input: IsochronesInput!)

Example

query Isochrones($input: IsochronesInput!) {
  isochrones(input: $input) {
    isochrones {
      value
      area
      reachFactor
      center
      geometry
    }
  }
}

Response

IsochronesResult.isochrones is a list of Isochrone, one per range value:

matrix

Compute a grid of travel durations and/or distances between locations for a given activity. Limit the grid to specific origins or destinations with the sources and destinations index lists.

Input

matrix(input: MatrixInput!)

Example

query Matrix($input: MatrixInput!) {
  matrix(input: $input) {
    durations
    distances
  }
}

Response

MatrixResult carries a grid per requested metric. Each grid is a row-per-source array of values, with inner null entries marking unreachable pairs:

Next steps