Embedding & URL parameters

The whole application state lives in the query string: viewport, sources, every visualization toggle, split layout, historical dates. A link reproduces a view exactly, and an iframe is just that link in a src. Inside an iframe the product walkthrough never starts by itself (startTour=true still opens it). The app sets no frame restrictions and is already embedded by the Heritage Watch and Anchise wrappers.

Live: the app embedded in this page, with a national COG as terrain and a Natural Earth lakes GeoJSON loaded from a URL.

Builder

Fill in a terrain (and optionally a second one, a basemap and vector data), copy the iframe. Or paste a link copied from the app's Share dialog to start from an existing view. The Share dialog itself also offers the iframe snippet, with a switch to hide the side panel.

<iframe
  src="https://terrain-viewer.iconem.com/?terrainSourceA=custom-ca-nrcan-mrdem30&drawingUrl=https%3A%2F%2Fraw.githubusercontent.com%2Fnvkelso%2Fnatural-earth-vector%2Fmaster%2Fgeojson%2Fne_110m_lakes.geojson&viewMode=3d"
  width="100%" height="560"
  style="border: 0"
  allow="fullscreen; clipboard-write"
  loading="lazy"
></iframe>

Your own data in a link

Any view's terrain or basemap can be given as a URL instead of an id. The URL becomes the source's id, so the link is self-contained: a visitor whose browser has never seen the source gets it registered on load.

A link without lat/lng is framed on view A's COG (its bounds are read from the file). The server hosting the data must allow cross-origin requests, and range requests for COGs. URLs inside the query string must be percent-encoded.

Active source versus available sources

The parameters above select a source for a view. To make sources available in the Bring-Your-Own-Data lists without activating any, so a visitor can switch between them:

So a typical embed points terrainSourceA at one COG and lists the alternatives with addTerrainUrl. Overlays, basemaps stacked on top of the active one, follow the same pattern: addOverlayUrl= makes one available, and the state field overlayBasemapIds= (a comma-separated list, which may hold URLs directly) is what turns overlays on.

The older terrainUrl= / basemapUrl= parameters still work; they only target view A and register the source under a fixed id.

Parameters that are instructions, not state

These are read once on load and are never written by the app. They stay in the URL, so the link remains shareable.

coverageOverlays is ordinary state, not an instruction — but it is worth knowing that it folds whole groups to a key, so ?coverageOverlays=mapterhorn,library is a complete, hand-writable link rather than a wall of ids. See Coverage overlays. | bookmarksUrl=<url> | A bookmarks JSON (the Bookmarks section's export format) fetched and merged into the visitor's bookmarks: a curated selection handed out by link. Pair with bookmarksGallery=true, or openSections=bookmarks / scrollTo=bookmarks, to land on it. | | addSources, addTerrainUrl, addBasemapUrl, addOverlayUrl, drawingUrl, viaTitiler, terrainType, basemapType | See above. |

The side panel and the timeline are ordinary state: sidebarCollapsed=true and historicalTimelineCollapsed=true. Which sections are folded, and the panel's scroll position, are not in the URL beyond openSections / closeSections / scrollTo: they change constantly in a session and would churn the address bar.

Everything else in the URL is state: lat, lng, zoom, pitch, bearing, viewMode (2d/3d/globe), appMode (terrain/historical), splitStyle (off/overlay/side-by-side), gridLayout, showHillshade, showRasterBasemap, date/dateA…, and so on. The quickest way to learn a parameter's name is to set it in the sidebar and read the address bar.

Project presets

?project=<id> applies a preset from the app's bundled lib/projects.json. A preset can hide parts of the interface, seed state and carry the sources it needs, which is how a curated embed avoids dozens of query parameters. See also Projects for the user-facing import/export bundles, which share the source and drawing formats.

{
  "my-site": {
    "id": "my-site",
    "name": "My site",
    "description": "One COG, hillshade on, no source pickers",
    "initialViewMode": "3d",
    "disableViewModes": ["globe"],
    "initialSidebarOpen": true,
    "hideSourcePanels": true,
    "hiddenSections": ["contour", "bookmarks", "projectImportExport"],
    "hideMapControls": ["geocoder", "geolocate"],
    "initialSections": { "general": false, "visualizationModes": true },
    "initialState": { "sourceA": "my-dem", "showHillshade": true, "showColorRelief": false },
    "customTerrainSources": [
      { "id": "my-dem", "name": "My DEM", "url": "https://host/dem.tif", "type": "cog", "cogViaTitiler": true, "maxzoom": 14 }
    ],
    "customBasemapSources": [
      { "id": "my-ortho", "name": "Orthophoto", "url": "https://host/ortho.tif", "type": "cog", "role": "basemap", "opacity": 100 }
    ],
    "autoZoomToSource": "sourceA"
  }
}

The exact interface, generated from lib/project-config.ts at build time:

Presets are part of the deployed app, so adding one is a pull request. For a one-off, the URL parameters above cover most of the same ground.

All parameters that are not state

Everything the app reads from the URL that it never writes back, in one place. Read once on load and left in the URL, so the link stays shareable.

Everything else is state, mirrored to the address bar by nuqs as you use the app. The complete generated list, with types and defaults, and the settings that live in localStorage instead, are on the State reference page; the same parameters as an interactive form are on URL as an API.