Core concepts

A short tour of the ideas that run through every part of the platform. Read this once and the product guides will feel familiar. Each section links out to the page that covers it in depth, so treat this as a map rather than a manual.

The four products

Mountaya exposes four products. Most integrations use one; some combine them.

Authentication

Every request carries an API key, and most surfaces also carry a short-lived session token; the model is the same across all four products. A publishable key (pk_…) is safe to ship in a browser, a secret key (sk_…) stays on a server you control and mints session tokens, and scopes (embedding, tiles, resources, data, mcp, management) gate which products each key reaches, one surface per scope. See authentication for the key pair, scopes, the session-token flow, and the query-parameter fallbacks.

Resource types

Beyond the basemaps and environmental overlays, the platform renders and queries several kinds of content. These are the resources you select by id when embedding a map, request tiles for, or search across.

Map Embedding selects these by id (itinerary_id, collection_id, zone_id), the Data API search query finds the itineraries, collections, and zones your credential may view, the Map Studio API creates and edits them, and the Tile API serves tiles for each.

Draft and published

An itinerary is edited as a draft and shown to the public as a published version. Editing a segment or a waypoint only ever changes the draft, so a route can be reworked in the open without anyone seeing a half-finished course. When the work is ready, publishing takes a snapshot of the whole itinerary at that moment.

Which version a request receives depends on the credential it presents, not on a parameter you choose.

Because a snapshot is taken at publish time, deleting a segment from the draft does not remove it from the published version. The public view keeps serving the last published snapshot until the next publish replaces it.

Publishing is blocked while a collaborator is still editing any part of the itinerary, so a snapshot never captures an edit halfway through.

Segment groups

An itinerary's segments are its legs, and a group labels a run of neighbouring ones as a single stage — a day, a col, an approach. A group carries a name, a colour, and optionally a speed, and those override what the run shows in the segment list, on the elevation profile, and in the hover readout.

Grouping changes no geometry. The member segments keep their own shape, metrics, and position, and each stays individually selectable and editable; a group is presentation, and its members are always a contiguous run.

Groups ship on the itinerary payload as groups, and each segment names the group it belongs to through group_id. A published snapshot freezes a group's name, colour, and speed alongside its members, so renaming or deleting a group in the draft leaves the published version untouched, exactly like every other edit.

Coordinates

Every coordinate in the platform is a [longitude, latitude] pair in WGS 84 (EPSG:4326), longitude first. This matches GeoJSON and MapLibre, and is the opposite order from the lat, lng convention some mapping tools use, a frequent source of swapped-axis bugs.

[6.8712, 45.9231]

The pair above is Chamonix: longitude 6.8712, latitude 45.9231. Across the Data API, distances are in meters, durations in seconds, elevations in meters above sea level, and gradients in degrees.

Units

Map Embedding renders measurements in the display units you choose. These preferences are set per embed and fall back to your organization's defaults.

These set the Map Embedding iframe's initial display preferences. Each is optional; when omitted, the studio falls back to your organization's defaults and then to a built-in default.

Activities

Routing is tuned per activity: most use a profile tuned to their terrain and movement style, with a default speed you can override. Activity values appear as the ActivitySlug enum in the Data API and as a lowercase wire form in the Map Studio and Tile APIs.

Each activity routes on a profile tuned to its terrain and movement style. Directions availability varies: most activities support turn-by-turn routing, backcountry skiing is freehand-line only, and cycling activities are not yet available for routing. The GraphQL ActivitySlug enum uses the uppercase value; the Map Studio and Tile APIs use the lowercase, underscore-free wire form.

Languages

The platform localizes names and descriptions into the supported languages below. Select one with a Language value where the API accepts it; error messages also honour the Accept-Language header.

The Language enum sets the locale of localized strings the API returns. The Data API also honours the Accept-Language header for error messages.

Rate limiting

Quotas are applied per organization, per API, per minute, across every key the organization owns: 60 requests per minute for the Data API and 600 for the Tile API by default. The Map Studio API carries no quota; its one bounded operation is session creation, which has its own per-IP and per-key limits. When you exceed any of them, the API responds with 429 Too Many Requests and no Retry-After header. See errors and rate limits for the full model and how it surfaces across the products.

Hostnames

Each surface is served from its own hostname.

Next steps