Skip to main content

Tile

Tile puts a Kaleidr basemap on your page. You pick a style, such as kaleidr-morning or kaleidr-night, and the SDK shows it in an iframe that Kaleidr hosts. Your page loads no map library.

Use Tile when you want a good-looking, interactive basemap and do not need to draw on it yourself: a location backdrop, a "where we are" panel, or the map that a Kaleidr chat panel plots its answers on.

If you already run your own Mapbox, MapLibre, Google Maps or Leaflet map, you do not need Tile. Attach Chat to the map you have.

At a glance​

QuestionAnswer
What do I need?A publishable key (kld_pk_live_…) that carries the maps scope. New keys carry it by default.
Which plan?Every plan, Free included.
How does it render?In an iframe served from https://map-embed.kaleidr.com.
How do I choose the look?With style-id. Six general-purpose styles are listed below.
What does it cost?One map load per tile session. See How map loads are counted.
Can the page talk to the map?It can set and move the camera, swap the style, and listen for a loaded message and an error message.

The smallest embed​

<script src="https://cdn.kaleidr.com/embed/v1/kaleidr.js"></script>
<kaleidr-map product="tile"
             publishable-key="kld_pk_live_…"
             style-id="kaleidr-morning"
             style="display:block; height:480px"></kaleidr-map>

Three things make this work:

  1. A key. Create a publishable key at kaleidr.com/api-keys. See Get an API key.
  2. An allowed origin. If the key lists allowed origins, the page's origin must be one of them. The page must be served over HTTP or HTTPS, not opened from disk.
  3. A height. The element is display:block by default, so a height on it applies. The snippet also writes display:block, which covers Safari before 16.4, where the element stays inline.

Styles​

style-idLook
kaleidr-morningBright: white ground, cyan water, white roads.
kaleidr-afternoonMid-tone ground with green vegetation and gray roads.
kaleidr-eveningGolden hour: warm sand and olive tones.
kaleidr-nightDark navy and charcoal with amber highways.
kaleidr-plainWhite canvas with borders and place labels. 3D buildings appear from zoom 15.
kaleidr-editorialThe afternoon palette with labels off, for small or decorative maps.

Always pass style-id. If you leave it out, the embed uses your organization's default basemap when one is set, and shows an error when none is.

How it works​

  1. The SDK sends your publishable key to Kaleidr and receives a short-lived tile session. This is the step that checks the key, its scope and your page's origin, and counts a map load. The answer also carries your organization's default basemap, when one is set. That is all the tile session is for: the map makes no further calls with it.
  2. The SDK replaces the element's contents with an iframe that shows the style you asked for. The frame's URL carries the style id and the camera you passed, and nothing else: neither your publishable key nor the session token is in it.
  3. The map draws inside the iframe. Your page's Content Security Policy only has to allow the loader, the session request and the frame.
  4. When the map has drawn, the iframe posts a kaleidr-embed:ready message to your page.

What the visitor can do​

Pan, rotate and tilt the map, and zoom with the on-map buttons, a pinch or the scroll wheel. Scrolling with the pointer over the map zooms the map; with the pointer outside the map, scrolling moves your page.

What your page can do​

  • Set the opening camera with center, zoom, pitch and bearing.
  • Move the camera later with handle.setCamera(...).
  • Swap the style with handle.setStyle('kaleidr-night'), with no reload.
  • Pair a chat panel with it. A chat mount can point at a tile element and plot its answers there.
  • Know when it loaded from the kaleidr-embed:ready message.

How map loads are counted​

Tile usage is measured in map loads, the same unit that views of your published maps use. One map load is counted each time the SDK obtains a tile session:

  • once when the map mounts;
  • again each time the SDK renews the session, which it does shortly before the session expires for as long as the mount exists. Sessions last 15 minutes by default;
  • again if you destroy the mount and mount it again, or remove the element and re-insert it.

A visitor who looks at the page for a few minutes uses one map load. A page left open for an hour uses about five. This is not "one per page view", so destroy tile mounts you no longer show.

When your organization has used its map loads for the period, new tile sessions are refused with HTTP 429. A new mount renders nothing. A map that is already on the page stays on the page. Allowances are in Quota and rate limits.

Limits​

  • Tile is a basemap. Your page cannot add its own markers, layers or popups to it, and receives no click or camera events from it. A paired chat panel can plot places on it.
  • The Tile product is the supported way to show a Kaleidr basemap.
  • Changing style-id on a mounted element does nothing. Use handle.setStyle, or insert a new element.
  • There is no separate tile key. The publishable key you use for other Kaleidr products is the tile key.

Where to go next​