Migration guide for developers moving from Google Maps Platform to Mapbox GL JS, covering API equivalents, pattern translations, and key differences

Mapbox Google Maps Migration Skill Comprehensive guidance for migrating from Google Maps Platform to Mapbox GL JS. Provides API equivalents, pattern translations, and strategies for successful migration. Core Philosophy Differences Google Maps: Imperative & Object Oriented Create objects (Marker, Polygon, etc.) Add to map with .setMap(map) Update properties with setters Heavy reliance on object instances Mapbox GL JS: Declarative & Data Driven Add data sources Define layers (visual representation) Style with JSON Update data, not object properties Key Insight: Mapbox treats everything as data + styling, not individual objects. Map Initialization Google Maps Mapbox GL JS Key Differences: Coordinate order: Google uses {lat, lng} , Mapbox uses [lng, lat] Authentication: Google uses API key in script tag, Mapbox uses access token in code Styling: Google uses map types, Mapbox uses full style URLs API Equivalents Reference Map Methods Google Maps Mapbox GL JS Notes map.setCenter(latLng) map.setCenter([lng, lat]) Coordinate order reversed map.getCenter() map.getCenter() Returns LngLat object map.setZoom(zoom) map.setZoom(zoom) Same behavior map.getZoom() map.getZoom() Same behavior map.panTo(latLng) map.panTo([lng, lat]) Animated pan map.fitBounds(bounds) map.fitBounds([[lng,lat],[lng,lat]]) Different bound format map.setMapTypeId(type) map.setStyle(styleUrl) Completely different approach map.getBounds() map.getBounds() Similar Map Events Google Maps Mapbox GL JS Notes google.maps.event.addListener(map, 'click', fn) map.on('click', fn) Simpler syntax event.latLng event.lngLat Event property name 'center changed' 'move' / 'moveend' Different event names 'zoom changed' 'zoom' / 'zoomend' Different event names 'bounds changed' 'moveend' No direct equivalent 'mousemove' 'mousemove' Same 'mouseout' 'mouseleave' Different name Markers and Points Simple Marker Google Maps: Mapbox GL JS: Multiple Markers Google Maps: Mapbox GL JS (Equivalent Approach): Mapbox GL JS (Data Driven Approach Recommended for 100+ points): Performance Advantage: Google Maps renders all markers as DOM elements (even when using the Data Layer), which becomes slow with 500+ markers. Mapbox's circle and symbol layers are rendered by WebGL, making them much faster for large datasets (1,000 10,000+ points). This is a significant advantage when building applications with many points. Info Windows / Popups Google Maps Mapbox GL JS Migration Strategy Step 1: Audit Current Implementation Identify all Google Maps features you use: [ ] Basic map with markers [ ] Info windows/popups [ ] Polygons/polylines [ ] Geocoding [ ] Directions [ ] Clustering [ ] Custom styling [ ] Drawing tools [ ] Street View (no Mapbox equivalent) [ ] Other advanced features Step 2: Set Up Mapbox Step 3: Convert Core Map Start with basic map initialization: 1. Replace new google.maps.Map() with new mapboxgl.Map() 2. Fix coordinate order (lat,lng lng,lat) 3. Update zoom/center Step 4: Convert Features One by One Prioritize by complexity: 1. Easy: Map controls, basic markers 2. Medium: Popups, polygons, lines 3. Complex: Clustering, custom styling, data updates Step 5: Update Event Handlers Change event syntax: google.maps.event.addListener() map.on() Update event property names ( latLng lngLat ) Step 6: Optimize for Mapbox Take advantage of Mapbox features: Convert multiple markers to data driven layers Use clustering (built in) Leverage vector tiles for custom styling Use expressions for dynamic styling Step 7: Test Thoroughly Cross browser testing Mobile responsiveness Performance with real data volumes Touch/gesture interactions Gotchas and Common Issues Coordinate Order Always double check coordinate order! Event Properties Timing Issues Removing Features Updating Data Without Flash Never remove and re add layers to update data — this reinitializes WebGL resources and causes a visible flash. Instead: When NOT to Migrate Consider staying with Google Maps if: Street View is critical Mapbox doesn't have equivalent Tight Google Workspace integration Places API deeply integrated Already heavily optimized Migration cost benefits Team expertise Retraining costs too high Short term project Not worth migration effort Quick Reference: Side by Side Comparison Remember: lng, lat order in Mapbox! Additional Resources [Mapbox GL JS Documentation](https://docs.mapbox.com/mapbox gl js/) [Official Google Maps to Mapbox Migration Guide](https://docs.mapbox.com/help/tutorials/google to mapbox/) [Mapbox Examples](https://docs.mapbox.com/mapbox gl js/examples/) [Style Specification](https://docs.mapbox.com/mapbox gl js/style spec/) Integration with Other Skills Works with: mapbox web integration patterns : Framework specific migration guidance mapbox web performance patterns : Optimize after migration mapbox token security : Secure your Mapbox tokens properly mapbox geospatial operations : Use Mapbox's geospatial tools effectively mapbox search patterns : Migrate geocoding/search functionality Reference Files The following reference files contain detailed migration guides for specific topics. Load them when working on those areas: references/shapes geocoding.md — Polygons, Polylines, Custom Icons, Geocoding references/directions controls.md — Directions/Routing, Controls references/clustering styling.md — Clustering, Styling/Appearance references/data performance.md — Data Updates, Performance, Common Migration Patterns (Store Locator, Drawing Tools, Heatmaps) references/api services.md — API Services Comparison, Pricing, Plugins, Framework Integration, Testing, Migration Checklist To load a reference, read the file relative to this skill directory, e.g.:

mapbox-google-maps-migration