Properties
Properties control the behavior and appearance of embedded iframes — the default terrain, language, measurement units, map controls, and active content.
Organization-level defaults ensure consistency across all iframes. You can override them on a per-iframe basis for specific use cases.
All properties except view are URL query parameters (after ?, joined with &). The view property is a URL fragment (after #) and must come last.
/studio/embed?with_profile_elevation=true#view=10.93/45.8793/6.939/171.3/51Unlike safety rules, which impose strict limits, properties function as configuration presets.
Required properties
Authenticate the iframe using your organization's publishable key. This key identifies your organization and applies the corresponding safety rules.
For details on API keys and session tokens, see Authentication.
Kind: URL query parameter (?)
Key:
publishable_keyType:
stringExample:
/studio/embed?publishable_key=pk_abc123def456Authenticate the iframe using a short-lived session token. Required if the require_session_token safety rule is enabled. The token must be created server-side and is tied to the publishable key provided via publishable_key.
Session tokens expire after 5 minutes. Your backend should refresh them before expiry and update the iframe URL accordingly.
For a step-by-step guide, see Authentication.
Kind: URL query parameter (?)
Key:
session_tokenType:
stringExample:
/studio/embed?publishable_key=pk_abc123def456&session_token=sess_eyJvcm...Optional properties
Map's default state
Loads the drawings and routes of a collection. Displays drawings if with_collection_drawings is enabled, and routes if with_collection_routes is enabled.
Required if itinerary_id or route_id is set.
To display a single itinerary or route from a collection, disable the corresponding with_collection_* toggle and set the ID:
/studio/embed?with_collection_routes=false&collection_id=uuid&itinerary_id=uuidKind: URL query parameter (?)
Key:
collection_idType:
uuidExample:
/studio/embed?collection_id=78ea01f3-8256-4925-9a02-44d3eadc3980Sets the default active overlay.
Kind: URL query parameter (?)
Key:
overlayType:
stringSupported overlays:
"aspectslope"
"avalanche"
"hillshade"
"humidity"
"pois"
"snowdepth"
"snowfall-daily"
"snowfall-hourly"
"temperature-actual"
"temperature-perceived"
"temperature-soil"
"visibility"
"wind"Example:
/studio/embed?overlay=temperature-perceivedSets the default active itinerary. Must be present in the collection defined by collection_id.
Displayed even if with_collection_itineraries is disabled — this lets you show one specific itinerary without the rest.
Mutually exclusive with route_id. If both are set, itinerary_id takes priority.
Kind: URL query parameter (?)
Key:
itinerary_idType:
uuidExample:
/studio/embed?collection_id=uuid&itinerary_id=uuidSets the default active route, giving users access to its elevation profile and characteristics. Must be present in the collection defined by collection_id.
Displayed even if with_collection_routes is disabled — this lets you show one specific route without the rest.
Mutually exclusive with itinerary_id. If both are set, itinerary_id takes priority.
Kind: URL query parameter (?)
Key:
route_idType:
uuidExample:
/studio/embed?collection_id=uuid&route_id=uuidSets the default terrain.
Kind: URL query parameter (?)
Key:
terrainType:
stringSupported terrains:
"satellite"
"topo"
"winter"Example:
/studio/embed?terrain=satelliteSets the default map position: zoom, center latitude, center longitude, bearing, and pitch.
Kind: URL fragment (#)
Key:
viewType:
string (zoom/latitude/longitude/bearing/pitch)Example:
/studio/embed#view=10.93/45.8793/6.939/171.3/51Custom user experience
Sets the language. Cannot be changed by the user via the Preferences panel.
Kind: URL query parameter (?)
Key:
preferred_languageType:
stringSupported languages:
"en"
"fr"Example:
/studio/embed?preferred_language=enSets the theme. Cannot be changed by the user via the Preferences panel.
Kind: URL query parameter (?)
Key:
preferred_themeType:
stringSupported themes:
"auto"
"dark"
"light"Example:
/studio/embed?preferred_theme=darkSets the unit of length. Can be changed by the user via the Preferences panel if with_preferences_control is enabled. When changed, the preference applies across all iframes in the session.
Kind: URL query parameter (?)
Key:
preferred_unit_lengthType:
stringSupported units of length:
"metric"
"imperial"Example:
/studio/embed?preferred_unit_length=metricSets the unit of slope. Can be changed by the user via the Preferences panel if with_preferences_control is enabled. When changed, the preference applies across all iframes in the session.
Kind: URL query parameter (?)
Key:
preferred_unit_slopeType:
stringSupported units of slope:
"degrees"
"percentage"Example:
/studio/embed?preferred_unit_slope=degreesSets the unit of temperature. Can be changed by the user via the Preferences panel if with_preferences_control is enabled. When changed, the preference applies across all iframes in the session.
Kind: URL query parameter (?)
Key:
preferred_unit_temperatureType:
stringSupported units of temperature:
"celsius"
"fahrenheit"Example:
/studio/embed?preferred_unit_temperature=celsiusSets the terrain appearance for different conditions (e.g. day or night).
Kind: URL query parameter (?)
Key:
terrain_variantType:
stringSupported values:
"light"
"dark"Example:
/studio/embed?terrain_variant=darkEnables the characteristics display for the active route.
Kind: URL query parameter (?)
Key:
with_profile_characteristicsType:
booleanExample:
/studio/embed?with_profile_characteristics=trueEnables the elevation profile for the active route.
Kind: URL query parameter (?)
Key:
with_profile_elevationType:
booleanExample:
/studio/embed?with_profile_elevation=trueEnables the summary headline for the active route in the iframe header.
Kind: URL query parameter (?)
Key:
with_profile_headlineType:
booleanExample:
/studio/embed?with_profile_headline=trueEnables display of drawings from the collection passed via collection_id.
Kind: URL query parameter (?)
Key:
with_collection_drawingsType:
booleanExample:
/studio/embed?with_collection_drawings=trueEnables display of itineraries from the collection passed via collection_id. Does not affect the itinerary set via itinerary_id, which is always shown.
Kind: URL query parameter (?)
Key:
with_collection_itinerariesType:
booleanExample:
/studio/embed?with_collection_itineraries=trueEnables display of routes from the collection passed via collection_id. Does not affect the route set via route_id, which is always shown.
Kind: URL query parameter (?)
Key:
with_collection_routesType:
booleanExample:
/studio/embed?with_collection_routes=trueEnables map interactivity — zoom, pan within boundaries, and pitch adjustment.
Kind: URL query parameter (?)
Key:
with_interaction_controlType:
booleanExample:
/studio/embed?with_interaction_control=trueEnables the zoom and bearing controls at the top-right of the map. Disabled if with_interaction_control is also disabled.
Kind: URL query parameter (?)
Key:
with_navigation_controlType:
booleanExample:
/studio/embed?with_navigation_control=trueEnables specific overlays. A wildcard (["*"]) enables all overlays. If both with_overlays and with_terrains are empty, the Layers panel is hidden.
Kind: URL query parameter (?)
Key:
with_overlaysType:
string[] | ["*"]Supported overlays:
"aspectslope"
"avalanche"
"hillshade"
"humidity"
"pois"
"snowdepth"
"snowfall-daily"
"snowfall-hourly"
"temperature-actual"
"temperature-perceived"
"temperature-soil"
"visibility"
"wind"Example:
/studio/embed?with_overlays=temperature-perceived&with_overlays=snowdepthEnables the history and forecast layer control.
Kind: URL query parameter (?)
Key:
with_overlays_controlType:
booleanExample:
/studio/embed?with_overlays_control=trueEnables the download button, allowing users to download the active route or itinerary as GPX or GeoJSON.
Kind: URL query parameter (?)
Key:
with_download_controlType:
booleanExample:
/studio/embed?with_download_control=trueEnables the Preferences panel, allowing users to change their preferred unit of length and temperature. Changes apply across all iframes in the session.
Kind: URL query parameter (?)
Key:
with_preferences_controlType:
booleanExample:
/studio/embed?with_preferences_control=trueEnables the scale control at the bottom-left of the map.
Kind: URL query parameter (?)
Key:
with_scale_controlType:
booleanExample:
/studio/embed?with_scale_control=trueEnables specific terrains. A wildcard (["*"]) enables all terrains. If both with_overlays and with_terrains are empty, the Layers panel is hidden.
Kind: URL query parameter (?)
Key:
with_terrainsType:
string[] | ["*"]Supported terrains:
"satellite"
"topo"
"winter"Example:
/studio/embed?with_terrains=satellite&with_terrains=winter