SDK Maps pour le web

Ce que c’est

Le SDK Maps de N-Ways pour le web est une fine couche au-dessus de MapLibre GL JS, la bibliothèque cartographique open source. Il vous donne une carte MapLibre avec le style hébergé, les tuiles vectorielles et les polices de N-Ways, la mention OpenStreetMap, et votre clé d’API sur chaque requête, ainsi que :

• un client pour les API N-Ways : géocodage, codes postaux, saisie semi-automatique, lieux, itinéraires, matrice d’itinéraires, tarifs de course et trafic ;
• un champ de recherche qui propose des adresses, des codes postaux et des lieux pendant la saisie ;
• des adresses de cartes statiques pour les images dans les e-mails et les reçus.

Tout ce que MapLibre sait faire (marqueurs, popups, couches GeoJSON, mouvements de caméra, événements) fonctionne sur la carte qu’il vous donne.

Le charger

Dans une page web, sans rien d’autre

La version autonome inclut MapLibre GL JS, un seul import suffit donc :

<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <link rel="stylesheet" href="https://nways.ng/sdk/v1/maplibre-gl.css" />
    <style>body { margin: 0 } #map { height: 100vh }</style>
  </head>
  <body>
    <div id="map"></div>
    <script type="module">
      import { createMap } from 'https://nways.ng/sdk/v1/nways-maps.standalone.js'
      const map = createMap({ container: 'map', key: 'VOTRE_CLE_API', center: [7.4951, 9.0579], zoom: 12 })
    </script>
  </body>
</html>

Avec npm et un bundler

Avec Vite, webpack, Next.js et les autres bundlers, MapLibre GL JS 6 et pmtiles 4 sont des dépendances pairs (peer dependencies), pour que votre application n’en garde qu’une copie de chacun :

npm install @nways/maps maplibre-gl@6 pmtiles@4

import 'maplibre-gl/dist/maplibre-gl.css'
import { createMap } from '@nways/maps'

const map = createMap({ container: 'map', key: import.meta.env.VITE_NWAYS_KEY, center: [3.3792, 6.5244], zoom: 12 })

Sans npm, importez https://nways.ng/sdk/v1/nways-maps.js (il importe maplibre-gl et pmtiles par leur nom, pour une import map ou un bundler), ou copiez ses quatre fichiers (nways-maps.js, style.js, services.js, autocomplete.js) dans votre projet. Les types sont à côté (nways-maps.d.ts).

Créer une carte

createMap(options) renvoie une Map MapLibre. Elle accepte les options de carte de MapLibre, et en plus :

Chaque createMap lit le style hébergé une fois : c’est un chargement de carte pour la facturation. Les déplacements et les zooms sont gratuits. Si le style hébergé n’est pas accessible (un problème de réseau), la carte se rabat d’elle-même sur le style intégré.

Styles hébergés

Le SDK utilise https://nways.ng/maps/v1/styles/streets-light.json et streets-dark.json. Vous pouvez les utiliser sans le SDK, dans n’importe quelle carte MapLibre : styleUrl() donne l’adresse avec votre clé.

import * as maplibregl from 'maplibre-gl'
import { Protocol } from 'pmtiles'
import { styleUrl, withKey } from '@nways/maps'

maplibregl.addProtocol('pmtiles', new Protocol().tile)
const key = 'VOTRE_CLE_API'
new maplibregl.Map({
  container: 'map',
  style: styleUrl({ key, theme: 'dark', lang: 'fr' }),
  // Les tuiles et les polices ont aussi besoin de la clé.
  transformRequest: (url) => ({ url: withKey(url, key) }),
  center: [1.2228, 6.1319],
  zoom: 12,
})

Cartes sombres et libellés en français

import { createMap, setTheme } from '@nways/maps'

const map = createMap({ container: 'map', key: 'VOTRE_CLE_API', lang: 'fr', center: [2.4183, 6.3654], zoom: 12 })

// Suivre le réglage clair ou sombre du téléphone.
const dark = matchMedia('(prefers-color-scheme: dark)')
const follow = () => setTheme(map, dark.matches ? 'dark' : 'light')
dark.addEventListener('change', follow)
follow()

Marqueurs et popups

Le SDK exporte MapLibre sous le nom maplibregl, la version autonome n’a donc besoin d’aucun autre import :

import { createMap, maplibregl } from 'https://nways.ng/sdk/v1/nways-maps.standalone.js'

