Compétence Mapbox Google Maps Migration

Guide complet pour migrer de Google Maps Platform vers Mapbox GL JS. Fournit des équivalents d'API, des traductions de motifs et des stratégies pour une migration réussie.

Différences de philosophie fondamentale

Google Maps : Impératif et orienté objet

• Créer des objets (Marker, Polygon, etc.)
• Les ajouter à la carte avec .setMap(map)
• Mettre à jour les propriétés avec des setters
• Forte dépendance aux instances d'objets

Mapbox GL JS : Déclaratif et piloté par les données

• Ajouter des sources de données
• Définir des couches (représentation visuelle)
• Styliser avec JSON
• Mettre à jour les données, pas les propriétés des objets

Insight clé : Mapbox traite tout comme des données + du style, pas comme des objets individuels.

Initialisation de la carte

Google Maps

const map = new google.maps.Map(document.getElementById('map'), {
  center: { lat: 37.7749, lng: -122.4194 },
  zoom: 12,
  mapTypeId: 'roadmap' // ou 'satellite', 'hybrid', 'terrain'
});

Mapbox GL JS

mapboxgl.accessToken = 'YOUR_MAPBOX_TOKEN';
const map = new mapboxgl.Map({
  container: 'map',
  style: 'mapbox://styles/mapbox/streets-v12', // ou satellite-v9, outdoors-v12
  center: [-122.4194, 37.7749], // [lng, lat] - notez l'ordre !
  zoom: 12
});

Différences clés :

• Ordre des coordonnées : Google utilise {lat, lng}, Mapbox utilise [lng, lat]
• Authentification : Google utilise une clé d'API dans la balise script, Mapbox utilise un token d'accès dans le code
• Style : Google utilise des types de carte, Mapbox utilise des URLs de style complet

Référence des équivalents d'API

Méthodes de carte

Événements de carte

Marqueurs et points

Marqueur simple

Google Maps :

const marker = new google.maps.Marker({
  position: { lat: 37.7749, lng: -122.4194 },
  map: map,
  title: 'San Francisco',
  icon: 'custom-icon.png'
});

// Supprimer le marqueur
marker.setMap(null);

Mapbox GL JS :

// Créer un marqueur
const marker = new mapboxgl.Marker()
  .setLngLat([-122.4194, 37.7749])
  .setPopup(new mapboxgl.Popup().setText('San Francisco'))
  .addTo(map);

// Supprimer le marqueur
marker.remove();

Plusieurs marqueurs

Google Maps :

const markers = locations.map(
  (loc) =>
    new google.maps.Marker({
      position: { lat: loc.lat, lng: loc.lng },
      map: map
    })
);

Mapbox GL JS (approche équivalente) :

// Même approche orientée objet
const markers = locations.map((loc) => new mapboxgl.Marker().setLngLat([loc.lng, loc.lat]).addTo(map));

Mapbox GL JS (approche pilotée par les données - recommandée pour 100+ points) :

// Ajouter en tant que source GeoJSON + couche (utilise WebGL, pas le DOM)
map.addSource('points', {
  type: 'geojson',
  data: {
    type: 'FeatureCollection',
    features: locations.map((loc) => ({
      type: 'Feature',
      geometry: { type: 'Point', coordinates: [loc.lng, loc.lat] },
      properties: { name: loc.name }
    }))
  }
});

map.addLayer({
  id: 'points-layer',
  type: 'circle', // ou 'symbol' pour les icônes
  source: 'points',
  paint: {
    'circle-radius': 8,
    'circle-color': '#ff0000'
  }
});

Avantage de performance : Google Maps rend tous les marqueurs comme des éléments DOM (même en utilisant la couche de données), ce qui devient lent avec 500+ marqueurs. Les couches circle et symbol de Mapbox sont rendues par WebGL, ce qui les rend beaucoup plus rapides pour les grands ensembles de données (1 000-10 000+ points). C'est un avantage significatif lors de la création d'applications avec de nombreux points.

Fenêtres d'info / Popups

Google Maps

const infowindow = new google.maps.InfoWindow({
  content: '<h3>Titre</h3><p>Contenu</p>'
});

marker.addListener('click', () => {
  infowindow.open(map, marker);
});

Mapbox GL JS

// Option 1 : Attacher au marqueur
const marker = new mapboxgl.Marker()
  .setLngLat([-122.4194, 37.7749])
  .setPopup(new mapboxgl.Popup().setHTML('<h3>Titre</h3><p>Contenu</p>'))
  .addTo(map);

// Option 2 : Au clic de la couche (pour les marqueurs pilotés par les données)
map.on('click', 'points-layer', (e) => {
  const coordinates = e.features[0].geometry.coordinates.slice();
  const description = e.features[0].properties.description;

  new mapboxgl.Popup().setLngLat(coordinates).setHTML(description).addTo(map);
});

Stratégie de migration

Étape 1 : Auditer l'implémentation actuelle

Identifier toutes les fonctionnalités Google Maps que vous utilisez :

