Comment ajouter des cartes interactives à votre site web | Tutoriel

Tableaux de bord logistiques, annonces immobilières, applications de livraison de repas : tous ont un point commun, une carte. Si votre site n'en a pas encore, vous privez vos utilisateurs d'un contexte précieux. Une carte leur permet de comprendre d'un coup d'œil une localisation, une proximité et des relations spatiales.

Ce tutoriel vous montre comment ajouter une carte entièrement interactive à n'importe quel projet JavaScript. Vous commencerez par afficher une carte, puis vous ajouterez des marqueurs et des popups, brancherez la recherche d'adresses sur la Geocoding API et terminerez par un composant React prêt pour la production, qui s'intègre proprement dans Next.js.

Voici ce que vous aurez construit à la fin :

• Une carte vectorielle dynamique, authentifiée avec votre clé API
• Des marqueurs cliquables avec un contenu de popup personnalisé
• Une fonction de recherche d'adresses fondée sur le géocodage
• Un composant React réutilisable, avec un nettoyage correct et une gestion du SSR de Next.js
• Une checklist d'optimisations de performance pour la production

Prérequis

Avant de commencer, vérifiez que vous disposez des éléments suivants :

• Une clé API MapAtlas (inscription gratuite, sans carte bancaire). Cette clé unique authentifie tous les services MapAtlas : tuiles, géocodage et calcul d'itinéraires.
• Un projet JavaScript. HTML simple, React, Vue ou Svelte : tout fonctionne.
• Node.js 18+ si vous installez via npm.

Étape 1 : installer le SDK MapAtlas

Ajoutez le SDK à votre projet avec npm :

npm install @mapmetrics/mapmetrics-gl

Si vous travaillez plutôt sur une page HTML simple, ajoutez les liens CDN dans votre <head> :

<link
  rel="stylesheet"
  href="https://unpkg.com/@mapmetrics/mapmetrics-gl/dist/mapmetrics-gl.css"
/>
<script src="https://unpkg.com/@mapmetrics/mapmetrics-gl/dist/mapmetrics-gl.js"></script>

N'oubliez pas l'import CSS. Sans lui, les contrôles de la carte et les popups s'affichent sans style. Ils fonctionnent, mais leur rendu visuel est cassé.

Étape 2 : créer un conteneur pour la carte

Le SDK remplit l'élément que vous lui indiquez : il vous faut donc une <div> avec une hauteur explicite. C'est l'erreur de configuration la plus fréquente : si le conteneur a height: 0, la carte s'initialise mais reste invisible.

<div id="map" style="width: 100%; height: 500px;"></div>

Une valeur fixe en pixels ou une unité de viewport (100vh, 50vh) conviennent toutes les deux. Les hauteurs en pourcentage ne fonctionnent que si l'élément parent a lui aussi une hauteur définie.

Étape 3 : afficher votre première carte interactive

Trois lignes de configuration suffisent : un conteneur, une URL de style contenant votre clé API et une position de départ.

import mapmetricsgl from '@mapmetrics/mapmetrics-gl';
import '@mapmetrics/mapmetrics-gl/dist/mapmetrics-gl.css';

const map = new mapmetricsgl.Map({
  container: 'map',
  style: 'https://gateway.mapmetrics-atlas.net/styles/?fileName=YOUR_STYLE_ID/style.json&token=YOUR_API_KEY',
  center: [4.9041, 52.3676], // [longitude, latitude]
  zoom: 12,
});

Ouvrez la page : vous voyez une carte vectorielle que vous pouvez faire glisser, zoomer à la molette et pincer pour naviguer. Les tuiles se chargent à la demande depuis les serveurs MapAtlas, sans lourd téléchargement initial.

Choisir un style de carte

Les styles de carte se trouvent dans votre compte. Dans le portail MapMetrics, ouvrez Styles, créez ou personnalisez un style, enregistrez-le et copiez son URL de style. Cette URL contient déjà votre token : elle se place donc directement dans l'option style. Gardez un style par rendu dont vous avez besoin, par exemple un style clair pour les applications généralistes et un style sombre pour les tableaux de bord, et passez de l'un à l'autre avec map.setStyle().

Gain rapide : utilisez un style sombre pour les interfaces d'administration et les outils utilisés dans des environnements peu éclairés. Beaucoup d'utilisateurs le préfèrent dans les pièces peu éclairées, et il fait ressortir les couches de données, comme les heatmaps et les tracés d'itinéraires, sur le fond de carte.

Étape 4 : ajouter des marqueurs et des popups à votre carte

Une carte sans marqueurs n'est qu'une image de fond. Les marqueurs transforment une vue statique en une interface avec laquelle vos utilisateurs peuvent interagir.

Un marqueur avec une popup

const popup = new mapmetricsgl.Popup().setHTML(`
  <strong>Amsterdam Central</strong>
  <p>Stationsplein, 1012 AB Amsterdam</p>
`);

