Custom Map Tiles API for Branded Basemaps

A custom map tiles API delivers geographic tiles and style resources so a website or application can render a branded interactive basemap. Vector tiles carry roads, buildings, water, and related features; a style document defines colors, labels, icons, and layer order; fonts, sprites, a CDN, authentication, attribution, and a browser renderer such as MapLibre complete the system. Without that full contract, teams often ship a pretty static image and lose interactive zoom, restyling, and layer control.

The sections below cover architecture, branding, Kaleidr delivery paths, attribution and hosting tradeoffs, map loads and caching, mistakes to avoid, and a production checklist. For design-token and hierarchy work, see How to Build a Custom Branded Basemap. For Studio authoring, open Kaleidr Studio after the architecture decisions below are clear.

Custom map tiles API essentials

• Separate data from style: Vector tiles hold geography; the style document owns paint, layout, and layer order.
• Ship supporting assets: Glyphs, sprites, attribution, and a renderer are part of the contract—not optional polish.
• Prefer hosted delivery unless you need the pipeline: Self-hosting buys control and owns updates, CDN, and incidents.
• Meter sessions, not curiosity: One map open can request many tiles; plan capacity from map loads and cache behavior.
• Keep attribution visible: Open data licenses still apply on hosted and self-hosted paths.

What Is a Custom Map Tiles API?

A custom map tiles API is the delivery layer that supplies the geographic chunks and supporting resources a renderer needs to draw an interactive basemap. Tiles are not the finished product: the basemap is the visual background assembled from tile sources, style rules, labels, icons, optional terrain, and attribution. The host application then places its own markers, routes, polygons, and workflow UI above that background so product data stays visually dominant.

Raster tiles remain useful for imagery, hillshade, and other pixel sources, while vector tiles fit branded, multi-zoom interactive basemaps because styling stays client-side. The Mapbox Vector Tile Specification describes the common MVT encoding, and MapLibre GL JS renders those tiles in the browser under a style document defined by the MapLibre Style Specification—both linked in References. Hybrid maps can still combine both when satellite or terrain pixels sit beneath vector roads and labels.

How Do Vector Tiles, Style JSON, and the Renderer Fit Together?

A global map is divided into a zoomed grid, and the renderer requests only the tiles needed for the current camera, typically through a URL pattern such as /tiles/{z}/{x}/{y}.pbf. A tile endpoint alone is incomplete: the style must declare sources, zoom ranges, source-layer names, glyph and sprite URLs, attribution, and ordered layers. TileJSON or explicit tile templates describe those sources in the style document so the renderer knows what to fetch and how to interpret each payload.

A style layer usually names an ID, a type such as fill, line, or symbol, a source and source-layer, zoom limits, filters, layout, and paint. Layer order is the drawing order: road casings sit beneath road fills; labels sit above the geometry they describe; product overlays usually sit above the basemap. The same compatible vector source can feed morning, night, and editorial variants when only paint, visibility, and typography change, which is why a branded basemap is a coordinated system rather than a static map image.

The conceptual skeleton below is illustrative rather than a Kaleidr export. It shows the usual roots—sources, sprite, glyphs, and an ordered layers array—that every production style must fill in before the map can render labels and icons correctly. Treat empty layers as a reminder that paint and layout rules are the actual design work.

{
  "version": 8,
  "name": "Example Branded Basemap",
  "sources": {
    "basemap": {
      "type": "vector",
      "url": "https://tiles.example.com/tilejson.json"
    }
  },
  "sprite": "https://cdn.example.com/sprites/brand",
  "glyphs": "https://cdn.example.com/fonts/{fontstack}/{range}.pbf",
  "layers": []
}

What Makes a Basemap Branded?

