Mapbox Google Maps Migration Skill

Google Maps PlatformからMapbox GL JSへの移行に関する包括的なガイダンス。API相当部分、パターン変換、移行戦略を提供します。

コア設計思想の相違点

Google Maps: 命令型 & オブジェクト指向

• オブジェクト(Marker、Polygon等)を作成
• .setMap(map)でマップに追加
• setterでプロパティを更新
• オブジェクトインスタンスへの強い依存

Mapbox GL JS: 宣言型 & データドリブン

• データソースを追加
• レイヤー(視覚表現)を定義
• JSON でスタイル設定
• オブジェクトプロパティではなくデータを更新

重要な洞察: Mapboxはすべてをデータ+スタイリングとして扱い、個別オブジェクトではありません。

マップの初期化

Google Maps

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

Mapbox GL JS

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

主な相違点:

• 座標順序: GoogleはLat, Lngで表現、Mapboxは[lng, lat]を使用
• 認証: GoogleはスクリプトタグのAPIキー、Mapboxはコード内のアクセストークン
• スタイリング: GoogleはマップタイプURLを使用、MapboxはフルスタイルURLを使用

API相当部分リファレンス

マップメソッド

Google Maps	Mapbox GL JS	備考
map.setCenter(latLng)	map.setCenter([lng, lat])	座標順序が反転
map.getCenter()	map.getCenter()	LngLatオブジェクトを返す
map.setZoom(zoom)	map.setZoom(zoom)	同じ動作
map.getZoom()	map.getZoom()	同じ動作
map.panTo(latLng)	map.panTo([lng, lat])	アニメーション付きパン
map.fitBounds(bounds)	map.fitBounds([[lng,lat],[lng,lat]])	異なる範囲形式
map.setMapTypeId(type)	map.setStyle(styleUrl)	完全に異なるアプローチ
map.getBounds()	map.getBounds()	類似

マップイベント

Google Maps	Mapbox GL JS	備考
google.maps.event.addListener(map, 'click', fn)	map.on('click', fn)	より簡潔な構文
event.latLng	event.lngLat	イベントプロパティ名
'center_changed'	'move' / 'moveend'	イベント名が異なる
'zoom_changed'	'zoom' / 'zoomend'	イベント名が異なる
'bounds_changed'	'moveend'	直接的な相当なし
'mousemove'	'mousemove'	同じ
'mouseout'	'mouseleave'	名前が異なる

マーカーと点

シンプルなマーカー

Google Maps:

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

// マーカーを削除
marker.setMap(null);

Mapbox GL JS:

// マーカーを作成
const marker = new mapboxgl.Marker()
  .setLngLat([-122.4194, 37.7749])
  .setPopup(new mapboxgl.Popup().setText('San Francisco'))
  .addTo(map);

// マーカーを削除
marker.remove();

複数マーカー

Google Maps:

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

Mapbox GL JS(同等のアプローチ):

// 同じオブジェクト指向アプローチ
const markers = locations.map((loc) => new mapboxgl.Marker().setLngLat([loc.lng, loc.lat]).addTo(map));

Mapbox GL JS(データドリブンアプローチ - 100以上のポイントに推奨):

// GeoJSONソース+レイヤーとして追加(WebGL使用、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', // or 'symbol' for icons
  source: 'points',
  paint: {
    'circle-radius': 8,
    'circle-color': '#ff0000'
  }
});

パフォーマンス上の利点: Google MapsはすべてのマーカーをDOM要素として描画します(データレイヤー使用時でも)。500以上のマーカーで速度が低下します。Mapboxの円形およびシンボルレイヤーはWebGLで描画されるため、大規模なデータセット(1,000〜10,000以上のポイント)ではるかに高速です。多くのポイントを備えたアプリケーションを構築する場合、これは大きな利点となります。

情報ウィンドウ / ポップアップ

Google Maps

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

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

Mapbox GL JS

// オプション1: マーカーに添付
const marker = new mapboxgl.Marker()
  .setLngLat([-122.4194, 37.7749])
  .setPopup(new mapboxgl.Popup().setHTML('<h3>Title</h3><p>Content</p>'))
  .addTo(map);

// オプション2: レイヤークリック時(データドリブンマーカー用)
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);
});

移行戦略

ステップ1: 現在の実装を監査

使用しているすべてのGoogle Maps機能を特定します:

• 基本的なマップとマーカー
• 情報ウィンドウ/ポップアップ
• ポリゴン/ポリライン
• ジオコーディング
• 方向/ルート検索
• クラスタリング
• カスタムスタイリング
• 描画ツール
• ストリートビュー(Mapboxに相当なし)
• その他の高度な機能