• [ ] Carte basique avec marqueurs
• [ ] Fenêtres d'info/popups
• [ ] Polygones/polylignes
• [ ] Géocodage
• [ ] Itinéraires
• [ ] Clustering
• [ ] Style personnalisé
• [ ] Outils de dessin
• [ ] Street View (pas d'équivalent Mapbox)
• [ ] Autres fonctionnalités avancées

Étape 2 : Configurer Mapbox

<!-- Remplacer le script Google Maps -->
<script src="https://api.mapbox.com/mapbox-gl-js/v3.18.1/mapbox-gl.js"></script>
<link href="https://api.mapbox.com/mapbox-gl-js/v3.18.1/mapbox-gl.css" rel="stylesheet" />

Étape 3 : Convertir la carte principale

Commencer par l'initialisation basique de la carte :

1. Remplacer new google.maps.Map() par new mapboxgl.Map()
2. Corriger l'ordre des coordonnées (lat,lng -> lng,lat)
3. Mettre à jour le zoom/centre

Étape 4 : Convertir les fonctionnalités une par une

Prioriser par complexité :

1. Facile : Contrôles de carte, marqueurs basiques
2. Moyen : Popups, polygones, lignes
3. Complexe : Clustering, style personnalisé, mises à jour de données

Étape 5 : Mettre à jour les gestionnaires d'événements

Changer la syntaxe des événements :

• google.maps.event.addListener() -> map.on()
• Mettre à jour les noms de propriétés d'événements (latLng -> lngLat)

Étape 6 : Optimiser pour Mapbox

Tirer parti des fonctionnalités de Mapbox :

• Convertir plusieurs marqueurs en couches pilotées par les données
• Utiliser le clustering (intégré)
• Exploiter les carreaux vectoriels pour un style personnalisé
• Utiliser les expressions pour un style dynamique

Étape 7 : Tester complètement

• Tests multi-navigateurs
• Réactivité mobile
• Performance avec des volumes de données réels
• Interactions tactiles/gestes

Pièges et problèmes courants

Ordre des coordonnées

// Google Maps
{ lat: 37.7749, lng: -122.4194 }

// Mapbox (INVERSÉ !)
[-122.4194, 37.7749]

Toujours vérifier l'ordre des coordonnées !

Propriétés d'événements

// Google Maps
map.on('click', (e) => {
  console.log(e.latLng.lat(), e.latLng.lng());
});

// Mapbox
map.on('click', (e) => {
  console.log(e.lngLat.lat, e.lngLat.lng);
});

Problèmes de timing

// Google Maps - immédiat
const marker = new google.maps.Marker({ map: map });

// Mapbox - attendre le chargement
map.on('load', () => {
  map.addSource(...);
  map.addLayer(...);
});

Suppression de fonctionnalités

// Google Maps
marker.setMap(null);

// Mapbox - doit supprimer les deux
map.removeLayer('layer-id');
map.removeSource('source-id');

Mettre à jour les données sans scintillement

Ne jamais supprimer et réajouter des couches pour mettre à jour les données — cela réinitialise les ressources WebGL et provoque un scintillement visible. À la place :

// ✅ Mettre à jour les données sur place (pas de scintillement)
map.getSource('stores').setData(newGeoJSON);

// ✅ Filtrer les données existantes (côté GPU, le plus rapide)
map.setFilter('stores-layer', ['==', ['get', 'category'], 'coffee']);

// ❌ MAUVAIS : la suppression + l'ajout cause un scintillement
map.removeLayer('stores-layer');
map.removeSource('stores');
map.addSource('stores', { ... });
map.addLayer({ ... });

Quand ne PAS migrer

Envisager de rester avec Google Maps si :

• Street View est critique - Mapbox n'a pas d'équivalent
• Intégration Google Workspace forte - Places API profondément intégrée
• Déjà hautement optimisé - Coût de migration > bénéfices
• Expertise de l'équipe - Les coûts de reconversion sont trop élevés
• Projet à court terme - Pas la peine de migrer

Référence rapide : Comparaison côte à côte

// GOOGLE MAPS
const map = new google.maps.Map(el, {
  center: { lat: 37.7749, lng: -122.4194 },
  zoom: 12
});

const marker = new google.maps.Marker({
  position: { lat: 37.7749, lng: -122.4194 },
  map: map
});

google.maps.event.addListener(map, 'click', (e) => {
  console.log(e.latLng.lat(), e.latLng.lng());
});

// MAPBOX GL JS
mapboxgl.accessToken = 'YOUR_TOKEN';
const map = new mapboxgl.Map({
  container: el,
  center: [-122.4194, 37.7749], // INVERSÉ !
  zoom: 12,
  style: 'mapbox://styles/mapbox/streets-v12'
});

const marker = new mapboxgl.Marker()
  .setLngLat([-122.4194, 37.7749]) // INVERSÉ !
  .addTo(map);

map.on('click', (e) => {
  console.log(e.lngLat.lat, e.lngLat.lng);
});

N'oubliez pas : ordre lng, lat dans Mapbox !

Ressources supplémentaires

• Documentation Mapbox GL JS
• Guide officiel de migration Google Maps vers Mapbox
• Exemples Mapbox
• Spécification de style

Intégration avec d'autres compétences

Fonctionne avec :

• mapbox-web-integration-patterns : Guidance de migration spécifique au framework
• mapbox-web-performance-patterns : Optimiser après la migration
• mapbox-token-security : Sécuriser correctement vos tokens Mapbox
• mapbox-geospatial-operations : Utiliser les outils géospatiaux de Mapbox efficacement
• mapbox-search-patterns : Migrer la fonctionnalité de géocodage/recherche

Fichiers de référence

Les fichiers de référence suivants contiennent des guides de migration détaillés pour des sujets spécifiques. Les charger lors du travail sur ces domaines :

• references/shapes-geocoding.md — Polygones, polylignes, icônes personnalisées, géocodage
• references/directions-controls.md — Itinéraires/routage, contrôles
• references/clustering-styling.md — Clustering, style/apparence
• references/data-performance.md — Mises à jour de données, performance, motifs de migration courants (localisateur de magasins, outils de dessin, cartes de chaleur)
• references/api-services.md — Comparaison des services API, tarification, plugins, intégration framework, test, liste de contrôle de migration

Pour charger une référence, lire le fichier relatif à ce répertoire de compétence, par exemple :

Load references/shapes-geocoding.md