Route suggestions
The suggestions query of the Data API. Every request is a POST to https://data.mountaya.com/graphql with a publishable key and a session token: see Authentication.
/graphqlGenerate route suggestions matching distance constraints for a given activity. Returns multiple route candidates with elevation data, allowing the client to select based on elevation gain, distance, or shape preference.
Arguments
inputSuggestionsInput!
The constraints a suggested route must satisfy: where it starts and ends, the activity, and the target distance or ascent.
activityActivitySlug!
One of: HIKING_AND_TRAIL, PROFESSIONAL_TRAIL, RUNNING, ROAD_CYCLING, GRAVEL_BIKE, MOUNTAIN_BIKE, BACKCOUNTRY_SKIING, SKI_TOURING, CROSS_COUNTRY_SKIING, SNOWSHOE_WALKING
Activity to use for routing. BACKCOUNTRY_SKIING, GRAVEL_BIKE and MOUNTAIN_BIKE have no routing and are VALIDATION_FAILED at ["input", "activity"].
See ActivitySlug.
ascentFloat
Target elevation gain (ascent) in meters, a finite number, 0 or more (a negative value, NaN or Infinity is VALIDATION_FAILED at ["input", "ascent"]). A positive target ranks fresh candidates by their distance and ascent gaps combined, and drops every fresh candidate whose ascent is more than 50% above or below it, so fewer routes than candidates, or none, can come back with no error. Only a candidate that failed on Mountaya's side adds an error to such an answer (see start for when it is asked for once more, and SuggestionsResult.routes). A pinned seed is kept whatever its ascent. Example: 800.0 for 800 m of climbing.
candidatesInt!
Number of route candidates to generate. Must be between 1 and 10. Each candidate uses a different random seed, producing different route shapes. Example: 3 for three route options.
distanceFloat!
Target total distance for the route in meters, greater than 0 and at most 100 km, the routing engine's own ceiling for a route and for a loop. For a point-to-point route it must also be at least the straight-line distance from start to end. Either refusal is VALIDATION_FAILED at ["input", "distance"]. Example: 20000 for a 20 km route.
end[Float!]
End point as [longitude, latitude] (WGS 84): exactly two numbers, a longitude between -180 and 180 and a latitude between -90 and 90 (VALIDATION_FAILED at ["input", "end"] otherwise). When omitted, the route loops back to the start point. When provided and different from start, generates a point-to-point route shaped to meet the target distance. Example: [6.7113, 45.8929] (Saint-Gervais-les-Bains).
pointsInt
Number of route shaping points (2-10, default 5). Higher values produce rounder, more circular loops. Only applies to loop routes. Example: 5 (default). Higher values (8-10) produce rounder loops.
seedsSuggestionSeedsInput
Optional directives to pin specific seeds into the result (include) and/or avoid specific seeds when generating fresh candidates (exclude). Useful to reproduce previously-returned routes, discover new variations different from ones already seen, or both in one call. See SuggestionSeedsInput for details.
exclude[Int!]
Seeds to exclude from the fresh candidate pool, at most 100 (more is VALIDATION_FAILED at ["input", "seeds", "exclude"]). Any deterministically-generated seed matching a value in this list is skipped, so clients can ask for new variations that differ from ones they have already seen.
include[Int!]
Seeds to pin into the result, in the order provided, each returned as long as it still routes without crossing a hazard. There may be no more of them than candidates, and none may repeat; either refusal is VALIDATION_FAILED at ["input", "seeds", "include"]. Any remaining slots are filled with fresh candidates.
speedFloat
Travel speed in km/h on LEVEL ground, a finite number greater than 0 (anything else, NaN and Infinity included, is VALIDATION_FAILED at ["input", "speed"]). When provided, it replaces the selected activity's default as the flat pace the travel-time model starts from.
start[Float!]!
Starting point as [longitude, latitude] (WGS 84): exactly two numbers, a longitude between -180 and 180 and a latitude between -90 and 90 (VALIDATION_FAILED at ["input", "start"] otherwise). Example: [6.8712, 45.9231] (Chamonix).
Returns
suggestionsSuggestionsResult!
Result of a suggestions query, containing multiple route candidates.
routes[SuggestionRoute!]!
Suggested route candidates: pinned seeds first, in the order given, then fresh candidates nearest the target distance first, or nearest the distance and ascent targets combined when ascent is positive. Can hold fewer routes than candidates.
distanceFloat!
Total route distance in meters, measured as the planimetric great-circle length of the geometry field, with elevation ignored. This is measured from the candidate, so it may differ from the requested target distance.
durationFloat!
Estimated route duration in seconds, computed over the terrain the candidate crosses rather than over its distance, anchored on the requested speed (or the activity default) as the pace on level ground. Integrating analysis.speedInfo over the geometry reproduces this number exactly.
elevationElevationSummary!
Elevation summary including altitude bounds, total gain/loss, and gradient extremes.
altitudeMetricRange!
Altitude range along the route in meters above sea level.
maxFloat!
Upper bound of the range.
minFloat!
Lower bound of the range.
ascentFloat!
Total elevation gain (ascent) in meters.
descentFloat!
Total elevation loss (descent) in meters.
gradientMetricRange!
Gradient range along the route in degrees. Positive values indicate uphill, negative values indicate downhill.
maxFloat!
Upper bound of the range.
minFloat!
Lower bound of the range.
geometryGeoJSON!
GeoJSON geometry representing the route path.
analysisGeometryAnalysis!
Surface and way type analysis for the route geometry. Its advisories raise no flag, because a candidate that crosses a tollway or an access-restricted way is never returned.
elevationElevationSummary!
Elevation summary over the analyzed geometry, including altitude bounds, total elevation gain/loss, and gradient extremes.
altitudeMetricRange!
Altitude range along the route in meters above sea level.
maxFloat!
Upper bound of the range.
minFloat!
Lower bound of the range.
ascentFloat!
Total elevation gain (ascent) in meters.
descentFloat!
Total elevation loss (descent) in meters.
gradientMetricRange!
Gradient range along the route in degrees. Positive values indicate uphill, negative values indicate downhill.
maxFloat!
Upper bound of the range.
minFloat!
Lower bound of the range.
elevations[Float!]!
Elevation in meters above sea level, one value per vertex, in order: per input coordinate for analyzeGeometry, and per vertex of the returned route geometry for directions and suggestions. Lets the client build a 3D version of the line for an elevation profile. A vertex beyond 85.0511 degrees of latitude, north or south, lies past the elevation source's coverage: it reads 0, which is no data rather than an altitude, and is left out of the ascent, descent, altitude, gradient and slope figures, which describe the covered part alone.
slopeInfo[SlopeInfo!]!
Slope angle segments along the geometry in degrees, referencing coordinate indices.
fromIndexInt!
Start index in the coordinates array (inclusive).
toIndexInt!
End index in the coordinates array (inclusive).
valueFloat!
Slope angle in degrees. Positive values indicate uphill, negative values indicate downhill.
speedInfo[SpeedInfo!]!
Resolved travel speed segments along the geometry in km/h, referencing coordinate indices.
fromIndexInt!
Start index in the coordinates array (inclusive).
toIndexInt!
End index in the coordinates array (inclusive).
valueFloat!
Travel speed in km/h over this stretch. Always positive. Slower than the flat pace on a climb, faster on a descent, and reduced further by a coarse surface or a technical trail. Never above the activity's maximum speed, in km/h: 12 for HIKING_AND_TRAIL, 20 for PROFESSIONAL_TRAIL, 22 for RUNNING, 60 for ROAD_CYCLING, 40 for BACKCOUNTRY_SKIING and SKI_TOURING, 30 for CROSS_COUNTRY_SKIING and 8 for SNOWSHOE_WALKING. A stretch at that cap stays there whatever speed asks for.
surfaceInfo[SurfaceInfo!]!
Surface type segments along the geometry, referencing coordinate indices. analyzeGeometry covers a stretch it has no data for, or one the routing engine failed on (which errors then flags), with one UNKNOWN segment. Empty for the activities that carry no surface, way type or trail difficulty analysis: the four winter activities (BACKCOUNTRY_SKIING, SKI_TOURING, CROSS_COUNTRY_SKIING and SNOWSHOE_WALKING).
fromIndexInt!
Start index in the coordinates array (inclusive).
toIndexInt!
End index in the coordinates array (inclusive).
valueSurfaceType!
One of: UNKNOWN, PAVED, UNPAVED, ASPHALT, CONCRETE, COBBLESTONE, METAL, WOOD, COMPACTED_GRAVEL, FINE_GRAVEL, GRAVEL, DIRT, GROUND, ICE, PAVING_STONES, SAND, WOODCHIPS, GRASS, GRASS_PAVER
Surface type for this coordinate range.
See SurfaceType.
trailDifficultyInfo[TrailDifficultyInfo!]!
Trail difficulty segments along the geometry, referencing coordinate indices. Graded on the SAC hiking scale for walking activities and the mountain-biking scale for cycling ones. analyzeGeometry covers a stretch it has no data for, or one the routing engine failed on (which errors then flags), with one UNKNOWN segment. Empty for the activities with no analysis (see surfaceInfo), and on a route whose routing graph carries no trail-difficulty data.
fromIndexInt!
Start index in the coordinates array (inclusive).
toIndexInt!
End index in the coordinates array (inclusive).
valueTrailDifficultyType!
One of: UNKNOWN, HIKING, MOUNTAIN_HIKING, DEMANDING_MOUNTAIN_HIKING, ALPINE_HIKING, DEMANDING_ALPINE_HIKING, DIFFICULT_ALPINE_HIKING, MTB_0, MTB_1, MTB_2, MTB_3, MTB_4, MTB_5, MTB_6
Trail difficulty for this coordinate range, on the scale matching the activity.
See TrailDifficultyType.
wayTypeInfo[WayTypeInfo!]!
Way type segments along the geometry, referencing coordinate indices. analyzeGeometry covers a stretch it has no data for, or one the routing engine failed on (which errors then flags), with one UNKNOWN segment. Empty for the activities with no analysis (see surfaceInfo).
fromIndexInt!
Start index in the coordinates array (inclusive).
toIndexInt!
End index in the coordinates array (inclusive).
valueWayType!
One of: UNKNOWN, STATE_ROAD, ROAD, STREET, PATH, TRACK, CYCLEWAY, FOOTWAY, STEPS, FERRY, CONSTRUCTION
Way type for this coordinate range.
See WayType.
advisoriesRouteAdvisories!
Route-level hazards the analyzed geometry crosses: tollways and access-restricted ways. For analyzeGeometry this is the union over the whole geometry, so a hazard anywhere along it raises the flag. Both flags are false and both lists empty for the activities with no analysis (see surfaceInfo) under analyzeGeometry, and when the activity cannot be routed at all.
tollwayBoolean!
True when the route crosses at least one way that charges a toll for the activity's mode of travel.
restrictedAccessBoolean!
True when the route crosses at least one way carrying a genuine access restriction. PERMISSIVE grants access rather than restricting it, and AGRICULTURAL and FORESTRY are ordinary terrain on foot, so none of the three raises this flag where the routing engine returns per-stretch access data. Where it returns none, the flag follows the engine's route-level warning, which any access tag raises, those three included.
tollwayInfo[TollwayInfo!]!
The stretches that cross a tollway, referencing coordinate indices, and only those. Empty when there are none, or when the engine returned no per-stretch toll data (read tollway then).
fromIndexInt!
Start index in the coordinates array (inclusive).
toIndexInt!
End index in the coordinates array (inclusive).
valueTollwayType!
One of: NONE, TOLLWAY
Whether this coordinate range crosses a tollway for the activity's mode of travel.
See TollwayType.
roadAccessInfo[RoadAccessRestrictionInfo!]!
The stretches that carry an access tag, referencing coordinate indices, and only those. PERMISSIVE, AGRICULTURAL and FORESTRY stretches are listed too, as information. Empty when there are none, or when the engine returned no per-stretch access data (read restrictedAccess then).
fromIndexInt!
Start index in the coordinates array (inclusive).
toIndexInt!
End index in the coordinates array (inclusive).
values[RoadAccessRestrictionType!]!
One of: NO, CUSTOMERS, DESTINATION, DELIVERY, PRIVATE, PERMISSIVE, PERMIT, RESTRICTED, UNKNOWN, SERVICE, AGRICULTURAL, FORESTRY
Every access restriction tagged on this coordinate range, for the activity's mode of travel. A way can carry several at once. Never empty: a range with no restriction is not reported at all.
summaryString!
Human-readable route summary. Example: "20.1 km, ~5h30m, +850m / -850m elevation, 45% path, 38% track."
steps[DirectionsStep!]!
Turn-by-turn direction steps along this candidate, in travel order.
fromIndexInt!
Start index in the route coordinates array (inclusive).
toIndexInt!
End index in the route coordinates array (inclusive).
typeManeuverType!
One of: TURN_LEFT, TURN_RIGHT, SHARP_LEFT, SHARP_RIGHT, SLIGHT_LEFT, SLIGHT_RIGHT, CONTINUE, ENTER_ROUNDABOUT, EXIT_ROUNDABOUT, UTURN, GOAL, DEPART, KEEP_LEFT, KEEP_RIGHT, UNKNOWN
Maneuver to perform at the start of this step.
See ManeuverType.
nameString!
Name of the way/street for this step. May be empty or "-" when unnamed.
distanceFloat!
Length of this step in meters: the routing engine's figure for the step, rescaled by the factor that takes the engine's own route length to the route's measured distance.
durationFloat!
Estimated duration of this step in seconds, from the same travel-time model as the route's duration, over the step's stretch of the geometry.
exitNumberInt
For a roundabout maneuver, the 1-based exit to take. Null for any other maneuver, matching exit_number on the REST resource, which is nullable for the same reason.
seedInt!
Seed value used to generate this route candidate. Pass this seed back in SuggestionsInput.seeds.include to pin this route into a future result, or in .exclude to filter it out of the fresh candidate pool. Reproducing a route also requires passing the same start/end/distance/points as the original request. Mismatched inputs will produce a different route even with the same seed.
Errors A field the API refuses is answered 200, its entry in errors beside the data that resolved. See Errors.
curl https://data.mountaya.com/graphql \
-H "X-API-Key: pk_your_publishable_key" \
-H "X-Session-Token: sess_your_session_token" \
-H "Content-Type: application/json" \
-d '{
"query": "query Suggestions($input: SuggestionsInput!) { suggestions(input: $input) { routes { distance duration seed } } }",
"variables": {
"input": {
"activity": "HIKING_AND_TRAIL",
"candidates": 2,
"distance": 12000,
"start": [6.8712, 45.9231]
}
}
}'