Comment ajouter des cartes interactives a votre site web | Tutoriel JavaScript (2026) | MapAtlas Blog

Chaque tableau de bord logistique, annonce immobiliere et application de livraison de nourriture ont une chose en commun: une carte. Si votre site n'en a pas encore, vous laissez de contexte sur la table. Un contexte qui aide les utilisateurs a comprendre les localisations, les proximites et les relations spatiales en un coup d'oeil.

Ce tutoriel vous guide a travers l'ajout d'une carte entierement interactive a n'importe quel projet JavaScript. Vous allez commencer par une carte rendue, puis ajouter des marqueurs et des popups, connecter la recherche d'adresses avec l'API Geocoding, et terminer avec un composant React pret pour la production qui s'integre parfaitement dans Next.js.

Voici ce que vous allez construire d'ici la fin:

Une carte vectorielle en direct authentifiee avec votre cle API
Des marqueurs cliquables avec du contenu popup personnalise
Une fonction de recherche d'adresses alimentee par le geocodage
Un composant React reutilisable avec un nettoyage approprie et une gestion SSR Next.js
Une liste de controle des optimisations de performance pour la production

Conditions prealables

Avant de commencer, assurez-vous d'avoir:

Une cle API MapAtlas (inscrivez-vous gratuitement, aucune carte de credit requise). Cette seule cle authentifie chaque service MapAtlas: les tuiles, le geocodage et l'acheminement.
Un projet JavaScript. HTML simple, React, Vue ou Svelte fonctionnent tous.
Node.js 18+ si vous installez via npm.

Etape 1: Installer le SDK MapAtlas

Tirez le SDK dans votre projet avec npm:

npm install @mapmetrics/mapmetrics-gl

Si vous travaillez plutot avec une page HTML simple, deposez 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>

Ne sautez pas l'import CSS. Sans lui, les controles de carte et les popups s'affichent sans style. Fonctionnels, mais visuellement casses.

Etape 2: Creer un conteneur de carte

Le SDK remplit tout element sur lequel vous le pointez, donc vous avez besoin d'un <div> avec une hauteur explicite. C'est l'erreur de configuration la plus courante: si le conteneur a height: 0, la carte s'initialise mais reste invisible.

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

Une valeur de pixel fixe ou une unite viewport (100vh, 50vh) fonctionnent toutes les deux. Les hauteurs en pourcentage ne fonctionnent que si l'element parent a aussi une hauteur definie.

Etape 3: Afficher votre premiere carte interactive

Trois lignes de configuration c'est tout ce qu'il faut: un conteneur, une URL de style avec votre cle API et une position de depart.

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

const map = new mapmetricsgl.Map({
  container: 'map',
  style: 'https://tiles.mapatlas.eu/styles/basic/style.json?key=YOUR_API_KEY',
  center: [4.9041, 52.3676], // [longitude, latitude]
  zoom: 12,
});

Ouvrez la page et vous verrez une carte vectorielle que vous pouvez faire glisser, faire defiler et faire glisser pour naviguer. Les tuiles se chargent a la demande a partir des serveurs MapAtlas, donc il n'y a pas de telechargement lourd initial.

Choisir un style de carte

Echangez le segment de chemin dans l'URL de style pour changer completement l'apparence:

Style	Chemin URL	Ideal pour
Basic	`/styles/basic/style.json`	Applications a usage general
Bright	`/styles/bright/style.json`	Superpositions de visualisation de donnees
Dark	`/styles/dark/style.json`	Tableaux de bord, mode nuit, analyse

Gain rapide: Utilisez le style Dark pour les panneaux d'administration et les outils utilises dans des environnements faiblement eclaires. Cela reduit la fatigue oculaire et fait que les couches de donnees comme les cartes de chaleur et les lignes d'acheminement se detachent visuellement du fond.

Etape 4: Ajouter des marqueurs et des popups a votre carte

Une carte sans marqueurs est juste une image de fond. Les marqueurs transforment une vue statique en quelque chose avec lequel les utilisateurs peuvent interagir.

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 et la popup s'ouvre. Vous pouvez mettre n'importe quel HTML a l'interieur: des adresses, des miniatures, des boutons d'appel a l'action, tout ce que votre interface utilisateur appelle.

Tracer plusieurs marqueurs a partir de donnees

La plupart des applications du monde reel ont besoin de plus d'une epingle. Bouclez sur un tableau et creez un marqueur pour chaque entree:

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 de performance: Une fois que vous depassez environ 100 a 200 marqueurs, le rendu ralentit noticeablement sur les vues dezoommees. Activez le clustering de source GeoJSON (supporte directement par le SDK) pour regrouper les marqueurs proches a des niveaux de zoom bas. Consultez la documentation SDK pour la configuration du clustering.

Etape 5: Ajouter la recherche d'adresses avec l'API Geocoding

L'API Geocoding transforme une requete textuelle (une adresse, un nom de ville ou un point de repere) en coordonnees sur lesquelles vous pouvez faire un panoramique, marquer ou alimenter une demande d'acheminement.

