Quick Start Guide

This guide walks you through integrating SimVector map tiles into your application using MapLibre GL JS and the official protocol wrapper.

Prerequisites

Before getting started, ensure you have:

• A SimVector API Key (located in your SimVector Console under Community Settings)
• An active Paid SimVector Community Subscription
• A vector tile map rendering client (e.g., MapLibre GL JS or MapLibre Leaflet Plugin)

Session Authentication

SimVector Map Tiles use session-based authentication. Your application exchanges an API key for a short-lived JSON Web Token (JWT), which authorizes access to map tiles and your subscribed datasets.

To mint a session token, send a GET request to:

GET https://simvector.net/api/v1/auth/jwt?api_key={YOUR_API_KEY}

The returned JWT is used to authenticate subsequent tile requests via standard Bearer token authorization (Authorization: Bearer <JWT>).

WARNING

Never expose your SimVector API key in client-side code. Always wrap token minting behind an authenticated endpoint on your own server.

MapLibre Integration

The @simvector/maplibre-protocol package automates token acquisition, renewal, and simvector:// resource resolution.

1. Install the Package

npm i @simvector/maplibre-protocol

2. Configure the Protocol Handler

import maplibregl from 'maplibre-gl';
import 'maplibre-gl/dist/maplibre-gl.css';
import { registerSimVectorProtocol } from '@simvector/maplibre-protocol';
import mapStyle from './map_symbology';

// 1. Register the protocol handler
registerSimVectorProtocol(maplibregl, {
  getToken: async () => {
    // Call your server-side endpoint where your API key is secured
    const response = await fetch('/api/simvector/token', { method: 'POST' });
    if (!response.ok) {
      throw new Error('Failed to retrieve SimVector map session token');
    }
    const data = await response.json();
    return data.token; // Must return a valid JWT string
  },
});

// 2. Initialize the map using simvector:// URIs in your style
const map = new maplibregl.Map({
  container: 'map',
  style: mapStyle, // Compiled style document referencing simvector:// tile sources
  center: [139.6917, 35.6895], // Tokyo
  zoom: 8,
});

Next Steps

Once your tile sources are set to simvector:// endpoints and your symbology style is loaded, the map renderer will automatically handle authentication and vector rendering. You can now adjust layer styling or add additional layers as needed.