Add an uploaded raster tileset in OpenLayers

Overview

This guide shows how to add an uploaded raster tileset in OpenLayers through TileJSON.

If your tileset starts as an MBTiles or PMTiles file, upload it through the console first. See Upload Data for the full upload workflow, then return with the tileset Id and API key from API Keys & Access.

The example uses mappinest.countries-raster as the sample uploaded raster tileset. It fetches TileJSON first, then uses the returned raster tile template and max zoom to create an OpenLayers XYZ source.

For production, replace mappinest.countries-raster with your own tileset Id from the console. Use the Raster Tiles API page for the direct XYZ tile URL and raster endpoint details.

Tiles API raster tiles in OpenLayers

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8" />
  <meta name="viewport" content="width=device-width, initial-scale=1" />
  <title>Mappinest raster TileJSON with OpenLayers</title>
  <link href="https://unpkg.com/ol@10.9.0/ol.css" rel="stylesheet" />
  <script src="https://unpkg.com/ol@10.9.0/dist/ol.js"></script>
  <script src="https://unpkg.com/ol-mapbox-style@13.4.1/dist/olms.js"></script>
  <style>
    body { margin: 0; }
    #map { height: 100vh; width: 100vw; }
  </style>
</head>
<body>
  <div id="map"></div>
  <script>

    const apiKey = 'YOUR_MAPPINEST_KEY';

    async function initMap() {
      // Fetch TileJSON first, then use the returned raster tile template to create the OpenLayers source.
      const tilejson = await fetch(
        `https://api.mappinest.com/v1/tiles/mappinest.countries-raster.json?key=${apiKey}`
      ).then((response) => response.json());
      const tilesUrl = tilejson.tiles?.[0];
      const tileMaxZoom = tilejson.maxzoom ?? 14;

      if (!tilesUrl) {
        throw new Error('TileJSON did not return a tile URL.');
      }

      const map = new ol.Map({
        target: 'map',
        view: new ol.View({
          center: ol.proj.fromLonLat([0, 0]),
          zoom: 1
        })
      });

      // Apply the Mappinest map style before adding the uploaded tileset layer.
      await window.olms.apply(
        map,
        `https://api.mappinest.com/v1/styles/light/style.json?key=${apiKey}`
      );

      map.addLayer(new ol.layer.Tile({
        source: new ol.source.XYZ({
          url: tilesUrl,
          maxZoom: tileMaxZoom,
          crossOrigin: 'anonymous'
        })
      }));
    }

    initMap();
  </script>
</body>
</html>

import { useEffect, useRef } from 'react';
import Map from 'ol/Map';
import View from 'ol/View';
import TileLayer from 'ol/layer/Tile';
import XYZ from 'ol/source/XYZ';
import { fromLonLat } from 'ol/proj';
import { apply } from 'ol-mapbox-style';
import 'ol/ol.css';

const apiKey = 'YOUR_MAPPINEST_KEY';

export default function MappinestOpenLayersRasterTilesMap() {
  const containerRef = useRef<HTMLDivElement | null>(null);
  const mapRef = useRef<Map | null>(null);

  useEffect(() => {
    if (!containerRef.current || mapRef.current) return;

    let cancelled = false;

    async function initMap() {
      // Fetch TileJSON first, then use the returned raster tile template to create the OpenLayers source.
      const tilejson = await fetch(
        `https://api.mappinest.com/v1/tiles/mappinest.countries-raster.json?key=${apiKey}`
      ).then((response) => response.json());
      if (cancelled || !containerRef.current) return;

      const tilesUrl = tilejson.tiles?.[0];
      const tileMaxZoom = tilejson.maxzoom ?? 14;

      if (!tilesUrl) {
        throw new Error('TileJSON did not return a tile URL.');
      }

      const map = new Map({
        target: containerRef.current,
        view: new View({
          center: fromLonLat([0, 0]),
          zoom: 1
        })
      });

      mapRef.current = map;

      // Apply the Mappinest map style before adding the uploaded tileset layer.
      await apply(
        map,
        `https://api.mappinest.com/v1/styles/light/style.json?key=${apiKey}`
      );

      map.addLayer(new TileLayer({
        source: new XYZ({
          url: tilesUrl,
          maxZoom: tileMaxZoom,
          crossOrigin: 'anonymous'
        })
      }));
    }

    void initMap();

    return () => {
      cancelled = true;
      mapRef.current?.setTarget(undefined);
      mapRef.current = null;
    };
  }, []);

  return <div ref={containerRef} style={{ height: 420, width: '100%' }} />;
}

URL patterns used in this example

The bold parameters are the values you replace. Prefer TileJSON as the integration request so the raster tile template and zoom metadata stay behind one URL.

Use case	URL pattern	Docs
Tileset TileJSON	`https://api.mappinest.com/v1/tiles/{tilesetId}.json?key=YOUR_KEY`	TileJSON
Direct raster tile URL	`https://api.mappinest.com/v1/tiles/{tilesetId}/{z}/{x}/{y}.{format}?key=YOUR_KEY`	Raster Tiles API
Map style	`https://api.mappinest.com/v1/styles/{styleId}/style.json?key=YOUR_KEY`	StyleJSON

Get your free API key in API Keys & Access, then replace YOUR_KEY in the example.

Common errors

Symptom	What to check
Raster layer is blank	Open the TileJSON URL and confirm the `tiles` array contains a raster tile template.
Tiles appear at the wrong zoom	Check `minzoom`, `maxzoom`, and tile bounds in the TileJSON response.
Requests return 403	Check API key restrictions and allowed domains in API Keys & Access.

Overview

URL patterns used in this example

Common errors

What to read next