EN
Aller au contenu

Guide de démarrage

De zéro à une carte affichée en moins d'une minute. Le chronomètre démarre à npm i et s'arrête quand la carte s'affiche.

Ensuite, cette page est une petite application qui grandit : une carte, puis un lieu, puis un repère, puis un itinéraire, puis une allure bien à elle. Chaque étape est un fichier complet, chacune ajoute une ligne ou deux à la précédente, et chacune s'exécute réellement sur cette page : le code affiché à côté de chaque exemple est celui qui l'a produit.

Nouveau dans les API cartographiques? Rien de ce qui suit ne suppose que vous en avez déjà utilisé une, mais si un mot comme tuile, style ou isochrone vous échappe, le glossaire d'une minute de l'Aperçu définit les sept qui comptent.

Aucun compte n'est nécessaire pour suivre cette page. Tous les exemples ci-dessous fonctionnent avec une clé de démonstration publique, et la dernière section vous donne cette clé à coller dans votre propre fichier. Les extraits affichent key: "um_live_..." comme espace réservé : remplacez-la par la clé de démonstration pour les exécuter dès aujourd'hui, ou par la vôtre quand vous en aurez une. Les clés, les origines autorisées et l'allure d'une clé refusée sont décrites dans Authentification.

1. Installation

npm i @unmap/sdk

maplibre-gl vient comme dépendance de @unmap/sdk, donc il n'y a rien d'autre à installer pour une carte de base.

Si votre page n'a pas d'étape de compilation, chargez le même SDK depuis une balise de script :

<link rel="stylesheet" href="https://cdn.unmap.dev/sdk/0.13.0/unmap.css">
<div id="map" style="height: 400px"></div>
<script src="https://cdn.unmap.dev/sdk/0.13.0/unmap.js"></script>
<script>
  unmap.createMap({
    key: "um_live_...",
    container: "#map",
    center: [-114.0719, 51.0447],
    zoom: 11,
  });
</script>

C'est le fichier au complet. Le paquet transporte son propre MapLibre, donc il n'y a rien d'autre à ajouter ni rien à configurer.

Les paquets sont facultatifs. Chaque point de terminaison est du HTTPS et du JSON ordinaires, donc si vous n'êtes pas en JavaScript, ou préférez ne pas ajouter une dépendance, Appeler l'API directement couvre curl, fetch, Python et un MapLibre standard sans aucun code @unmap.

2. Ajoutez un conteneur

N'importe où dans votre page, donnez à la carte une boîte avec une hauteur :

<div id="map" style="height: 400px"></div>

La hauteur n'est pas décorative. Un conteneur sans hauteur affiche une carte de zéro pixel, MapLibre ne signale aucune erreur, et la page paraît simplement vide. C'est la première chose à vérifier quand rien ne s'affiche.

Dans votre entrée JavaScript ou CSS, importez la feuille de style de MapLibre depuis le paquet installé :

import "maplibre-gl/dist/maplibre-gl.css";

Sans bundler, liez le même fichier depuis votre HTML. Dans les deux cas, la feuille de style est servie depuis votre propre site, pas depuis un CDN tiers. Une réserve : avec la disposition stricte de pnpm, une dépendance transitive n'est pas importable depuis votre application, donc ajoutez-y maplibre-gl comme dépendance directe.

3. Affichez une carte

Deux instructions de code après l'installation. Voici le Hello World au complet, et il s'exécute ci-dessous :

résultat en direct
le code qui l’a produit
import { Unmap } from "@unmap/sdk";

const unmap = new Unmap({
  key: "um_live_...",
  container: "map",
  center: [-114.0719, 51.0447],
  zoom: 11,
});

Cela affiche un fond de carte de Calgary, l'arrière-plan sur lequel reposeront vos marqueurs et vos données. center et zoom disent où elle commence; style, mode et lang disent comment elle est dessinée. Aucun n'est obligatoire : sans eux, vous obtenez base en mode clair, avec les étiquettes dans la langue du lecteur.

