Iframe parameters

Everything about an embed is set through query parameters on the iframe src. This page is the complete reference, grouped by purpose. Every parameter is optional except the publishable key: a bare embed renders a default interactive map.

Where a parameter has a default, it follows a fixed precedence. The URL value wins; if it is absent, your organization's default for that field applies; if that is also unset, the built-in default below applies. Boolean parameters take the textual values true or false.

Credentials

publishable_key

string

required

Your publishable key (pk_…) with the embedding scope. It resolves your organization and authorizes the embed. Required: an embed without a resolvable publishable key renders a loader rather than a map.

session_token

string

A short-lived session token (sess_…). Required only when your organization enforces session tokens (require_session_token). See authentication.

Content selection

The content parameters choose what the map shows.

itinerary_id

string

The itinerary to display.

collection_id

string

A collection whose itineraries and zones the studio loads. Which of those appear is governed by the with_collection_* toggles below.

zone_id

string

A zone to display on the map.

activity

string

The activity context for the map, as a wire-form slug (for example hikingandtrail). See the activities table.

Display

These parameters set the map's appearance and the initial camera.

terrain

string

default: topo

The basemap terrain slug. Defaults to topo when neither the URL nor your organization specifies one.

terrain_variant

string

default: light

The basemap tint, light or dark.

overlay

string

A single environmental overlay to show on load, by its slug (for example hillshade). See the overlays table.

hillshade

boolean

Whether to render the shaded-relief hillshade on load.

time_offset

number

The forecast time for weather and snow overlays, as a count of minutes from the viewer's current clock (negative is the past). It is clamped to the studio's forecast window, roughly 71 hours back to 6 days forward. Omitted means "now". The offset is relative on purpose, so a shared link to "+6 days" means six days from whoever opens it, not a frozen instant.

view

string

The initial camera, carried in the URL hash rather than the query string as #view=zoom/lat/lng, optionally with bearing and pitch (#view=zoom/lat/lng/bearing/pitch). The studio writes this hash as the viewer pans and zooms, so copying a live embed URL preserves the camera.

Viewer preferences

The preferred_* parameters set the embed's initial display preferences. Each is optional; when omitted, the studio falls back to your organization's default and then to a built-in default.

Preference	Parameter	Values
Length	`preferred_unit_length`	`metric`, `imperial`
Slope	`preferred_unit_slope`	`degrees`, `percentage`
Temperature	`preferred_unit_temperature`	`celsius`, `fahrenheit`
Theme	`preferred_theme`	`light`, `dark`
Base-map tint	`terrain_variant`	`light`, `dark`

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.

preferred_language

string

The locale for the studio's interface, one of en, fr, es, it, de, zh, ja. See the languages reference.

UI controls

The with_* parameters toggle which controls and panels appear. Each is a boolean; the default column is the value used when neither the URL nor your organization specifies one.

Map controls

with_navigation_control

boolean

default: true

The zoom and compass control.

with_overlays_control

boolean

default: false

The overlay picker, letting the viewer toggle environmental overlays.

with_preferences_control

boolean

default: true

The preferences control for units, language, and theme.

with_download_control

boolean

default: false

The download control for exporting the displayed content.

with_streetview_control

boolean

default: false

The street view control.

Collection content

These govern which parts of a collection_id the studio renders.

with_collection_itineraries

boolean

default: true

Show the collection's itineraries.

with_collection_zones

boolean

default: true

Show the collection's zones.

Elevation and analysis panels

with_profile_elevation

boolean

default: true

The elevation profile chart.

with_profile_characteristics

boolean

default: true

The terrain characteristics breakdown (surface, way type).

with_profile_analysis

boolean

default: true

The slope and gradient analysis.

Allowlists

Two parameters take a list of slugs rather than a single value. Pass each value as a repeated query parameter, for example ?with_overlays=hillshade&with_overlays=steepness.

with_overlays

string[]

The overlays the viewer may choose from in the overlay picker. When omitted, your organization's default allowlist applies. See the overlays table for the slugs.

with_terrains

string[]

The basemap terrains the viewer may switch between. When omitted, your organization's default allowlist applies.

Activities

The activity parameter takes the lowercase, underscore-free wire form.

Activity	API value	Wire form
Hiking and trail running	`HIKING_AND_TRAIL`	`hikingandtrail`
Running	`RUNNING`	`running`
Backcountry skiing	`BACKCOUNTRY_SKIING`	`backcountryskiing`
Ski touring	`SKI_TOURING`	`skitouring`
Cross-country skiing	`CROSS_COUNTRY_SKIING`	`crosscountryskiing`
Snowshoe walking	`SNOWSHOE_WALKING`	`snowshoewalking`
Gravel biking	`GRAVEL_BIKE`	`gravelbike`
Mountain biking	`MOUNTAIN_BIKE`	`mountainbike`
Road cycling	`ROAD_CYCLING`	`roadcycling`

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.

Overlays

The overlay parameter and the with_overlays allowlist take these overlay slugs.

Overlay	Group	Description
`pois`	Terrain enrichment	Points of interest (huts, peaks, passes, parking, water) rendered as vector features.
`hillshade`	Terrain enrichment	Shaded-relief hillshade derived from the digital elevation model.
`temperature-actual`	Weather	Forecast air temperature.
`temperature-perceived`	Weather	Forecast perceived ("feels-like") temperature.
`temperature-soil`	Weather	Forecast soil-surface temperature.
`visibility`	Weather	Forecast horizontal visibility.
`humidity`	Weather	Forecast relative humidity.
`wind`	Weather	Forecast wind speed and direction.
`steepness`	Surface	Slope steepness classification from 25° to 45°+.
`aspectslope`	Surface	Combined slope aspect and steepness shading.
`snowdepth`	Snow	Modelled snow depth on the ground.
`snowfall-daily`	Snow	Forecast daily snowfall accumulation.
`snowfall-hourly`	Snow	Forecast hourly snowfall accumulation.

Weather and snow overlays accept a timestamp query parameter to select a forecast step; static overlays (pois, hillshade, aspectslope) ignore it.

Next steps

Iframe events

Change the displayed content after load and react to the ready event with the postMessage API.

Examples

End-to-end recipes that combine parameters with the runtime API.