Get started
Tutorials

Build a race course page

Build a race course page

A course page runners can read at a glance: the route on a map, its elevation profile, and a table of aid stations with their services and cut-off times.

A course on a map above its table of aid stations

You set the course up with the Map Studio API, then draw it with the TypeScript SDK. You need:

  • a publishable key with the studio-embedded, publishing and tiles scopes, and your secret key;
  • the id of a member of your organization, who the writes act as;
  • for the page, a Vite and React app. To start one:
npx create-vite@latest course-page --template react-ts && cd course-page && \
  npm install @mountaya/client @mountaya/elements @mountaya/elements-react maplibre-gl@6.16.0

Map Studio and the Tile API come with an agreement.

1

Mint a session token for a member

Writes act as one of your members, so your server mints a session token that names them.

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)
Response
{
  "data": {
    "expires_at": "2026-11-09T13:28:33.925081Z",
    "token": "sess_your_session_token",
    "user_id": "7a4e1c98-3b52-4f60-9d81-c05e2f7a83b1"
  }
}

2

Create the course

Import the route and its aid stations in one call. Already have your course in Mountaya? Skip this step and use its id.

ACTIVITY_ID=$(curl -s https://api.mountaya.com/v1/activities \
  -H "X-API-Key: $MOUNTAYA_PUBLISHABLE_KEY" \
  | jq -r '.data[].children[] | select(.slug == "running") | .id')

COURSE=$(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 @- <<JSON
{
  "name": "Docs Vallée Trail",
  "activity_id": "$ACTIVITY_ID",
  "is_private": false,
  "segments": [{
    "name": "Les Houches to Argentière",
    "mode": "directions",
    "geojson": {"type": "MultiPoint", "coordinates": [[6.7991, 45.8915], [6.8712, 45.9231], [6.9271, 45.9822]]}
  }],
  "waypoints": [
    {"mode": "poi", "name": "Chamonix", "icon": "droplet", "geojson": {"type": "Point", "coordinates": [6.8712, 45.9231]}},
    {"mode": "poi", "name": "Argentière", "icon": "flag", "geojson": {"type": "Point", "coordinates": [6.9271, 45.9822]}}
  ]
}
JSON
)

ITINERARY_ID=$(echo "$COURSE" | jq -r .data.id)
echo "$COURSE" | jq '.data | {id, name, distance, ascent, waypoints: [.waypoints[] | {id, name}]}'
Response (abridged)
{
  "id": "aa75b75f-db36-4554-a13a-15e33b19aa9e",
  "name": "Docs Vallée Trail",
  "distance": 17060.58,
  "ascent": 360,
  "waypoints": [
    {
      "id": "a142860b-7c91-4c27-9389-c12aa0cfec2e",
      "name": "Chamonix"
    },
    {
      "id": "bc1f1b0b-0196-4a13-9109-a22c082a3519",
      "name": "Argentière"
    }
  ]
}

The route is routed through the three points you sent, so distance and ascent are the real trail figures.

3

Add services and a cut-off

Give the Chamonix aid station its services and the time runners must leave it by.

WAYPOINT_ID=$(echo "$COURSE" | jq -r '.data.waypoints[] | select(.name == "Chamonix") | .id')

curl -s -X PATCH "https://api.mountaya.com/v1/itineraries/$ITINERARY_ID/waypoints/$WAYPOINT_ID" \
  -H "X-API-Key: $MOUNTAYA_PUBLISHABLE_KEY" \
  -H "X-Session-Token: $MOUNTAYA_SESSION_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"amenities": ["water", "food", "first-aid"], "timing": {"cutoff_at": "2026-08-29T09:30:00Z", "stop_duration": 300}}' \
  | jq '.data.waypoints[] | select(.name == "Chamonix") | {name, amenities, timing}'
Response (abridged)
{
  "name": "Chamonix",
  "amenities": [
    "water",
    "food",
    "first-aid"
  ],
  "timing": {
    "cutoff_at": "2026-08-29T09:30:00Z",
    "stop_duration": 300
  }
}

cutoff_at is an absolute instant, so the page decides which time zone to print it in.

4

Publish the course

Runners read the published version, so publish once the course is ready.

curl -s -X POST "https://api.mountaya.com/v1/itineraries/$ITINERARY_ID/publication" \
  -H "X-API-Key: $MOUNTAYA_PUBLISHABLE_KEY" \
  -H "X-Session-Token: $MOUNTAYA_SESSION_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  | jq '.data | {id, name, published_at, has_unpublished_changes}'
Response (abridged)
{
  "id": "aa75b75f-db36-4554-a13a-15e33b19aa9e",
  "name": "Docs Vallée Trail",
  "published_at": "2026-11-09T13:26:19.12665Z",
  "has_unpublished_changes": false
}

5

Build the page

The page needs only the publishable key and the course id. The map, the profile and the table share one provider, so hovering one moves the others.

src/main.tsx
/// <reference types="vite/client" />
import { Mountaya } from "@mountaya/client/browser";
import type { MountayaMap } from "@mountaya/elements";
import { MapControls, MapView, MountayaElementsProvider } from "@mountaya/elements-react";
import { ItineraryProfile, ItineraryWaypointTable } from "@mountaya/elements-react/elements";
import "@mountaya/elements-react/styles.css";
import { StrictMode, useState } from "react";
import { createRoot } from "react-dom/client";

const client = new Mountaya({
  credential: { publishableKey: import.meta.env.VITE_MOUNTAYA_PUBLISHABLE_KEY },
});

// The course you published.
const COURSE_ID = import.meta.env.VITE_MOUNTAYA_COURSE_ID;

// Cut-offs in the race's own time zone, whatever the runner's.
const formatCutoffAt = (iso: string) =>
  new Intl.DateTimeFormat("en-GB", {
    hour: "2-digit",
    minute: "2-digit",
    timeZone: "Europe/Paris",
    weekday: "short",
  }).format(new Date(iso));

const CoursePage = () => {
  const [map, setMap] = useState<MountayaMap | null>(null);
  const [filter, setFilter] = useState<readonly string[]>([]);

  return (
    <MountayaElementsProvider client={client} map={map}>
      <div style={{ height: 420 }}>
        <MapView
          client={client}
          onReady={(ready) => {
            setMap(ready);
            void ready.setItinerary(COURSE_ID, { fit: true });
          }}
          terrain="topo"
        >
          <MapControls compass layers zoom />
        </MapView>
      </div>
      <ItineraryProfile
        axis
        formatCutoffAt={formatCutoffAt}
        itineraryId={COURSE_ID}
        sections
        surface="published"
        tooltip
      />
      <ItineraryWaypointTable
        columns={["waypoint", "distance", "elevation", "amenities", "cutoff"]}
        filter={filter}
        formatCutoffAt={formatCutoffAt}
        itineraryId={COURSE_ID}
        onFilterChange={setFilter}
        surface="published"
      />
    </MountayaElementsProvider>
  );
};

const root = document.getElementById("root");
if (root === null) throw new Error("index.html has no #root element.");

createRoot(root).render(
  <StrictMode>
    <CoursePage />
  </StrictMode>,
);

It replaces the src/main.tsx Vite wrote. Start it with your key and the course id:

Terminal
VITE_MOUNTAYA_PUBLISHABLE_KEY=pk_your_publishable_key VITE_MOUNTAYA_COURSE_ID=0b6d1a4e-6d3f-4f7a-9c2e-1f0a5b8c3d21 npm run dev

Pick a service above the table to keep only the aid stations that offer it.

Next steps

Last updated