Mapbox GL JSは、Mapboxの現代的なマッピング技術を使用して、WebマップやWebアプリケーションを構築するためのクライアントサイドのJavaScriptライブラリです。Mapbox GL JSを使用して、WebブラウザやクライアントでMapboxの地図を表示し、ユーザーのインタラクティビティを追加し、アプリケーション内で地図体験をカスタマイズすることができます。
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<title>ガイド</title>
<meta name="viewport" content="initial-scale=1,maximum-scale=1,user-scalable=no">
<link href="https://api.mapbox.com/mapbox-gl-js/v3.9.0/mapbox-gl.css" rel="stylesheet">
<script src="https://api.mapbox.com/mapbox-gl-js/v3.9.0/mapbox-gl.js"></script>
<style>
body { margin: 0; padding: 0; }
#map { position: absolute; top: 0; bottom: 0; width: 100%; }
</style>
</head>
<body>
<div id="map"></div>
<script>
// TO MAKE THE MAP APPEAR YOU MUST
// ADD YOUR ACCESS TOKEN FROM
// https://account.mapbox.com
mapboxgl.accessToken = 'YOUR_MAPBOX_ACCESS_TOKEN';
const map = new mapboxgl.Map({
container: 'map',
style: 'mapbox://styles/mapbox/streets-v9',
projection: 'globe', // Display the map as a globe, since satellite-v9 defaults to Mercator
zoom: 1,
center: [30, 15]
});
map.addControl(new mapboxgl.NavigationControl());
map.scrollZoom.disable();
map.on('style.load', () => {
map.setFog({}); // Set the default atmosphere style
});
// The following values can be changed to control rotation speed:
// At low zooms, complete a revolution every two minutes.
const secondsPerRevolution = 240;
// Above zoom level 5, do not rotate.
const maxSpinZoom = 5;
// Rotate at intermediate speeds between zoom levels 3 and 5.
const slowSpinZoom = 3;
let userInteracting = false;
const spinEnabled = true;
function spinGlobe() {
const zoom = map.getZoom();
if (spinEnabled && !userInteracting && zoom < maxSpinZoom) {
let distancePerSecond = 360 / secondsPerRevolution;
if (zoom > slowSpinZoom) {
// Slow spinning at higher zooms
const zoomDif =
(maxSpinZoom - zoom) / (maxSpinZoom - slowSpinZoom);
distancePerSecond *= zoomDif;
}
const center = map.getCenter();
center.lng -= distancePerSecond;
// Smoothly animate the map over one second.
// When this animation is complete, it calls a 'moveend' event.
map.easeTo({ center, duration: 1000, easing: (n) => n });
}
}
// Pause spinning on interaction
map.on('mousedown', () => {
userInteracting = true;
});
map.on('dragstart', () => {
userInteracting = true;
});
// When animation is complete, start spinning if there is no ongoing interaction
map.on('moveend', () => {
spinGlobe();
});
spinGlobe();
</script>
</body>
</html>
YOUR_MAPBOX_ACCESS_TOKENをあなたのMapboxアカウントのアクセストークンに置き換えるまで、期待通りに動作しません。このページでは、Mapbox GL JSを独自のアプリケーションでどのように使用できるかについて詳しく説明します。すぐに始めたいですか？クイックスタートガイドを参照するか、サンプルを見てみてください。
ユースケース
Mapbox GL JSのユースケースには次のようなものがあります：
- 地理データの可視化とアニメーション
- 地図上の機能のクエリとフィルタリング
- Mapboxスタイルのレイヤー間にデータを配置する
- 地図上でカスタムクライアントサイドデータを動的に表示およびスタイリングする
- 3Dデータの可視化とアニメーション
- プログラムで地図にマーカーやポップアップを追加する
Mapbox GL JSでできることのインスピレーションをさらに知りたい場合は、チュートリアル、サンプル、およびMapboxの顧客ショーケースページをご覧ください。
主要概念
Mapbox GL
Mapbox GL JSの「GL」は、2Dおよび3DのMapbox地図をOpenGLを使用して動的な視覚グラフィックとしてレンダリングするグラフィックライブラリであるMapbox GLを指します。Mapbox GL JSは、追加のプラグインを使用せずに、互換性のあるWebブラウザで動的にMapboxマップをレンダリングします。
クライアントサイドレンダリング
Mapbox GL JSはクライアントサイドレンダリングに依存しています。Mapbox GL JSのマップは、サーバーではなくブラウザでベクタータイルとスタイルルールを組み合わせて動的にレンダリングされるため、ユーザーのインタラクションに応じて地図のスタイルや表示されるデータを変更できます。
「Map」クラス
mapboxgl.Mapクラスは、すべてのMapbox GL JSプロジェクトの基礎です。このセクションのクションのコードは、ページにマップを追加するのに必要な最小限の内容を示しています：
mapboxgl.accessToken = '<your access token here>';
const map = new mapboxgl.Map({
container: 'map', // container ID
style: 'mapbox://styles/mapbox/streets-v12', // style URL
center: [-74.5, 40], // starting position [lng, lat]
zoom: 9 // starting zoom
});
accessToken: このMapbox アクセストークンは、Mapbox GL JSマップをMapboxアカウントに関連付けます。container: マップが配置されるHTML要素。この例では、IDが"map"の<div>要素です。style: 使用される地図スタイルのスタイルURL。上記の例では、Mapbox Streets v12スタイルを使用しています。styleオプションをMapコンストラクタに提供しない場合、Mapbox標準スタイルがデフォルトで有効になります。center: マップの開始位置の座標（経度、緯度の順）。zoom: マップの初期化時のズームレベル。整数値または小数値である可能性があります。
レイヤー
Mapbox GL JSマップは、視覚要素と地図データを提供する複数のレイヤーから構成されることができます。各レイヤーは、ブラウザでデータを描画する方法に関するルールを提供し、レンダラーはこれらのレイヤーを使用して地図を画面に描画します。
Mapbox GL JSのaddLayerメソッドは、マップのスタイルにMapboxスタイルのレイヤーを追加します。addLayerに必要な唯一のパラメータはMapboxスタイルのレイヤーオブジェクトです。また、新しいレイヤーを追加する前に既存のレイヤーのIDを指定するオプションのbeforeパラメータも含めることができます。この引数を省略すると、レンダラーはマップ上にレイヤーを描画します。
Mapbox Standardは、slotという概念を通じてデータレイヤーを追加しやすくしています。slotは、既存の土地レイヤーの上に追加されるなど、予め決められたスタイル内の場所ですが、すべてのラベルより下に配置されます。Mapbox Standardの実行時にレイヤーの順序を指定する方法について詳しくを学びましょう。
以下のセクションでは、Mapboxスタイルレイヤーオブジェクトの要素について説明します。
非同期
Mapbox GL JSのレイヤーはリモートであるため、非同期です。したがって、Mapbox GL JSに接続するコードは、適切なタイミングでマップを変更するためにイベントバインディングを使用することがよくあります。たとえば：
map.on('load', () => {
map.addLayer({
id: 'terrain-data',
type: 'line',
source: {
type: 'vector',
url: 'mapbox://mapbox.mapbox-terrain-v2'
},
'source-layer': 'contour'
});
});
この例のコードでは、map.on('load', function() {を使用して、マップのリソース（スタイルなど）が読み込まれた後にmap.addLayerを呼び出します。直ちにmap.addLayerを実行した場合、追加するレイヤーのスタイルがまだ存在しないため、エラーが発生します。
レイヤーソース
新しいレイヤーを追加するときには、ソースを定義する必要があります。ソースはtypeとurlを受け入れますが、GeoJSONソースはurlを持っていません。各タイプのソースには、それぞれ固有のプロパティがあります：
各ソースタイプについての詳細は、Mapboxスタイル仕様のソースセクションを参照してください。
タイルセットには複数のソースレイヤーと呼ばれるデータのサブセットを含めることができます。たとえば、Mapbox Streetsタイルセットには、道路、公園などのソースレイヤーが含まれています。自分のレイヤーが正しいソースレイヤーを参照していることを確認するためには、レイヤーオブジェクトにsource-layer（通常は元のファイルの名前）を含める必要があります。次のサンプルをご覧ください：
map.on('load', () => {
map.addLayer({
id: 'rpd_parks',
type: 'fill',
source: {
type: 'vector',
url: 'mapbox://mapbox.3o7ubwm8'
},
'source-layer': 'RPD_Parks'
});
});
Mapbox GL JSのaddSourceメソッドを使用してソースを追加することもできます。この別の方法を使用してもマップのパフォーマンスに差はありませんが、コードをより読みやすく保つことができることがあります。
レイアウトとペイントプロパティ
レイヤーには、paintおよびlayoutという2つのプロパティがあり、これらを使用してデータをスタイリングします。layoutプロパティは、配置や表示などの高レベルの設定を指定し、レンダリングプロセスの初めに適用されます。paintプロパティは、不透明度、色、移動などのより細かいスタイル属性を指定します。これらは処理が少なく後からレンダリングされます。
次のコードは、マップにレイヤーを追加し、データを緑の塗りつぶしでスタイル付けする例です：
map.on('load', () => {
map.addLayer({
id: 'rpd_parks',
type: 'fill',
source: {
type: 'vector',
url: 'mapbox://mapbox.3o7ubwm8'
},
'source-layer': 'RPD_Parks',
layout: {
visibility: 'visible'
},
paint: {
'fill-color': 'rgba(61,153,80,0.55)'
}
});
});
上記のコードスニペットの最終的な成果物は、サンフランシスコが表示される地図で、公園が緑の多角形として表示されたものです。RPD_Parksレイヤーには、市の公園のデータからのベクターポリゴンが含まれているかもしれません。
別の方法でソースを追加した場合、addLayerにソースを含めるときにソースidを指定する必要があります。
カメラ
カメラは地図の視野です。Mapbox GL JSでは、カメラの視点を調整するための以下のパラメータが提供されています：center、zoom、bearing（地図の視覚的回転）、pitch（地図の視覚的傾き）。地図の初期視点、jumpTo、easeTo、flyToは、すべて共通のカメラオプションを使用します。
他のツールと一緒にMapbox GL JSを使用する
Mapbox GL JSは、多くの他のMapboxツールと非常によく動作します。自分のデータを地図に使用したり、独自のカスタムマップスタイルを作成したり、インタラクティビティを追加したりすることができます。
自分のデータを使用する
Mapbox GL JSを使用すると、大量の地理的データを提供するMapboxタイルセットにアクセスできます。また、Mapbox Studio、Mapbox Tiling Service、またはUploads APIを使用して、自分のデータをアップロードして、Mapbox GL JSマップでそれをアクセスして表示することができます。
マップのスタイリング
Mapbox StreetsなどのMapboxが所有するスタイルを使用して地図をスタイリングすることができます。また、Mapbox Studioで作成した独自のカスタムスタイルを使用することもできます。Mapboxデザインの例やカスタムマップスタイルがMapbox GL JSマップで使用されている例についての詳細は、Examples pageを参照してください。
インタラクティブ性
サードパーティーツールを使用して、Mapbox GL JSマップに追加のインタラクティビティを追加することができます。たとえば、Turf.jsを使用して空間解析を行ったり、three.jsを使用して地図に3Dモデルを追加したり、Web Audio API](/example/dancing-buildings/)を使用してユーザーの環境の音に反応するアニメーションを作成したりすることができます。さまざまなサードパーティーツールを使用したMapbox GL JSの使用方法について詳しく知りたい場合は、Examples pageをご覧ください。
Mapbox GL JSは他のウェブマップにインタラクティブ要素を追加するために使用できる多くのプラグインもサポートしています。インタラクティブな描画ツールを追加したり、インセットマップを追加したり、Mapbox Geocoding APIやMapbox Directions APIと統合したりなど、さまざまなプラグインがあります。詳細については、Mapbox GL JSプラグインページをご覧ください。
Mapbox WebサービスAPI
Mapbox GL JSは、1つ以上のMapbox WebサービスAPIを使用するアプリケーションの素晴らしい出発点です。たとえば、Directions APIを使用して地図上に段階的な経路案内を可視化したり、Isochrone APIを使用して推定通行時間を可視化したりすることができます。Mapbox WebサービスAPIをMapbox GL JSとどのように使用できるかについてもっと詳しく知りたい場合は、Tutorials pageやMapbox GL JS examples pageをご覧ください。
JavaScriptフレームワーク
Mapbox GL JSは、Reactを含むさまざまなJavaScriptフレームワークと組み合わせて使用することができます。Mapbox GL JSをReactと一緒に使用する方法について詳しく知りたい場合は、ReactアプリでMapbox GL JSを使用するチュートリアルをご覧ください。
属性
Mapbox GL JSで地図を作成すると、地図の右下隅に自動的に属性が含まれます。表示オプションをさらに設定するには、AttributionControlのAPIドキュメントを参照してください。Mapboxが要求する属性の種類やその理由についての詳細については、Attributionガイドを参照してください。