center est [longitude, latitude], dans cet ordre. Toutes les coordonnées d'unmap le sont, et c'est l'erreur qui coûte le plus de temps aux débutants : la longitude est le nombre est-ouest, négatif au Canada. Inversez-les et la carte atterrit dans l'océan Indien.

résultat en direct
le code qui l’a produit
import { Unmap } from "@unmap/sdk";

const unmap = new Unmap({
  key: "um_live_...",
  container: "map",
  style: "base",
  mode: "light",
  lang: "fr",
  center: [-73.5673, 45.5017],
  zoom: 12,
});

Appuyez sur un contrôle ci-dessus et regardez l'extrait changer avec lui : chaque option que vous choisissez apparaît dans le code, et rien de ce que vous n'avez pas choisi ne s'y cache. Les neuf styles et les deux modes sont décrits dans l'API de cartes.

C'est la marque des 60 secondes. Tout ce qui suit est optionnel.

Si la carte ne finit jamais de charger

Un problème d'empaqueteur mérite d'être connu avant de vous coûter un après-midi, car il échoue en silence. Si votre carte affiche un rectangle gris et ne se dessine jamais (aucune erreur levée, aucune requête en échec dans le panneau réseau), ouvrez la console et cherchez ceci :

Failed to load module script: The server responded with a non-JavaScript MIME type of "text/html".

MapLibre GL JS 6 est uniquement ESM et analyse ses tuiles dans un web worker, qu'il charge comme un module. Il trouve ce worker par import.meta.url, et le guide de migration de MapLibre indique clairement que cette valeur ne traverse pas de façon fiable le graphe de modules d'un empaqueteur. Quand elle ne se résout pas, le worker ne démarre jamais, MapLibre n'analyse jamais de tuile, il n'en demande donc aucune, et la carte attend indéfiniment un événement de chargement qui ne peut pas arriver. Rien dans votre code n'est fautif, et rien dans votre code ne peut l'intercepter.

Le correctif tient en un appel, et MapLibre le demande à toute personne qui utilise un empaqueteur. Copiez le worker et le module qu'il importe hors du paquet, puis servez-les vous-même :

// scripts/copy-maplibre-worker.mjs
import { copyFileSync, mkdirSync } from "node:fs";
import { createRequire } from "node:module";
import path from "node:path";
 
const dist = path.join(path.dirname(createRequire(import.meta.url).resolve("maplibre-gl/package.json")), "dist");
const dest = path.join(process.cwd(), "public", "maplibre");
 
mkdirSync(dest, { recursive: true });
for (const file of ["maplibre-gl-worker.mjs", "maplibre-gl-shared.mjs"]) {
  copyFileSync(path.join(dist, file), path.join(dest, file));
}

Exécutez-le avant dev et avant build, puis pointez MapLibre vers les copies une seule fois, au-dessus de la première carte que vous créez :

import { maplibregl } from "@unmap/sdk";
 
maplibregl.setWorkerUrl("/maplibre/maplibre-gl-worker.mjs");

Copiez les deux fichiers. Le worker importe maplibre-gl-shared.mjs par un simple chemin relatif : ce fichier doit donc se trouver à côté du worker sous ce nom exact. Ne copier que le worker reproduit le même échec silencieux, une étape plus loin.