async function searchAddress(query) {
  const url = new URL('https://api.mapatlas.eu/geocoding/v1/search');
  url.searchParams.set('text', query);
  url.searchParams.set('key', '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 resultats reviennent sous forme de caracteristiques GeoJSON, ils se branchent donc directement dans n'importe quelle couche compatible GeoJSON, tableau de donnees ou appel API en aval.

Construisez une barre de recherche en direct en moins de 30 lignes: Attachez searchAddress a l'evenement input d'un champ de texte, debounce-le de 300ms, et vous avez une recherche de carte style autocomplete sans dependances supplementaires.

Integration des cartes interactives avec React

Un composant de carte reutilisable

Enveloppez l'initialisation de la carte dans useEffect pour qu'elle s'execute apres le montage du DOM, et renvoyez une fonction de nettoyage pour eviter les fuites memoire au demontage:

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://tiles.mapatlas.eu/styles/basic/style.json?key=${apiKey}`,
      center,
      zoom,
    });

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

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

Utilisez-le n'importe ou dans votre arborescence de composants:

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

Gestion du rendu cote serveur Next.js

Le SDK de carte depend des APIs du navigateur (window, document) qui n'existent pas pendant le rendu cote serveur. Importez le composant dynamiquement avec SSR desactive:

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 }} />
    ),
  }
);

L'espace reserve loading garde votre mise en page stable pendant que le paquet de carte se telecharge, en evitant le decalage de mise en page cumulatif (CLS), ce qui compte pour l'experience utilisateur et les Core Web Vitals.

Liste de controle des performances en production

Avant de deployer, parcourez ces optimisations:

Chargement tardif des cartes en bas de la page. Utilisez IntersectionObserver pour initialiser la carte uniquement lorsque son conteneur se fait defiler dans la vue. Cela differe environ 200 KB de JavaScript du chargement de page initial.
Restez avec les tuiles vectorielles. Les tuiles vectorielles s'adaptent proprement a toute densite d'ecran, se chargent plus rapidement que les images raster et peuvent etre completement restyisees cote client sans demandes de serveur supplementaires. MapAtlas sert des tuiles vectorielles par defaut.
Regroupez les gros ensembles de marqueurs. Au-dela de 100 a 200 marqueurs, le rendu non groupe sur une vue dezoommee provoque des chutes d'images noticeables. Le clustering resout cela entierement.
Gardez votre cle API cote serveur. Ne validez jamais les cles dans un depot public. Utilisez des variables d'environnement (NEXT_PUBLIC_MAPATLAS_KEY dans Next.js) ou des demandes de proxy a travers votre backend pour les operations sensibles.
Definissez maxBounds pour les applications regionales. Si vos utilisateurs ne se soucient que d'une geographie, limitez la viewport pour que les tuiles en dehors de cette zone ne soient jamais demandees. Moins d'appels reseau, chargement plus rapide.

Quoi construire ensuite

Vous avez une carte qui s'affiche, montre des marqueurs, recherche des adresses et s'integre avec React. Voici ou aller a partir de la:

API Routage: Demandez des directions au compas entre deux coordonnees. Renvoie une polyline d'itineraire, la distance totale et le temps de deplacement estime.
API Isochrone: Generez un polygone couvrant chaque point accessible dans n minutes. Utilise pour les zones de livraison, les cartes de couverture de service et l'analyse de la zone de chalandise.
API Matrice: Calculez le temps de deplacement et la distance entre plusieurs origines et destinations dans une seule demande. Essentiel pour la distribution de flotte et l'optimisation logistique.

La reference complete du SDK, la documentation de style et les guides API sont disponibles sur docs.mapatlas.xyz.

Questions frequemment posees

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

Oui. MapAtlas offre un niveau gratuit sans carte de credit requise lors de l'inscription. Il inclut le rendu de tuiles vectorielles, l'API Geocoding et l'API Routage. C'est suffisant pour le developpement et une utilisation en production a petite echelle.

Comment incorporer une carte dans une application React ou Next.js?

Enveloppez l'initialisation de la carte dans un hook useEffect pour qu'il s'execute apres le montage du DOM. Dans Next.js, utilisez dynamic() avec ssr: false pour eviter les erreurs de rendu cote serveur. Les deux approches sont couvertes avec des exemples prets a copier-coller dans ce tutoriel.

Qu'est-ce que les tuiles vectorielles et pourquoi devrais-je les utiliser plutot que raster?

Les tuiles vectorielles decrivent les caracteristiques de la carte (routes, batiments, etiquettes) comme une geometrie mathematique plutot que comme des images de pixels pre-rendues. Elles s'adaptent precisement a toute resolution, se chargent plus rapidement et peuvent etre completement restyisees cote client sans aller-retours supplementaires du serveur.

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

Le rendu se degrade generalement au-dela de 100 a 200 marqueurs a des niveaux de zoom bas. La correction est le clustering: le SDK MapAtlas supporte le clustering de source GeoJSON nativement, regroupant les marqueurs proches a un zoom bas et les etendant au fur et a mesure que l'utilisateur fait un zoom avant.

Ai-je besoin d'une experience en SIG pour utiliser MapAtlas?

Non. Le SDK est concu pour les developpeurs web, pas pour les specialistes en SIG. Vous initialisez une carte avec des coordonnees et un niveau de zoom, ajoutez des marqueurs avec des paires de longitude/latitude et appelez l'API Geocoding avec du texte ordinaire. Aucune base de donnees spatiale ou outil SIG requis.

Comment ajouter des cartes interactives a votre site web | Tutoriel JavaScript (2026)