new mapmetricsgl.Marker({ color: '#97C70A' })
  .setLngLat([4.9001, 52.3791])
  .setPopup(popup)
  .addTo(map);

Cliquez sur le marqueur : la popup s'ouvre. Vous pouvez y placer n'importe quel HTML, qu'il s'agisse d'adresses, de miniatures ou de boutons d'appel à l'action, selon les besoins de votre interface.

Afficher plusieurs marqueurs à partir de données

La plupart des applications réelles ont besoin de plus d'un repère. OnlyHere en est un exemple en production : ce guide quotidien des sorties à Londres place chaque événement sur une carte MapAtlas interactive, pour que vous puissiez parcourir le programme par lieu et par quartier. Parcourez un tableau et créez un marqueur pour chaque entrée :

const locations = [
  { name: 'Amsterdam', coords: [4.9041, 52.3676] },
  { name: 'Rotterdam', coords: [4.4777, 51.9244] },
  { name: 'Utrecht',   coords: [5.1214, 52.0907] },
];

locations.forEach(({ name, coords }) => {
  const popup = new mapmetricsgl.Popup().setHTML(`<strong>${name}</strong>`);
  new mapmetricsgl.Marker({ color: '#97C70A' })
    .setLngLat(coords)
    .setPopup(popup)
    .addTo(map);
});

Note sur les performances : les marqueurs HTML sont des éléments du DOM, donc quelques centaines d'entre eux suffisent à ralentir la carte quand la vue est dézoomée. À ce stade, placez les points dans une source GeoJSON avec clustering (pris en charge nativement par le SDK) et affichez-les sous forme de couche. La documentation du SDK détaille la configuration du clustering.

Étape 5 : ajouter une recherche d'adresses avec la Geocoding API

La Geocoding API convertit une requête textuelle (adresse postale, nom de ville ou point de repère) en coordonnées. Vous pouvez ensuite centrer la carte dessus, y placer un marqueur ou les transmettre à une requête de calcul d'itinéraire.

async function searchAddress(query) {
  const url = new URL('https://gateway.mapmetrics-atlas.net/forward-geocode/');
  url.searchParams.set('text', query);
  url.searchParams.set('token', 'YOUR_API_KEY');

  const res  = await fetch(url);
  const data = await res.json();

  if (!data.features.length) return;

  const [lng, lat] = data.features[0].geometry.coordinates;
  const label      = data.features[0].properties.label;

  map.flyTo({ center: [lng, lat], zoom: 14 });

  new mapmetricsgl.Marker({ color: '#97C70A' })
    .setLngLat([lng, lat])
    .setPopup(new mapmetricsgl.Popup().setHTML(`<strong>${label}</strong>`))
    .addTo(map);
}

// Try it
searchAddress('Rijksmuseum, Amsterdam');

Les résultats sont renvoyés sous forme de features GeoJSON : ils s'intègrent directement dans n'importe quelle couche compatible GeoJSON, dans un tableau de données ou dans un appel API en aval.

Une barre de recherche en direct en moins de 30 lignes : attachez searchAddress à l'événement input d'un champ texte, ajoutez un debounce de 300 ms, et vous obtenez une recherche cartographique avec autocomplétion, sans aucune dépendance supplémentaire.

Intégrer des cartes interactives dans React

Un composant de carte réutilisable

Placez l'initialisation de la carte dans useEffect pour qu'elle s'exécute après le montage du DOM, et renvoyez une fonction de nettoyage pour éviter les fuites mémoire au démontage :

import { useEffect, useRef } from 'react';
import mapmetricsgl from '@mapmetrics/mapmetrics-gl';
import '@mapmetrics/mapmetrics-gl/dist/mapmetrics-gl.css';