Next.js avec Turbopack est le cas où la plupart des gens le rencontrent (maplibre-gl-js#8126), et c'est ce que unmap.dev exécute lui-même. Vite, webpack, esbuild, rspack et Rollup demandent le même appel avec leur propre chemin. Charger MapLibre directement depuis un CDN comme module n'a besoin de rien de tout cela : il résout le worker par lui-même. La version en balise de script ci-dessus non plus : elle livre son propre worker et l'indique à MapLibre avant la création de votre première carte.

4. Trouvez un lieu

.geocoder se trouve sur la même instance, et fonctionne avec ou sans carte :

résultat en direct
le code qui l’a produit
import { Unmap } from "@unmap/sdk";

const unmap = new Unmap({ key: "um_live_..." });

const results = await unmap.geocoder.search("Calgary Tower", { limit: 3 });

Chaque appel retourne un tableau de résultats. Chaque résultat comporte id, name, layer, lng, lat, une table names quand le lieu porte des noms dans plus d'une langue, et un address structuré quand il en existe un. Les résultats de recherche et de saisie semi-automatique ajoutent un score; les résultats par catégorie ajoutent une distance en mètres. La forme complète est décrite dans l'API de géocodage.

Les trois autres recherches suivent la même forme :

// Saisie semi-automatique (se déclenche à chaque frappe)
const hints = await unmap.geocoder.autocomplete("rue sainte-cath", {
  lang: "fr",
  limit: 5,
});
 
// Recherche par catégorie : les pharmacies les plus proches d'un point, triées par distance
const nearby = await unmap.geocoder.nearby("pharmacie", {
  near: [-114.07, 51.05],
  limit: 5,
});
 
// Géocodage inverse d'une coordonnée
const here = await unmap.geocoder.reverse(-114.07, 51.05);

Le géocodage seul

Sans carte, sans SDK complet : @unmap/geocoding est un client autonome pour ces quatre mêmes points de terminaison, sans dépendance à MapLibre.

npm i @unmap/geocoding
import { Geocoder } from "@unmap/geocoding";
 
const geocoder = new Geocoder({ key: "um_live_..." });
 
const results = await geocoder.search("Iqaluit");
const hints = await geocoder.autocomplete("yellowkni", { limit: 5 });
const cafes = await geocoder.nearby("café", {
  near: [-73.5673, 45.5017],
  radius: 1000,
});
const here = await geocoder.reverse(-68.517, 63.749);

5. Placez le lieu sur la carte

Les étapes 3 et 4 réunies : géocodez une requête, puis déposez un repère MapLibre sur la réponse. unmap.map est la carte MapLibre GL, donc tout ce que l'API MapLibre sait faire à une carte, vous pouvez le faire à celle-ci.

résultat en direct
le code qui l’a produit
import { Unmap, maplibregl } from "@unmap/sdk";

const unmap = new Unmap({
  key: "um_live_...",
  container: "map",
  center: [-114.0719, 51.0447],
  zoom: 11,
});

const [place] = await unmap.geocoder.search("Calgary Tower");

new maplibregl.Marker({ color: "#FF3E9A" })
  .setLngLat([place.lng, place.lat])
  .setPopup(new maplibregl.Popup().setText(place.name))
  .addTo(unmap.map!);

6. Tracez un itinéraire

.router est la troisième chose offerte par la même instance. route() retourne la distance, la durée et une géométrie GeoJSON LineString que vous pouvez ajouter à la carte comme source :

résultat en direct
le code qui l’a produit
import { Unmap } from "@unmap/sdk";

const unmap = new Unmap({
  key: "um_live_...",
  container: "map",
  center: [-114.03, 51.07],
  zoom: 11,
});

const route = await unmap.router.route([-114.0719, 51.0447], [-113.9871, 51.0899], { mode: "auto" });

unmap.map!.on("load", () => {
  unmap.map!.addSource("route", {
    type: "geojson",
    data: { type: "Feature", properties: {}, geometry: route.geometry },
  });
  unmap.map!.addLayer({
    id: "route-line",
    type: "line",
    source: "route",
    layout: { "line-cap": "round", "line-join": "round" },
    paint: { "line-color": "#FF3E9A", "line-width": 3 },
  });
});

Ici aussi les coordonnées sont [lng, lat]. distanceMeters et durationSeconds sont exactement ce que les noms indiquent : des mètres et des secondes, pas des kilomètres ou des minutes. isochrone() répond à l'autre question d'itinéraire, jusqu'où puis-je aller dans un temps donné, et retourne cette zone sous forme de FeatureCollection GeoJSON :

const bands = await unmap.router.isochrone([-114.07, 51.05], {
  minutes: [10, 20],
});

minutes est obligatoire, accepte jusqu'à quatre valeurs, et chacune doit valoir au plus 120.

Les itinéraires seuls

Sans carte, sans SDK complet : @unmap/routing est un client autonome pour ces deux mêmes points de terminaison.

npm i @unmap/routing
import { Router } from "@unmap/routing";
 
const router = new Router({ key: "um_live_..." });
 
const route = await router.route([-114.07, 51.05], [-113.99, 51.05], {
  mode: "auto",
});
console.log(route.distanceMeters, route.durationSeconds);
 
const bands = await router.isochrone([-114.07, 51.05], {
  minutes: [10, 20],
  mode: "pedestrian",
});

mode vaut 'auto' | 'car' | 'bicycle' | 'pedestrian' | 'truck' | 'transit', aussi bien dans les types publiés de @unmap/routing que sur la passerelle (car est le même profil automobile que auto; voir l'API d'itinéraires pour le profil de véhicule camion). La valeur par défaut est 'auto'.

7. Donnez-lui une allure bien à elle

La dernière option est theme : un code produit par le créateur de thèmes qui redessine la carte dans les couleurs que vous avez choisies. C'est une donnée, pas une feuille de style : il voyage dans la même requête que le reste, et il a priorité sur style.

résultat en direct
le code qui l’a produit
import { Unmap } from "@unmap/sdk";

const unmap = new Unmap({
  key: "um_live_...",
  container: "map",
  theme: "u4e",
  center: [-114.0719, 51.0447],
  zoom: 12,
});

u4e est un code court désignant un thème prédéfini livré avec unmap; le créateur exporte aussi de longs codes ut1. pour un thème que vous avez composé vous-même. Les deux se passent dans la même option. L'API de cartes décrit ce qu'un thème peut transporter.

Erreurs

Les clients lèvent une exception sur toute réponse non 2xx. GeocoderError et RouterError portent toutes deux le status HTTP, ce qui permet de brancher dessus :

import { GeocoderError } from "@unmap/sdk";
 
try {
  await unmap.geocoder.search("");
} catch (e) {
  if (e instanceof GeocoderError && e.status === 400) {
    // la requête était mal formée; voir /fr/docs/reference/errors pour chaque code
  }
}

Utiliser une clé de démonstration

Vous voulez essayer avant d'obtenir une clé? La clé de démonstration publique est limitée en débit et sans danger à intégrer. C'est celle qu'utilise chaque exemple de cette page :

new Unmap({
  key: "um_test_793cf0c9cb8f4f5cf12bbdebdd96b59532b38876fbe5d14d",
  container: "map",
  center: [-68.517, 63.7467],
  zoom: 11,
});

Elle parle à la même passerelle que votre propre clé, https://api.unmap.dev; c'est la valeur par défaut, donc il n'y a aucune option gateway à définir. Comme la clé est partagée, elle peut atteindre la limite de débit aux moments d'affluence. Obtenez la vôtre dans le tableau de bord quand vous êtes prêt.

Prochaines étapes

  • Parcourez les Exemples pour une carte, une recherche ou un itinéraire en direct à copier.
  • Vous quittez Google Maps, Mapbox, HERE ou Esri? Commencez par Migrer.
  • Consultez l'Aperçu pour la référence complète des options et méthodes, et la liste des paquets.
  • Authentification pour les formes de clé, les origines autorisées, la séparation navigateur/serveur et ce que renvoie une clé refusée.
  • Appeler l'API directement si vous préférez vous passer des paquets ; l'API de cartes, l'API de géocodage et l'API d'itinéraires documentent chaque point de terminaison, paramètre et réponse.
  • Sur React ou Vue avec shadcn ? npx @unmap/cli create mon-app crée un projet avec carte, boîte de recherche et panneau d'itinéraire déjà en place, ou copiez-les dans un projet existant depuis le registre de composants.
  • Concevez votre propre cartographie sur /create et passez le code comme theme.