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 three products

Mountaya exposes three 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 three 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 (data, tiles, embedding) gate which products each key reaches. 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 Tile API serves tiles for each, and the Data API search query can find the itineraries, collections, and zones your credential may view.

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.8652, 45.8326]

The pair above is Chamonix: longitude 6.8652, latitude 45.8326. 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: each uses a profile optimized for its terrain and movement style, with a sensible default speed you can override. Activity values appear as the ActivitySlug enum in the Data API and as a lowercase wire form in the Tile and REST APIs.

Each activity routes on a profile tuned to its terrain and movement style. The GraphQL ActivitySlug enum uses the uppercase value; the Tile and REST 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

Limits are applied per key. When you exceed one, the API responds with 429 Too Many Requests and a Retry-After header telling you how long to wait. 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