export function MapAtlasMap({
  apiKey,
  center = [4.9041, 52.3676],
  zoom   = 12,
}) {
  const containerRef = useRef(null);

  useEffect(() => {
    const map = new mapmetricsgl.Map({
      container: containerRef.current,
      style: `https://gateway.mapmetrics-atlas.net/styles/?fileName=YOUR_STYLE_ID/style.json&token=${apiKey}`,
      center,
      zoom,
    });

    return () => map.remove();
  }, [apiKey]);

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

Utilisez-le n'importe où dans votre arbre de composants :

<MapAtlasMap
  apiKey={process.env.NEXT_PUBLIC_MAPATLAS_KEY}
  center={[4.9041, 52.3676]}
  zoom={13}
/>

Gérer le rendu côté serveur de Next.js

Le SDK cartographique dépend d'API du navigateur (window, document) qui n'existent pas pendant le SSR. Importez le composant dynamiquement, avec le SSR désactivé :

import dynamic from 'next/dynamic';

const MapAtlasMap = dynamic(
  () => import('./MapAtlasMap').then(m => m.MapAtlasMap),
  {
    ssr: false,
    loading: () => (
      <div style={{ height: 500, background: '#f0f1f3', borderRadius: 12 }} />
    ),
  }
);

Le placeholder loading stabilise votre mise en page pendant le téléchargement du bundle de la carte. Il évite le décalage cumulatif de mise en page (CLS), qui compte à la fois pour l'expérience utilisateur et pour les Core Web Vitals.

Checklist de performance pour la production

Avant la mise en production, passez en revue ces optimisations :

• Chargez en différé les cartes situées sous la ligne de flottaison. Utilisez IntersectionObserver pour n'initialiser la carte que lorsque son conteneur entre dans la zone visible. Vous retirez ainsi environ 250 Ko de JavaScript compressé du chargement initial de la page.
• Restez sur les tuiles vectorielles. Elles restent nettes quelle que soit la densité de l'écran, demandent moins de requêtes à mesure que l'utilisateur zoome et peuvent être restylées côté client sans requête serveur supplémentaire. MapAtlas sert des tuiles vectorielles par défaut.
• Regroupez les grands ensembles de marqueurs. Quelques centaines de marqueurs HTML sur une vue dézoomée provoquent des chutes d'images visibles. Une couche GeoJSON avec clustering évite ce problème.
• Restreignez les clés utilisées dans le navigateur. Une clé utilisée dans le navigateur, y compris dans une variable d'environnement NEXT_PUBLIC_, est visible par toute personne qui ouvre les DevTools. Ne committez jamais de clés dans un dépôt public, limitez les clés du navigateur à vos propres domaines dans le portail et faites transiter les opérations sensibles par votre backend.
• Définissez maxBounds pour les applications régionales. Si vos utilisateurs ne s'intéressent qu'à une zone géographique, limitez le viewport pour que les tuiles situées hors de cette zone ne soient jamais demandées. Moins d'appels réseau, un chargement plus rapide.

Que construire ensuite

Vous avez maintenant une carte qui s'affiche, montre des marqueurs, recherche des adresses et s'intègre à React. Voici les prochaines étapes :

• Routing API : obtenez un itinéraire détaillé, étape par étape, entre deux coordonnées. L'API renvoie la polyline de l'itinéraire, la distance totale et le temps de trajet estimé.
• Isochrone API : générez un polygone couvrant tous les points accessibles en n minutes. Elle sert pour les zones de livraison, les cartes de couverture de service et l'analyse de zones de chalandise.
• Matrix API : calculez le temps de trajet et la distance entre plusieurs origines et destinations en une seule requête. Indispensable pour la répartition de flotte et l'optimisation logistique.

La référence complète du SDK, la documentation des styles et les guides des API sont disponibles sur docs.mapatlas.xyz.

À lire aussi : Comment l'IA trouve votre site web en 2026, ou pourquoi des données structurées et accessibles par API comme celles-ci sont désormais la clé pour être découvert par les agents IA.

Questions fréquentes

Puis-je ajouter gratuitement des cartes interactives à mon site web ?

Oui. MapAtlas propose une offre gratuite, sans carte bancaire à l'inscription. Elle comprend le rendu des tuiles vectorielles, la Geocoding API et la Routing API. C'est suffisant pour le développement et pour une production à petite échelle.

Comment intégrer une carte dans une application React ou Next.js ?

Placez l'initialisation de la carte dans un hook useEffect pour qu'elle s'exécute après le montage du DOM. Dans Next.js, utilisez dynamic() avec ssr: false pour éviter les erreurs de rendu côté serveur. Ce tutoriel couvre les deux approches avec des exemples prêts à copier-coller.

Que sont les tuiles vectorielles, et pourquoi les préférer aux tuiles raster ?

Les tuiles vectorielles décrivent les éléments de la carte (routes, bâtiments, libellés) sous forme de géométrie mathématique, et non d'images en pixels pré-rendues. Elles restent nettes à toutes les résolutions, demandent moins de téléchargements à mesure que vous zoomez et peuvent être entièrement restylées côté client, sans aller-retour supplémentaire avec le serveur.

Combien de marqueurs puis-je ajouter avant que les performances baissent ?

Le rendu se dégrade généralement dès que vous atteignez quelques centaines de marqueurs HTML aux faibles niveaux de zoom. La solution est le clustering : le SDK MapAtlas prend en charge nativement le clustering des sources GeoJSON. Il regroupe les marqueurs proches à faible zoom et les sépare à mesure que l'utilisateur zoome.

Faut-il une expérience en SIG pour utiliser MapAtlas ?

Non. Le SDK est conçu pour les développeurs web, pas pour les spécialistes des SIG. Vous initialisez une carte avec des coordonnées et un niveau de zoom, vous ajoutez des marqueurs avec des paires longitude/latitude et vous appelez la Geocoding API avec du texte brut. Aucune base de données spatiale ni aucun outil SIG n'est nécessaire.

À lire aussi :

• Créer une carte immobilière avec clustering
• Créer un store locator avec une API cartographique
• Alternatives à Google Maps API pour les développeurs européens
• Commencer gratuitement