skilld
All skills
mapbox avatar

/mapbox-google-maps-migration

@65bab68 official
by mapboxmapbox/mapbox-agent-skills80 stars
17

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

Ask your Agent

Use this Skill: https://skilld.dev/gh/mapbox/mapbox-agent-skills/mapbox-google-maps-migration

This session only. Nothing lands on disk.

referencesapi-services.md

≈942 tokens on demand. Your agent reads this file only when SKILL.md points to it.

API Services, Pricing, Plugins, Framework Integration, and Testing

API Services Comparison

Service Google Maps Mapbox Notes
Geocoding Geocoding API Geocoding API Similar capabilities
Reverse Geocoding ✅ ✅ Similar
Directions Directions API Directions API Mapbox has traffic-aware routing
Distance Matrix Distance Matrix API Matrix API Similar
Isochrones ❌ ✅ Mapbox exclusive
Optimization ❌ ✅ Mapbox exclusive (TSP)
Street View ✅ ❌ Google exclusive
Static Maps ✅ ✅ Both supported
Satellite Imagery ✅ ✅ Both supported
Tilesets Limited Full API Mapbox more flexible

Pricing Differences

Google Maps Platform

  • Charges per API call
  • Free tier: $200/month credit
  • Different rates for different APIs
  • Can get expensive with high traffic

Mapbox

  • Charges per map load
  • Free tier: 50,000 map loads/month
  • Unlimited API requests per map session
  • More predictable costs

Migration Tip: Understand how pricing models differ for your use case.

Plugins and Extensions

Google Maps Plugins -> Mapbox Alternatives

Google Maps Plugin Mapbox Alternative
MarkerClusterer Built-in clustering
Drawing Manager @mapbox/mapbox-gl-draw
Geocoder @mapbox/mapbox-gl-geocoder
Directions @mapbox/mapbox-gl-directions
- @mapbox/mapbox-gl-traffic
- @mapbox/mapbox-gl-compare

Framework Integration

React

Google Maps:

import { GoogleMap, Marker } from '@react-google-maps/api';

Mapbox:

import Map, { Marker } from 'react-map-gl';
// or
import { useMap } from '@mapbox/mapbox-gl-react';

Vue

Google Maps:

import { GoogleMap } from 'vue3-google-map';

Mapbox:

import { MglMap } from 'vue-mapbox';

See mapbox-web-integration-patterns skill for detailed framework guidance.

Testing Strategy

Unit Tests

// Mock mapboxgl
jest.mock('mapbox-gl', () => ({
  Map: jest.fn(() => ({
    on: jest.fn(),
    addSource: jest.fn(),
    addLayer: jest.fn()
  })),
  Marker: jest.fn()
}));

Integration Tests

  • Test map initialization
  • Test data loading and updates
  • Test user interactions (click, pan, zoom)
  • Test API integrations (geocoding, directions)

Visual Regression Tests

  • Compare before/after screenshots
  • Ensure visual parity with Google Maps version

Checklist: Migration Complete

  • Map initializes correctly
  • All markers/features display
  • Click/hover interactions work
  • Popups/info windows display
  • Geocoding integrated
  • Directions/routing working
  • Custom styling applied
  • Controls positioned correctly
  • Mobile/touch gestures work
  • Performance is acceptable
  • Cross-browser tested
  • API keys secured
  • Error handling in place
  • Analytics/monitoring updated
  • Documentation updated
  • Team trained on Mapbox

Source: SKILL.md on GitHub

Third-party checks

1 warning15d5 checks · Risk SAFE
  • Gen Agent Trust Hub15d

    This skill is a safe and educational migration guide for developers moving from Google Maps to Mapbox GL JS. It provides technical comparisons, API equivalents, and best practices for performance optimization. All external references and code samples target official Mapbox services and reputable open-source libraries.

  • Socket15d

    No alerts

  • Snyk15d

    Risk: LOW · No issues

  • Runlayer7mo

    2/2 files flagged

  • ZeroLeaks5mo

    Score: 93/100 · 2 sections analyzed

Provenance

Signed by skilld at 65bab68. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub 8 hours ago.

Activeupdated 6 months ago

Topics

  • mapbox
  • google-maps
  • migration
  • mapping
  • javascript
  • geospatial
  • gl-js
  • web-mapping

README badge

README badge for mapbox/mapbox-agent-skills/mapbox-google-maps-migration

What it does

Guides developers migrating from Google Maps Platform to Mapbox GL JS, covering API method equivalents, coordinate order differences, and architectural patterns. Includes reference tables for map methods and events, marker strategies for different data volumes, and gotchas like timing issues and data updates that cause visual flashing.

Generated from the current SKILL.md.

Frequently asked

Does Mapbox have a Street View equivalent?
No. Street View is not available in Mapbox GL JS, so if Street View is critical to your application, you should stay with Google Maps.
What's the coordinate order difference between Google Maps and Mapbox?
Google Maps uses {lat, lng} while Mapbox uses [lng, lat] (reversed). This applies to all methods: map.setCenter(), marker.setLngLat(), fitBounds(), etc.
How do I handle large numbers of markers in Mapbox?
For 100+ points, use data-driven layers (GeoJSON sources + circle/symbol layers) instead of individual marker objects. Mapbox renders these with WebGL, making them much faster than DOM-based markers for 1,000-10,000+ points.
How do I update marker data without causing a visual flash?
Call map.getSource('source-id').setData(newGeoJSON) to update data in place, or use map.setFilter() to filter existing data on the GPU. Never remove and re-add layers to update data, as this reinitializes WebGL resources and causes a visible flash.
What authentication method does Mapbox use?
Mapbox uses access tokens set in code (mapboxgl.accessToken = 'YOUR_TOKEN'), whereas Google Maps uses API keys in the script tag.

Generated from the current SKILL.md. These answers refresh after source changes.