Verify a Planisfy environment, render a published style with MapLibre, and follow the path to publishing your own map.

Quickstart

This guide takes you from a reachable Planisfy API to a map rendered in the browser. By the end, you will have:

verified the API origin,
obtained and inspected a published style URL,
rendered that style with MapLibre GL JS, and
identified the next steps for publishing your own data or calling authenticated service APIs.

Before you begin

You need access to a Planisfy environment and at least one published style.

In managed Planisfy, open Console and copy the stable or versioned URL from a published style.
In an existing self-hosted installation, use any style already published through Console.
For a new local self-hosted installation, start with the demo-data path in Docker Compose self-hosting.

If you do not have a published style yet, continue to publish your first map after verifying the environment.

1. Choose the API origin

Use the origin for your environment:

Environment	API origin
Managed production	`https://api.planisfy.com`
Local Docker Compose	`http://localhost:4000`
Portless local development	`https://api.planisfy.localhost`
Self-hosted deployment	Your public API domain

The examples below use http://localhost:4000. Replace it with your API origin.

Verify that the API is reachable:

curl -i http://localhost:4000/health

A self-hosted environment can report degraded optional services while the API and Console remain available. Use detailed health and preflight before debugging a client:

curl http://localhost:4000/health/detailed
curl http://localhost:4000/setup/preflight

2. Get a published style URL

Planisfy exposes MapLibre-compatible stable and version-pinned style URLs:

http://localhost:4000/styles/v1/{owner}/{style}
http://localhost:4000/styles/v1/{owner}/{style}@{version}

Use the stable URL when you want clients to follow the currently published version. Use a versioned URL when a client must remain pinned to immutable content.

For the local demo-data workflow, the default style is normally available at:

http://localhost:4000/styles/v1/planisfy/planisfy-streets-light-v1

If that URL is not available, confirm that demo data was installed and the default-map smoke path completed, or publish a style through Console.

3. Inspect the style before rendering it

Fetch the style directly:

curl -i http://localhost:4000/styles/v1/planisfy/planisfy-streets-light-v1

A successful response should contain MapLibre style JSON with a version, sources, and layers. Depending on the style, it may also contain glyphs and sprite URLs.

Those dependent URLs matter because MapLibre loads them after it loads the style. A style request can succeed while tiles, glyphs, or sprites still fail, so the browser network panel is part of the verification process.

4. Render the style with MapLibre

Save the following as index.html, replacing the style URL when needed:

<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <title>Planisfy MapLibre Quickstart</title>
    <link
      href="https://unpkg.com/maplibre-gl@4/dist/maplibre-gl.css"
      rel="stylesheet"
    />
    <style>
      html,
      body,
      #map {
        width: 100%;
        height: 100%;
        margin: 0;
      }
    </style>
  </head>
  <body>
    <div id="map"></div>
    <script src="https://unpkg.com/maplibre-gl@4/dist/maplibre-gl.js"></script>
    <script>
      const map = new maplibregl.Map({
        container: "map",
        style: "http://localhost:4000/styles/v1/planisfy/planisfy-streets-light-v1",
        center: [9.1829, 48.7758],
        zoom: 12
      });

      map.addControl(new maplibregl.NavigationControl(), "top-right");

      map.on("error", (event) => {
        console.error("MapLibre resource error", event.error ?? event);
      });
    </script>
  </body>
</html>

Serve the directory through a local HTTP server rather than opening the file directly. For example:

python3 -m http.server 8080

Then open http://localhost:8080.

5. Verify the complete request chain

When the map loads, the browser should request more than the style document:

style JSON
  -> TileJSON or source metadata
  -> vector tiles
  -> glyph ranges
  -> sprite metadata and image, when configured
  -> rendered map

Use the browser network panel to identify the first failing request.

Symptom	Check first
The style URL returns 404	Confirm the owner, style slug, and publication state.
The map is blank	Inspect TileJSON, tile URLs, and the underlying artifact.
Geometry renders but labels do not	Check the style `glyphs` URL and glyph service.
Symbol layers render without icons	Check sprite publication and sprite routes.
The browser reports CORS errors	Verify the public API origin and allowed Console/client origins.
The self-host stack is degraded	Inspect `/health/detailed` and `/setup/preflight` before changing the client.

For a deeper MapLibre integration guide, continue with Use MapLibre.

6. Call an authenticated service API

Geocoding, routing, elevation, and static map APIs require an API key or an authenticated Console session. Create a narrowly scoped key in Console, then send it through X-API-Key.

For example, when a Pelias-compatible service and dataset are configured:

curl "http://localhost:4000/geocoding/v1/forward?q=Stuttgart&limit=3" \
  -H "X-API-Key: pk_your_key_here"

If the request reports that geocoding is unavailable, verify the Pelias configuration and dataset rather than changing the API key. The Planisfy route can exist while its backing geographic dataset is not installed.

Review API key management, authentication, and error handling before integrating service APIs into an application.

7. Publish your first map

Once the environment and renderer are working, use this workflow to publish your own data:

Open Console and create or select an organization.
Create a tileset and upload or import source data.
Wait for processing to produce a publishable tileset version.
Publish the tileset and verify its TileJSON URL.
Create a style and add the tileset as a source.
Publish the style.
Copy its stable or versioned style URL into your MapLibre client.

Continue with:

For a self-hosted environment, also read Self-hosting overview so you understand which datasets and runtime services you are responsible for.

Quickstart

On this page