Branding is not recoloring every road with a corporate accent. A useful branded basemap aligns hierarchy, typography, icons, and zoom behavior with the product while keeping geography readable. Define color roles for land, water, parks, buildings, road classes, boundaries, transit, labels, and highlights, then set label priority for the audience: travel maps emphasize districts and landmarks; logistics maps emphasize roads and facilities; property maps emphasize transit and neighborhoods. Suppress low-value points of interest and detailed geometry until a useful zoom, and keep light, dark, high-contrast, editorial, and operational variants on one shared token system so they stay consistent across releases.

How Do You Deliver Kaleidr Designed Basemaps?

Kaleidr documents two delivery paths for designed basemaps. The embedded tiles product owns its map inside an iframe and is selected by style ID with product="tile". Load the versioned loader once from https://cdn.kaleidr.com/embed/v1/kaleidr.js, then declare the custom element with an explicit height so the layout does not collapse before the map paints.

<kaleidr-map
  product="tile"
  publishable-key="kld_pk_live_REPLACE_ME"
  style-id="kaleidr-morning"
  center="-0.12,51.5"
  zoom="11"
  style="height: 480px">
</kaleidr-map>

Built-in style IDs include kaleidr-morning, kaleidr-afternoon, kaleidr-night, kaleidr-editorial, and kaleidr-plain. The examples follow the current Tiles reference and use-tiles guide; the loader installs window.Kaleidr and defines <kaleidr-map> for both declarative markup and imperative mounts. Teams that already own a MapLibre map can load the published style JSON directly without an iframe, which keeps native control over layers, events, camera behavior, and overlays.

const map = new maplibregl.Map({
  container: "map",
  style: "https://tile.kaleidr.com/styles/kaleidr-morning.json",
  center: [-0.12, 51.5],
  zoom: 11
});

Choose the embedded tiles product for a self-contained basemap component. Choose direct MapLibre loading when the host must own the map object. Tile embeds use a browser publishable key with the maps scope, restricted to approved origins and exchanged for a short-lived session; keep server keys out of the browser and configure origins before shipping to production.

How Should Teams Handle Attribution, Hosting, and Cost?

Open map data and public community tile servers are not the same thing. OpenStreetMap data is available under the Open Database License, and visible attribution is required on the copyright page linked in References. The OpenStreetMap Foundation’s public raster and vector tile services have separate usage policies with limited shared capacity, so production applications should not treat community tile endpoints as an unrestricted commercial CDN.

Kaleidr’s current pricing page states that open basemap tiles derive from open geographic data, are served through Kaleidr’s tile CDN, allow commercial use within each plan’s map-load allowance, require attribution to OpenStreetMap contributors, and permit self-hosting the same open data when teams prefer to operate the pipeline. Keep attribution visible on every map mode, including mobile and full-screen, and preserve it in exports when required. Hosting choice determines who owns updates, delivery, scaling, monitoring, and incident response—not whether attribution still applies.

Self-host when specialized data, isolation, or custom update cycles justify the maintenance burden. Use hosted delivery when the main need is a reliable branded basemap without running the full pipeline. Kaleidr Enterprise supports custom map loads and an independent CDN when volume or isolation exceeds the standard Pro pool.

How Do Map Loads, Caching, and Performance Interact?

A tile request is not a complete map session. One open can fetch style JSON, many vector tiles, glyph ranges, sprites, optional terrain or raster layers, and additional tiles after pan and zoom. Kaleidr meters one pool of map loads rather than billing every tile separately. The pricing page describes one map load as one open or boot of a shared, published, embedded, or basemap session and estimates roughly 20 tile requests per map load. Published monthly allowances reviewed on 5 August 2026 are 2,500 map loads on Free and 25,000 on Pro; Enterprise is custom. Confirm current figures on the pricing page before capacity planning.

One map session can generate many resource requests; style complexity and caching determine real performance and cost. Reduce style complexity with zoom-dependent visibility, restrained symbol density, and stable cacheable URLs for immutable tile versions. Measure cold loads with an empty cache, warm loads after priming, mobile networks, style switches, and failed font, sprite, or tile requests in your environment—treat diagrams as teaching aids, not published latency SLAs. MapLibre may require worker, image, and connection sources allowed by Content Security Policy, and its documentation notes worker requirements for strict deployments.

