Get started
Map Studio API

Import and export

Import and export

Take an itinerary out as a route file, and bring route files in as new itineraries. This page exports an itinerary as GPX, then imports that file back.

Before you start

Mint a session token that names a member, as in the quickstart:

export MOUNTAYA_SESSION_TOKEN=$(curl -s -X POST https://api.mountaya.com/v1/sessions \
  -H "X-API-Key: $MOUNTAYA_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"publishable_key\": \"$MOUNTAYA_PUBLISHABLE_KEY\", \"user_id\": \"7a4e1c98-3b52-4f60-9d81-c05e2f7a83b1\", \"surface\": \"studio-embedded\"}" \
  | jq -r .data.token)

The examples export $ITINERARY_ID, a published itinerary of yours.

Export a route file

GET /v1/itineraries/{itinerary_id}/export answers the file itself. With the publishable key alone, it exports the published version.

curl -s -o chamonix-to-argentiere.gpx \
  "https://api.mountaya.com/v1/itineraries/$ITINERARY_ID/export?format=gpx" \
  -H "X-API-Key: $MOUNTAYA_PUBLISHABLE_KEY"

head -n 8 chamonix-to-argentiere.gpx
Response (first lines)
<?xml version="1.0" encoding="UTF-8"?>
<gpx version="1.1" creator="Mountaya" xmlns="http://www.topografix.com/GPX/1/1">
  <trk>
    <name>Chamonix to Argentière</name>
    <trkseg>
      <trkpt lat="45.92307" lon="6.87126">
        <ele>1037.1</ele>
      </trkpt>
formatFile
gpxOne track, one track segment per itinerary segment
kml, kmzOne styled line per segment
geojsonA FeatureCollection
fit, tcxA course for a GPS watch, or an activity with variant=activity
csvA flat table of coordinates

Add segment_id to export one segment.

Import a route file

Import takes two calls. POST /v1/itineraries/preview reads the file and proposes segments without saving anything. POST /v1/itineraries/import saves the draft you send back.

PREVIEW=$(curl -s -X POST https://api.mountaya.com/v1/itineraries/preview \
  -H "X-API-Key: $MOUNTAYA_PUBLISHABLE_KEY" \
  -H "X-Session-Token: $MOUNTAYA_SESSION_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -F "provider=gpx" \
  -F "file=@chamonix-to-argentiere.gpx" \
  -F "activity_id=$ACTIVITY_ID")

IMPORTED=$(echo "$PREVIEW" \
  | jq '{
      name: "Chamonix to Argentière (GPX)",
      activity_id: .data.activity_id,
      is_private: true,
      segments: [.data.segments[] | {mode: .recommendation, name, geojson: .[.recommendation].geojson}],
      waypoints: .data.waypoints
    }' \
  | curl -s -X POST https://api.mountaya.com/v1/itineraries/import \
    -H "X-API-Key: $MOUNTAYA_PUBLISHABLE_KEY" \
    -H "X-Session-Token: $MOUNTAYA_SESSION_TOKEN" \
    -H "Idempotency-Key: $(uuidgen)" \
    -H "Content-Type: application/json" \
    -d @-)

echo "$IMPORTED" | jq '.data | {id, name, status, distance, ascent, count}'
IMPORTED_ID=$(echo "$IMPORTED" | jq -r .data.id)
Response (abridged)
{
  "id": "9b8c5fe6-85dd-4dfd-8ceb-3f5eaceb1dc5",
  "name": "Chamonix to Argentière (GPX)",
  "status": "draft",
  "distance": 9005.15,
  "ascent": 277,
  "count": {
    "groups": 0,
    "segments": 1,
    "waypoints": 0
  }
}

Review the preview before you confirm: rename the itinerary, and pick each segment's mode.

To let a visitor download the file from your page without a key, ask the Data API's exportItinerary for a signed URL. The URL works for ten minutes, with no credential.

Next steps

Last updated