Maplibre Latlong Map and API Wrapper

A MapLibre GL JS wrapper with built-in Latlong authentication for maptiles and api suite.

• LLMap - A wrapper to add Latlong Maps layers to MapLibre GL JS.
• LLApi - A wrapper to access Latlong APIs link for document API Documentation

Installation

npm install maplibre-latlong-maps maplibre-gl

Peer dependency: maplibre-gl >= 3.0.0

Authentication

This library uses JWT-only authentication (v1.2.0+). Generate a JWT on your server using your client credentials, then pass it to the frontend.

{ jwt: 'your-jwt-token' }

If you do not have credentials to generate a JWT, please Sign Up to create an account.

Migrating from v1.0.0

In v1.2.0 client-credential authentication has been removed. If you were previously passing clientId and clientSecret directly then chnage to jwt as shown below

+ const llmap = new LLMap(
+   { jwt: 'your-server-generated-jwt' },
+   { container: 'map' }
+ );

What changed:

• clientId and clientSecret fields are depricated from LLMapAuth and LLApiAuth
• Auth is now a single { jwt: string } object
• Generate the JWT server-side using your credentials, then pass it to the client
• Token auto-refresh is no longer handled by the library.

Note: In v1.2 Auth - LLMap and LLApi uses different jwt avoid using same jwt for both instance

Depricated Auth in v1.2

- const llmap = new LLMap(
-   { clientId: 'xxx', clientSecret: 'yyy' },
-   { container: 'map' }
- );

Latlong Map Tiles

To access Latlong map tiles use LLMap or createLLMap with the examples below.

Option 1: Async Factory (recommended)

createLLMap returns a promise that resolves once the map is fully loaded. No callbacks needed.

import { createLLMap } from 'maplibre-latlong-maps';
import 'maplibre-latlong-maps/styles.css';

const llmap = await createLLMap(
  { jwt: 'your-jwt-token' },
  { container: 'map', latitude: 12.9716, longitude: 77.5946, zoom: 12 }
);

Option 2: Class with load callback

import { LLMap } from 'maplibre-latlong-maps';
import 'maplibre-latlong-maps/styles.css';

const llmap = new LLMap(
  { jwt: 'your-jwt-token' },
  { container: 'map', latitude: 12.9716, longitude: 77.5946, zoom: 12 }
);


// Map on-load Example
llmap.on('load', () => {
  llmap.instance.addSource('my-source', { type: 'geojson', data: geojson });
  llmap.instance.addLayer({ id: 'my-layer', type: 'circle', source: 'my-source' });

How to use MapLibre functions

llmap.instance.addSource('my-source', { type: 'geojson', data: geojson });
llmap.instance.addLayer({ id: 'my-layer', type: 'circle', source: 'my-source' });
llmap.instance.flyTo({ center: [77.5946, 12.9716], zoom: 14 });

Config Options

| Option | Type | Default | Description | |-----------|-----------------------|----------------|-------------------------------------| | container | string | HTMLElement | (required) | Element or ID to mount the map into | | latitude | number | 12.9716 | Map center latitude | | longitude | number | 77.5946 | Map center longitude | | zoom | number | 4 | Initial zoom level | | bearing | number | 0 | Map bearing in degrees | | pitch | number | 0 | Map pitch in degrees | | minZoom | number | 0 | Minimum zoom level | | maxZoom | number | 22 | Maximum zoom level | | styleUrl | string | (raster) | Custom MapLibre style URL | | baseUrl | string | apihub URL | Base URL for tile API |

LLMap API

| Member | Type | Description | |--------------|----------|--------------------------------------------------| | instance | property | The underlying MapLibre Map instance (after load) | | isReady | property | Whether the map has finished loading | | on('load') | method | Register a callback for when the map is ready | | destroy() | method | Remove the map and clean up | | logout() | method | Clear stored token + destroy map |

React Example

import { useEffect, useRef, useState } from 'react';
import { LLMap } from 'maplibre-latlong-maps';
import 'maplibre-latlong-maps/styles.css';

function MapView({ token }: { token: string }) {
  const containerRef = useRef<HTMLDivElement>(null);
  const llmapRef = useRef<LLMap | null>(null);
  const [mapReady, setMapReady] = useState(false);

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

    const llmap = new LLMap(
      { jwt: token },
      { container: containerRef.current, latitude: 12.9716, longitude: 77.5946, zoom: 10 }
    );

    llmap.on('load', () => {
      llmapRef.current = llmap;
      setMapReady(true);
      llmap.instance.on('click', (e) => console.log('Clicked:', e.lngLat));
    });

    return () => {
      llmap.destroy();
      llmapRef.current = null;
    };
  }, [token]);

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

LLApi

Sample code below to intialize and call Geocode API

import { LLApi } from 'maplibre-latlong-maps';

const api = new LLApi({ jwt: 'your-jwt-token' });
const location = await api.geocode('Indiranagar, Bangalore');

Available Methods

| Method | Description | |--------|-------------| | getToken() | Get current auth token (throws if expired) | | logout() | Clear stored token | | geocode(address, accuracyLevel?) | Address to coordinates | | reverseGeocode(lat, lng, details?) | Coordinates to address | | autoComplete(query, locationBias?) | Text-based location search | | autoSuggest(query, lat, lng, strictBias?) | Location-biased place search | | landmarks(lat, lng) | Nearby landmarks for a coordinate | | directions(origin, destination, headers?) | Driving route between two points | | distanceMatrix(origins, destinations) | Distance/duration matrix | | pincode(pincode) | Pincode information | | isochrone(distanceLimit, lat, lng) | Reachability polygon | | geofenceCreate(geojson, name?) | Create a geofence | | geofenceUpdate(geofenceId, geojson, name?) | Update a geofence | | geofenceContains(geofenceId, lat, lng, buffer?) | Point-in-geofence check | | geofenceDetails(geofenceId) | Get geofence details | | geofenceDelete(geofenceId) | Delete a geofence | | snapToRoad(coordinates) | Snap coordinates to nearest road | | addlyser(address) | Break address into structured parts | | nearestCities(address, limit?) | Find nearest cities | | votingConstituencySearch(address) | Voting constituency lookup | | trips(path, roundTrip?) | Optimized route ordering | | pointOfInterest(lat, lng, category) | POI search by category |

For detailed information about response formats, status codes, and messages, please refer to our API Documentation.

Available imports

// Core
import { LLMap, createLLMap, LLApi } from 'maplibre-latlong-maps';
import type { LLMapAuth, LLMapConfig, LLApiAuth, LLApiConfig } from 'maplibre-latlong-maps';

// Utilities
import { isTokenExpired } from 'maplibre-latlong-maps';
import { validateBBox, clampZoom, clampLatitude, clampLongitude } from 'maplibre-latlong-maps';

// MapLibre GL re-exports (use these to avoid duplicate instances)
import { LngLatBounds, LngLat, Marker, Popup, NavigationControl, GeolocateControl } from 'maplibre-latlong-maps';

// Types
import type { MapLibreConfig, ViewState, BBox } from 'maplibre-latlong-maps';

// Styles
import 'maplibre-latlong-maps/styles.css';

License

MIT