Accessibility still applies across every branded style. Preserve label contrast, avoid color-only categories, expose names and actions outside the canvas, provide keyboard paths through map-adjacent controls, and follow current WCAG guidance where the surrounding product must. Measure map-load success, style-load time, tile and asset errors, time to a usable map, quota use, and completion of the product task the map supports—not tile volume alone.

Which Mistakes Should Teams Avoid?

Before release, document source and style contracts, version style URLs, verify zoom bounds and source-layers, confirm glyphs and sprites across languages and pixel ratios, test light and dark variants, configure CSP, restrict publishable keys and confirm the maps scope, keep attribution readable, handle tile, font, sprite, and style failures, and test real application overlays above the basemap. Run the checklist on staging origins that match production, then repeat on a mid-range phone before you call the style done.

Final Verdict

A custom map tiles API turns geographic data and a branded style system into an interactive basemap. Vector tiles carry reusable features; the style document decides what to draw and how it looks; fonts, sprites, a renderer, a CDN, authentication, attribution, and host overlays complete the stack. Host when you want delivery without owning the pipeline; self-host when pipeline control is the product requirement. Keep the basemap separate from authoritative business data, and measure the user task the map enables.

Kaleidr provides Studio design for custom basemaps, an embeddable tiles product for a self-contained map, and a published style URL for teams that own MapLibre. Choose the path by how much control the host needs over the map object, layers, and infrastructure—then ship the style only after cold and warm loads look acceptable on the devices your users actually use. Revisit the decision when overlays, offline needs, or map-load volume change the operational equation.

Add Designed Tiles to Your Application

Review style IDs, the MapLibre style URL, publishable-key requirements, and the map-load model in the current docs, then integrate with an origin-restricted key. Start with one style ID on staging, confirm attribution and camera defaults, and only then wire the same style into production hosts. Read the Kaleidr Tiles Documentation to start the embed or style-URL path for your product.

FAQs

What is a custom map tiles API?

A custom map tiles API serves geographic tiles and supporting resources used to render a styled basemap. A complete integration normally includes tile sources, a style document, fonts, sprites, attribution, a renderer, and usage controls.

What is the difference between map tiles and a basemap?

Tiles are the geographic chunks delivered to the renderer. A basemap is the complete visual background created from tile sources, style rules, labels, icons, terrain, and attribution.

Are vector tiles images?

No. Vector tiles encode geographic features and attributes. A browser or native renderer applies style rules and draws the result. Raster tiles are pre-rendered images.

Can the same vector tiles support multiple brands?

Yes. Multiple style documents can reference the same compatible tile source and apply different colors, labels, layer visibility, icons, and zoom rules.

Does a branded basemap replace application data?

No. The basemap provides geographic context. Stores, properties, routes, assets, and other business records should remain separate overlays backed by authoritative systems.

Can I use Kaleidr tiles with MapLibre?

Yes. The current use-tiles guide documents a published style JSON URL that can be passed directly to a MapLibre map.

Does the Kaleidr tiles embed require an API key?

Current SDK documentation requires a browser publishable key for tiles and identifies maps as the required capability scope. Restrict the key to approved origins.

Can I expose a Kaleidr server key in a tile embed?

No. Server keys are backend credentials. Use a publishable browser key through the Kaleidr SDK or custom element.

Are Kaleidr basemap tiles available for commercial use?

Kaleidr’s current pricing page states that commercial use is allowed within each plan’s map-load allowance. Attribution and applicable data-license requirements still apply.

Can I self-host open map data?

Yes, when the underlying licenses permit it. Self-hosting requires the team to manage data updates, tile generation, storage, CDN delivery, monitoring, attribution, and reliability.

References