ステップ2: Mapboxのセットアップ

<!-- 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" />

ステップ3: コアマップを変換

基本的なマップ初期化から始めます:

1. new google.maps.Map()をnew mapboxgl.Map()に置き換える
2. 座標順序を修正(lat,lng -> lng,lat)
3. ズーム/中心を更新

ステップ4: 機能を1つずつ変換

複雑さで優先度を付けます:

1. 簡単: マップコントロール、基本的なマーカー
2. 中程度: ポップアップ、ポリゴン、線
3. 複雑: クラスタリング、カスタムスタイリング、データ更新

ステップ5: イベントハンドラを更新

イベント構文を変更します:

• google.maps.event.addListener() -> map.on()
• イベントプロパティ名を更新(latLng -> lngLat)

ステップ6: Mapbox用に最適化

Mapboxの機能を活用します:

• 複数マーカーをデータドリブンレイヤーに変換
• クラスタリング(組み込み)を使用
• カスタムスタイリングにベクトルタイルを活用
• 動的スタイリングに式を使用

ステップ7: 徹底的にテスト

• クロスブラウザテスト
• モバイルレスポンシブ対応
• 実データ量でのパフォーマンス
• タッチ/ジェスチャーインタラクション

落とし穴と一般的な問題

座標順序

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

// Mapbox (REVERSED!)
[-122.4194, 37.7749]

常に座標順序を二重確認してください!

イベントプロパティ

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

タイミングの問題

// Google Maps - 即座
const marker = new google.maps.Marker({ map: map });

// Mapbox - ロード待機
map.on('load', () => {
  map.addSource(...);
  map.addLayer(...);
});

機能を削除

// Google Maps
marker.setMap(null);

// Mapbox - 両方を削除する必要があります
map.removeLayer('layer-id');
map.removeSource('source-id');

データ更新時のフラッシュなし

データを更新するためにレイヤーを削除して再追加しないでください—これはWebGLリソースを再初期化し、視覚的なフラッシュが発生します。代わりに:

// ✅ データをその場で更新(フラッシュなし)
map.getSource('stores').setData(newGeoJSON);

// ✅ 既存データをフィルタリング(GPU側、最速)
map.setFilter('stores-layer', ['==', ['get', 'category'], 'coffee']);

// ❌ 悪い例: 削除+再追加でフラッシュが発生
map.removeLayer('stores-layer');
map.removeSource('stores');
map.addSource('stores', { ... });
map.addLayer({ ... });

移行しない場合

以下の場合はGoogle Mapsに留まることを検討してください:

• ストリートビューが重要 - Mapboxに相当なし
• Googleワークスペース統合が密接 - Places API が深く統合
• 既に大幅に最適化 - 移行コスト > 利益
• チームの専門知識 - 再トレーニングコストが高い
• 短期プロジェクト - 移行の労力に見合わない

クイックリファレンス: 並行比較

// 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], // REVERSED!
  zoom: 12,
  style: 'mapbox://styles/mapbox/streets-v12'
});

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

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

重要: Mapboxではlng, lat順序です!

追加リソース

• Mapbox GL JS Documentation
• Official Google Maps to Mapbox Migration Guide
• Mapbox Examples
• Style Specification

他のスキルとの連携

連携スキル:

• mapbox-web-integration-patterns: フレームワーク固有の移行ガイダンス
• mapbox-web-performance-patterns: 移行後の最適化
• mapbox-token-security: Mapboxトークンを適切に保護
• mapbox-geospatial-operations: Mapboxの地理空間ツールを効果的に使用
• mapbox-search-patterns: ジオコーディング/検索機能の移行

リファレンスファイル

以下のリファレンスファイルに、特定のトピックの詳細な移行ガイドが含まれています。それらの領域で作業する際に読み込んでください:

• references/shapes-geocoding.md — ポリゴン、ポリライン、カスタムアイコン、ジオコーディング
• references/directions-controls.md — 方向/ルート検索、コントロール
• references/clustering-styling.md — クラスタリング、スタイリング/外観
• references/data-performance.md — データ更新、パフォーマンス、一般的な移行パターン(ストアロケーター、描画ツール、ヒートマップ)
• references/api-services.md — APIサービス比較、価格設定、プラグイン、フレームワーク統合、テスト、移行チェックリスト

リファレンスを読み込むには、このスキルディレクトリを基準にしたファイルを読み込んでください。例えば:

Load references/shapes-geocoding.md