Itineraries

Two queries reach the itineraries your credential can already see. itinerary reads one in full; exportItinerary prepares it as a downloadable route file. Neither writes anything — the Data API only reads, and creating or editing an itinerary goes through the Map Studio API.

Access follows the same three-tier visibility model as everything else. A private itinerary is readable by the active members of the organization that owns it — and a personal itinerary, one owned by no organization, by its author alone; a public one ("anyone with the link") is readable by id across organizations. An itinerary that exists but is not visible to you answers forbidden; not found means no itinerary carries that id.

itinerary

Read one itinerary with its ordered segments, waypoints, and segment groups. This is the companion to the itineraries target of search, which returns references only.

Input

itinerary(input: ItineraryInput!)

id

ID!

required

Identifier of the itinerary to read. The only input: the whole itinerary comes back, with no windowing to declare.

Example

query Itinerary($input: ItineraryInput!) {
  itinerary(input: $input) {
    name
    activitySlug
    distance
    ascent
    segmentCount
    groups {
      id
      name
      color
    }
    segments {
      id
      name
      position
      groupId
      distance
      ascent
      altitude {
        min
        max
      }
      geometry
    }
    waypoints {
      name
      position
      point
    }
  }
}

Response

name, description, activitySlug

String / ActivitySlug

The itinerary's own identity. description and activitySlug are null when none is stored.

distance, ascent

Float / Int

Totals across every segment, in meters. Null when no segment contributes a value, which includes an itinerary with no segments yet.

isPrivate, organizationId

Boolean! / ID!

Which visibility tier the itinerary sits in, and which organization owns it.

segments

[ItinerarySegment!]!

The ordered chain, each with its position, its metrics (distance, duration, ascent, descent, altitude, gradient), and its GeoJSON geometry. A segment that has not been computed carries null metrics; one with no geometry yet carries a null geometry.

waypoints

[ItineraryWaypoint!]!

Named points along the itinerary, in order, each with its point as [longitude, latitude].

groups

[ItinerarySegmentGroup!]!

Segment groups, oldest first. Empty when the itinerary has none.

segmentCount, waypointCount, groupCount

Int!

Counts of each list, so a client can size a response without walking it.

Groups are flat, not nested

A group renames and recolours a contiguous run of segments so it reads as one leg ("Day 1"), and optionally overrides the speed used for its duration. It changes nothing about its members. Membership is carried on each segment's groupId rather than nested inside the group, so the ordered segment chain stays the itinerary's primary structure; resolve a run by matching ids.

Feed a segment's geometry straight to terrainProfile or analyzeGeometry to answer questions about the ground a saved route actually covers.

exportItinerary

Prepare a download of one of your itineraries as a route file.

Input

exportItinerary(input: ExportItineraryInput!)

id

ID!

required

Identifier of the itinerary to export. It must be one you can already read; nothing here widens access.

format

ExportFormat!

required

GPX, KML, KMZ, GEOJSON, CSV, FIT, or TCX.

variant

ExportVariant

default: COURSE

COURSE for a planned route a device navigates turn by turn, ACTIVITY for the same geometry as a completed workout with synthesized timestamps. Applies to FIT and TCX only; every other format ignores it.

Example

query ExportItinerary($input: ExportItineraryInput!) {
  exportItinerary(input: $input) {
    url
    filename
    format
    expiresAt
  }
}

Response

The query returns a signed URL, not the file. A GPX or FIT payload is of no use inlined into a GraphQL response, and a URL can be handed straight to a user or fetched by a client that wants the bytes.

url

String!

The signed download URL. It needs no further authentication and may be fetched once or many times inside its window.

filename

String!

Suggested file name including the extension, for example tour-du-mont-blanc.gpx.

format

ExportFormat!

The format the download is encoded in, echoed from the request.

expiresAt

String!

When the URL stops working, as an RFC 3339 timestamp. This is the authority on the window; do not assume a duration.

Treat the URL as a credential

It carries no authentication of its own, so anyone holding it can fetch the file until it expires — within minutes. It names one itinerary in one format and nothing else, and it re-checks your access when it is fetched, so a link that leaks after your access changed is already dead. Do not log it, cache it, or persist it.

Nothing is stored by an export: it creates no share link and leaves no state behind, so the same itinerary can be prepared repeatedly in different formats without side effects.

Next steps

Terrain

Profile a segment's geometry for elevation, slope, and aspect.

Map Studio API

Create, edit, and publish the itineraries these queries read.