• Kaleidr. Create Custom Maps with AI Map Maker. kaleidr.com. Accessed 5 August 2026. https://kaleidr.com/studio
• Kaleidr. Pricing & Plans. kaleidr.com. Accessed 5 August 2026. https://kaleidr.com/pricing
• Kaleidr. Tiles — Embed a Designed Basemap. Kaleidr Developer Docs. Accessed 5 August 2026. https://docs.kaleidr.com/sdk/tiles
• Kaleidr. Use a Designed Basemap. Kaleidr Developer Docs. Accessed 5 August 2026. https://docs.kaleidr.com/guides/use-tiles
• Kaleidr. kaleidr.js — the Loader. Kaleidr Developer Docs. Accessed 5 August 2026. https://docs.kaleidr.com/sdk/kaleidr-js
• Kaleidr. kaleidr-map — the Element. Kaleidr Developer Docs. Accessed 5 August 2026. https://docs.kaleidr.com/sdk/kaleidr-map-element
• Kaleidr. Get an API Key. Kaleidr Developer Docs. Accessed 5 August 2026. https://docs.kaleidr.com/get-an-api-key
• Kaleidr. Auth & Scopes. Kaleidr Developer Docs. Accessed 5 August 2026. https://docs.kaleidr.com/platform-api/auth-and-scopes
• MapLibre. MapLibre GL JS Introduction. Accessed 5 August 2026. https://maplibre.org/maplibre-gl-js/docs/
• MapLibre. MapLibre Style Specification. Accessed 5 August 2026. https://maplibre.org/maplibre-style-spec/
• MapLibre. Sources — MapLibre Style Specification. Accessed 5 August 2026. https://maplibre.org/maplibre-style-spec/sources/
• Mapbox. Mapbox Vector Tile Specification. Accessed 5 August 2026. https://github.com/mapbox/vector-tile-spec
• OpenStreetMap Foundation. Copyright and License. Accessed 5 August 2026. https://www.openstreetmap.org/copyright
• OpenStreetMap Foundation. Tile Usage Policy. Accessed 5 August 2026. https://operations.osmfoundation.org/policies/tiles/
• OpenStreetMap Foundation. Vector Tile Usage Policy. Accessed 5 August 2026. https://operations.osmfoundation.org/policies/vector/
• World Wide Web Consortium. Web Content Accessibility Guidelines (WCAG) 2.2. Accessed 5 August 2026. https://www.w3.org/TR/WCAG22/

@misc{kaleidr_tiles,
  title  = {Tiles -- Embed a Designed Basemap},
  author = {{Kaleidr}},
  note   = {Kaleidr Developer Docs; accessed 5 August 2026},
  url    = {https://docs.kaleidr.com/sdk/tiles}
}

@misc{kaleidr_use_tiles,
  title  = {Use a Designed Basemap},
  author = {{Kaleidr}},
  note   = {Kaleidr Developer Docs; accessed 5 August 2026},
  url    = {https://docs.kaleidr.com/guides/use-tiles}
}

@misc{maplibre_style_spec,
  title  = {MapLibre Style Specification},
  author = {{MapLibre}},
  note   = {Accessed 5 August 2026},
  url    = {https://maplibre.org/maplibre-style-spec/}
}

@misc{mapbox_vector_tile_spec,
  title  = {Mapbox Vector Tile Specification},
  author = {{Mapbox}},
  note   = {Accessed 5 August 2026},
  url    = {https://github.com/mapbox/vector-tile-spec}
}

@misc{osm_copyright,
  title  = {Copyright and License},
  author = {{OpenStreetMap Foundation}},
  note   = {Accessed 5 August 2026},
  url    = {https://www.openstreetmap.org/copyright}
}

@misc{osm_tile_policy,
  title  = {Tile Usage Policy},
  author = {{OpenStreetMap Foundation}},
  note   = {Accessed 5 August 2026},
  url    = {https://operations.osmfoundation.org/policies/tiles/}
}

@misc{wcag22,
  title  = {Web Content Accessibility Guidelines 2.2},
  author = {{World Wide Web Consortium}},
  note   = {Accessed 5 August 2026},
  url    = {https://www.w3.org/TR/WCAG22/}
}