const map = createMap({ container: 'map', key: 'VOTRE_CLE_API', center: [3.3515, 6.6018], zoom: 15 })
new maplibregl.Marker({ color: '#0b7a3e' })
  .setLngLat([3.3515, 6.6018])
  .setPopup(new maplibregl.Popup().setText('Point d’enlèvement : rond-point d’Allen Avenue'))
  .addTo(map)

Appeler les API

createClient({ key }) renvoie un objet avec une méthode par API. Les points peuvent s’écrire { lat, lng } ou [lng, lat] ; les réponses sont le JSON des API.

Les erreurs lèvent une ApiError avec status, reason et retryAfter. Erreurs

Un itinéraire sur la carte

Les tracés d’itinéraire arrivent en GeoJSON, prêts pour une couche de carte :

import { createClient, createMap } from '@nways/maps'

const key = 'VOTRE_CLE_API'
const map = createMap({ container: 'map', key, center: [3.37, 6.53], zoom: 11 })
const nways = createClient({ key })

const { routes } = await nways.route({
  origin: { lat: 6.6018, lng: 3.3515 },
  destination: { lat: 6.4541, lng: 3.3947 },
  mode: 'okada',
})

map.on('load', () => {
  map.addSource('route', { type: 'geojson', data: { type: 'Feature', properties: {}, geometry: routes[0].geometry } })
  map.addLayer({ id: 'route', type: 'line', source: 'route', layout: { 'line-cap': 'round', 'line-join': 'round' }, paint: { 'line-color': '#1a73e8', 'line-width': 6 } })
})

Un champ de recherche

attachAutocomplete(input, options) transforme n’importe quel <input> en champ de recherche avec les suggestions de N-Ways, la navigation au clavier et des libellés pour les lecteurs d’écran. Une recherche, de la première lettre jusqu’au choix, compte pour une session de saisie semi-automatique.

<label for="address">Adresse de livraison</label>
<input id="address" placeholder="Rue, code postal ou lieu" />
<script type="module">
  import { attachAutocomplete, createMap } from 'https://nways.ng/sdk/v1/nways-maps.standalone.js'

  const key = 'VOTRE_CLE_API'
  const map = createMap({ container: 'map', key })
  attachAutocomplete(document.getElementById('address'), {
    key,
    near: { lat: 6.5244, lng: 3.3792 },
    onSelect: (place) => map.flyTo({ center: place.location.coordinates, zoom: 17 }),
  })
</script>

Changez son apparence avec des variables CSS sur la page : --nways-ac-bg, --nways-ac-fg, --nways-ac-border, --nways-ac-active, --nways-ac-muted.

Votre propre style

buildStyle({ key, theme, lang }) renvoie le style intégré du SDK sous forme d’objet de style MapLibre simple. Changez les couleurs ou ajoutez des couches avant de le passer vous-même à MapLibre, ou partez de zéro avec l’API Tuiles.

import { buildStyle, createMap } from '@nways/maps'

const style = buildStyle({ key: 'VOTRE_CLE_API' })
style.layers.find((l) => l.id === 'water').paint['fill-color'] = '#5aa9d6'
createMap({ container: 'map', key: 'VOTRE_CLE_API', style, center: [-0.187, 5.6037], zoom: 12 })

Attribution

Le coin de la carte affiche N-Ways · © OpenStreetMap contributors · Protomaps. Laissez-le visible : la licence d’OpenStreetMap exige la mention partout où ses données sont affichées. Vous pouvez la rendre compacte (le bouton ⓘ de MapLibre), mais ne la cachez pas et ne la couvrez pas. Si vous passez votre propre style sans la mention, le SDK l’ajoute. Règles d’attribution

Android et iOS

Pour les applications natives, utilisez les SDK Maps Android et iOS : les mêmes styles hébergés sur MapLibre Native, avec l’identité de votre application envoyée pour la restriction de sa clé.

Licences

@nways/maps est open source sous licence Apache 2.0 (Apache-2.0), Copyright 2026 N-WAYS LIMITED ; le paquet inclut les fichiers LICENSE et NOTICE. La licence couvre uniquement le code : les cartes et les données de N-Ways restent © les contributeurs d’OpenStreetMap sous l’Open Database Licence (ODbL), avec la mention affichée partout où elles apparaissent.

La version autonome inclut MapLibre GL JS (BSD 3-Clause), pmtiles (BSD 3-Clause) et fflate (MIT) ; leurs licences se trouvent dans LICENSES.txt, à côté.