BeMap JavaScript API — Developer Guide

▶️ Run the demo now: npm install then npm start → builds the library and opens the dashboard at http://localhost:8080/examples/. 🧪 Tests: npm test · 📦 Build only: npm run build

Just want to USE the SDK (not develop it)? See the distribution README.github.md and INSTALL.md. To publish it online: DEPLOY.md.

BeMap JS API is a JavaScript SDK for BeNomad's mapping and geolocation platform — a unified, engine-agnostic API over MapLibre GL v5, Leaflet 1.9, and OpenLayers v10, plus services for routing, geocoding, autocomplete, isochrone, charging stations, and EV routing.

Quick start

// 1. Create a context
var ctx = new bemap.Context({
    "login": "<your account>",
    "password": "<your password>",
    "secure": true,
    "host": "bemap.benomad.com"
});

// 2. Create a map (OpenLayers or Leaflet)
var map = new bemap.OlMap(ctx, "map-div").defaultLayers().move(2.35, 48.85, 12);

// 3. Add a marker
var marker = new bemap.Marker(new bemap.Coordinate(2.35, 48.85), {
    icon: new bemap.Icon({
        src: "marker.svg",
        anchorX: 0.5,
        anchorY: 1,
        anchorXUnits: "fraction",
        anchorYUnits: "fraction"
    })
});
map.addMarker(marker);

Environments. The quick start uses production (bemap.benomad.com). For integration testing / validation use bemap-preprod.benomad.com (preprod) or bemap-beta.benomad.com (beta) — pair with the matching tilesHost (mptiles-api.benomad.net / -preprod / -beta) when using BeNomad Tiles.

Features

Map display with MapLibre GL (bemap.MapLibreMap), OpenLayers (bemap.OlMap), or Leaflet (bemap.LeafletMap)
BeNomad Tiles — GPU vector basemap (PMTiles) with 3D buildings, terrain, and globe (MapLibre)
Tile performance & robustness — 200-slice reads that the browser HTTP-caches natively (no Service Worker needed), a self-healing tile cache, and a per-request timeout/retry gate — all parametrable
Archive-rebuild survival (v2.0.1) — per-map ?v= version tokens (auto-discovered from /api/maps) + an ETag guard: a tileset republished under the same name never blanks the map, even in tabs already open — see docs/browser-cache.md
Credential-less browser mode (v2.0.2) — the proxy option routes services, WMS and the tiles login through your own server, so no BeMap login/password ever reaches the browser (tile bytes still go direct) — see docs/integration-proxy.md
Tile authentication — configurable wire mode (HttpOnly cookie by default / X-Session-Token header / ?token=), with proactive JWT renewal
Markers with custom icons, text labels, clustering, and drag support
Polylines, Polygons, Circles with custom styling
Popups with HTML content
Routing with multi-stop, alternative routes, and route sheets
EV routing with charging station integration
Isochrone analysis (reachability zones)
Geocoding and reverse geocoding
Address autocomplete
WMS layers (raster) with GetFeatureInfo support
Event system for map and geometry interactions

Installation

See INSTALL.md for setup instructions.

Project structure

src/                   Source files (JS modules)
src-test/              Unit tests (Jasmine/Karma)
dist/                  Built distribution files
docs/                  Reference documentation
examples/              Interactive examples and guides
lib/                   Third-party libraries (installed via bower)

Build

Install dependencies, then build the distribution files:

npm install
bower install
npx grunt

The generated files are written to dist/.

Running tests

npx grunt test

Examples

One command builds the library, serves + opens the dashboard, and live-reloads the browser on every change:

npx grunt dev          # build + serve + open + LIVE-RELOAD at http://localhost:8080/examples/
# npx grunt serve      # serve only — no build, no reload (dist/ must already be built)
# npx grunt serve --port=9000

With grunt dev running: edit anything under examples/ and the page refreshes automatically; edit library source under src/ and the bundle rebuilds, then the page refreshes. npm start is an alias for npx grunt dev.

grunt alone only builds into dist/ — it does not serve, so the page won't appear or refresh. Use grunt dev (or any static server, e.g. npx http-server -p 8080, then open http://localhost:8080/examples/).

Dev environment (local only). When the dashboard runs on localhost (or file://), the Credentials picker offers a fourth entry — Dev (local only) → bemap-dev.benomad.org + mptiles-api-dev.benomad.net. It never appears on a deployed site: examples/context.js adds it only when location.hostname is local, and the env resolver ignores unknown saved keys.

Version

2.0.0

License

See LICENSE.md

Home