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.

Activity	API value	Wire form
Hiking and trail running	`HIKING_AND_TRAIL`	`hikingandtrail`
Running	`RUNNING`	`running`
Backcountry skiing	`BACKCOUNTRY_SKIING`	`backcountryskiing`
Ski touring	`SKI_TOURING`	`skitouring`
Cross-country skiing	`CROSS_COUNTRY_SKIING`	`crosscountryskiing`
Snowshoe walking	`SNOWSHOE_WALKING`	`snowshoewalking`
Gravel biking	`GRAVEL_BIKE`	`gravelbike`
Mountain biking	`MOUNTAIN_BIKE`	`mountainbike`
Road cycling	`ROAD_CYCLING`	`roadcycling`

Each activity routes on a profile tuned to its terrain and movement style. The GraphQL ActivitySlug enum uses the uppercase value; the Tile and REST 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.

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!)

activity

ActivitySlug!

required

Activity to use for routing. Selects the routing profile and default speed.

waypoints

[[Float!]!]!

required

Ordered list of waypoints as [longitude, latitude] pairs. At least two are required.

speed

Float

Travel speed in km/h. Overrides the activity's default speed and adjusts the estimated duration.

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:

distance

Float!

Total route distance in meters.

duration

Float!

Estimated route duration in seconds.

elevation

ElevationSummary!

Altitude bounds, total ascent and descent, and the gradient range in degrees.

geometry

GeoJSON!

Route path as a GeoJSON LineString. Coordinates are [longitude, latitude, altitude].

analysis

GeometryAnalysis!

Surface, way type, and slope segments along the route. See analysis.

summary

String!

Human-readable one-line summary, for example 15.2 km, ~4h12m, +720m / -430m elevation, 62% unpaved.

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

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.

Input

suggestions(input: SuggestionsInput!)

activity

ActivitySlug!

required

Activity to use for routing.

start

[Float!]!

required

Starting point as [longitude, latitude].

distance

Float!

required

Target total distance for the route in meters.

candidates

Int!

required

Number of candidates to generate (1 to 10). Each uses a different random seed.

ascent

Float

Target elevation gain in meters. When set, candidates are also ranked by proximity to this value.

end

[Float!]

End point as [longitude, latitude]. Omit to loop back to start; provide a different point for a point-to-point route shaped to the target distance.

points

Int

default: 5

Number of shaping points (2 to 10). Higher values produce rounder loops. Only applies to loop routes.

speed

Float

Travel speed in km/h, overriding the activity default.

seeds

SuggestionSeeds

Pin specific seeds into the result (include) and avoid others in the fresh candidate pool (exclude). Useful to reproduce or vary previously returned routes. A seed in both lists is a validation error.

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:

seed

Int!

The seed used to generate this candidate. Pass it back in seeds.include to reproduce the route or seeds.exclude to filter it out of fresh candidates. Reproducing a route also requires the same start, end, distance, and points.

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!)

activity

ActivitySlug!

required

Activity to use for routing.

locations

[[Float!]!]!

required

Origin points as [longitude, latitude] pairs.

range

[Float!]!

required

Range values, in seconds for TIME or meters for DISTANCE. Multiple values produce concentric isochrones.

rangeType

IsochronesRangeType!

required

Whether range is expressed in TIME (seconds) or DISTANCE (meters).

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:

value

Float!

Range value in seconds or meters, matching the input range type.

area

Float

Area of the polygon in square meters.

reachfactor

Float

Ratio of the isochrone area to the theoretical area (0 to 1).

center

[Float!]!

Center point as [longitude, latitude].

geometry

GeoJSON!

Polygon geometry of the isochrone.

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!)

activity

ActivitySlug!

required

Activity to use for routing.

locations

[[Float!]!]!

required

Locations as [longitude, latitude] pairs.

metrics

[MatrixMetric!]!

required

Metrics to compute. At least one of DISTANCE (meters) or DURATION (seconds).

sources

[Int!]

Indices of locations to use as sources. When omitted, all locations are used.

destinations

[Int!]

Indices of locations to use as destinations. When omitted, all locations are used.

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:

durations

[[Float]!]

Duration grid in seconds. Present only when the DURATION metric was requested.

distances

[[Float]!]

Distance grid in meters. Present only when the DISTANCE metric was requested.

Next steps

Places

Geocode places, reverse-geocode coordinates, list POIs, and search.

Analysis

Classify the surface, way type, and slope of any geometry.