スタティック画像 API
Mapbox スタティック画像 API は、Mapbox Studio スタイルから生成されたスタティックな地図画像を提供します。これらの画像は、マッピングライブラリや API の助けを借りずに web やモバイルデバイスで表示できます。埋め込み地図のように見えますが、インタラクティブな機能やコントロールはありません。
PLAYGROUND
スタティック画像 API プレイグラウンド
インタラクティブな地図をズームイン・ズームアウトすることで、スタティック画像 API リクエストを作成します。
スタティック画像 API におけるメルカトル以外の投影
スタティック画像 API から返されるすべての地図画像は Web メルカトル に投影されます。 他の投影はサポートされていません。
スタイルからスタティック地図を取得する
get
https://api.mapbox.com/styles/v1/{username}/{style_id}/static/{overlay}/{lon},{lat},{zoom},{bearing},{pitch}|{bbox}|{auto}/{width}x{height}{@2x}
styles:tiles
地図の位置は auto という単語、バウンディングボックス、または経度、緯度、ズーム、方位角、ピッチの 5 つの数字によって表されます。最後の 2 つの数字、方位角とピッチは任意です。方位角のみを指定した場合、ピッチはデフォルトで 0 になります。どちらも指定しない場合、デフォルトで両方とも 0 になります。auto や bbox を指定する場合、これらの数字を提供しないでください。
- ベクター層を含むスタイルでは、返されるスタティック地図は PNG になります。
- ラスター層のみを含むスタイルでは、返されるスタティック地図は JPEG になります。
| 必須のパラメータ | タイプ | 説明 |
|---|---|---|
username | string | スタイルが所属するアカウントの ユーザー名。 |
style_id | string | スタティック地図を作成するスタイルの ID。 |
overlay | string | リクエスト時に地図上に適用できる 1 つ以上のコンマ区切りのフィーチャ。オーバーレイのフィーチャの順序がページ上の Z オーダーを決定します。リストの最後の項目が最も高い Z オーダー（リスト内の他のフィーチャを上に重ねたもの）を持ち、リストの最初の項目が最も低い Z オーダー（他のフィーチャの下に位置）を持ちます。形式は geojson、marker、または path の混合です。各オプションの詳細は オーバーレイオプションセクション を参照してください。 |
lon | number | スタティック地図の中心点の経度。-180 から 180 の範囲の数値。 |
lat | number | スタティック地図の中心点の緯度。-85.0511 から 85.0511 の範囲の数値。 |
zoom | number | ズームレベル。0 から 22 の範囲の数値。端数のズームレベルは小数点以下 2 桁に丸められます。 |
bbox | array | 上の経度、上の緯度、下の経度、下の緯度を四角括弧で囲んだ 4 つの座標 [lon(min),lat(min),lon(max),lat(max)]。bbox は lon,lat,zoom または auto と交換されます。ズームレベルは、指定された幅と高さ内にバウンディングボックスを収める最も詳細なズームレベルに基づいて計算されます。リクエストの幅と高さを増やすと、高いズームレベルの地図が返されます。バウンディングボックスを使用してスタティック地図を取得する方法については、bbox の例リクエスト を参照してください。 |
auto | string | auto が使用される場合、ビューポートはオーバーレイの境界にフィットします。使用する場合、auto は lon、lat、zoom、bearing、pitch、および bbox を置き換えます。指定された padding 値がない場合、auto を使用すると、自動的に適用されるパディングが画像の最小側の 5% の値（次の整数値に切り上げ）になり、1 側あたり最大 12 ピクセルのパディングが適用されます。 |
width | number | 画像の幅。1 から 1280 ピクセルの範囲の数値。 |
height | number | 画像の高さ。1 から 1280 ピクセルの範囲の数値。 |
このエンドポイントの結果をさらに絞り込むために、次のオプションパラメータを使用できます：
| オプションパラメータ | タイプ | 説明 |
|---|---|---|
bearing | number | 方位角は地図の中心から地図を回転させます。0 から 360 の範囲の数値で、10進度として解釈されます。90 は地図を時計回りに 90° 回転させ、180 は地図を上下逆さまにします。デフォルトは 0。 |
pitch | number | ピッチは地図を傾け、遠近感を出します。0 から 60 の範囲の数値で、度で測定されます。デフォルトは 0（地図を真上から見る）。 |
@2x | string | 高密度ディスプレイのためにスタティック地図を @2x スケールファクターでレンダリングします。 |
attribution | boolean | 画像に帰属があるかどうかを制御します。デフォルトは true。注意: attribution=false と指定すると、ウォーターマーク付きの帰属が画像から削除されます。ただし、OpenStreetMap データを使用する地図に関しては法的責任があり、これはほとんどの Mapbox の地図に含まれます。attribution=false と指定した場合、ウェブページや文書の他の場所に適切な帰属を含める必要 があります。 |
logo | boolean | 图片に Mapbox ロゴがあるかどうかを制御します。デフォルトは true。 |
before_layer | string | overlay がスタイルに挿入される場所を制御します。すべてのオーバーレイは指定されたレイヤーの前に挿入されます。 |
addlayer | object | Mapbox スタイルレイヤーを地図のスタイルにレンダリング時に追加します。before_layer と組み合わせて使用できます。詳細は スタイルパラメータ を参照してください。 |
setfilter | array | Mapbox の表現構文を使用してスタイル内の既存のレイヤーにフィルタを適用します。layer_id と併用する必要があります。詳細は スタイルパラメータ を参照してください。 |
layer_id | string | setfilter で指定されたフィルタを適用するスタイル内のレイヤーを指定します。 |
padding | string | 画像の最小パディングを示します。これは auto または bbox でのみ使用できます。この値は CSS 仕様 に似ており、単位のない 1-4 つの整数を受け入れます。例えば、padding=5 はすべての側に 5 ピクセルの最小パディングを宣言し、padding=5,8,10,7 は上側に 5 ピクセル、右側に 8 ピクセル、下側に 10 ピクセル、左側に 7 ピクセルの最小パディングを宣言します。auto が使用され、padding に値が指定されていない場合、デフォルトのパディングが使用されます（画像の最小側の 5% の値（最も近い整数値に切り上げ）、側あたり最大 12 ピクセルのパディング）。 |
例リクエスト
例リクエスト: スタイルからスタティック地図を取得する
# 経度 -122.4241、緯度 37.78、ズーム 15.25、方位角 0、ピッチ 60 の地図を取得し、地図
# は 400 ピクセルの幅・高さを持ち、出力を PNG 画像として保存します。
$ curl -g "https://api.mapbox.com/styles/v1/mapbox/streets-v12/static/-122.4241,37.78,15.25,0,60/400x400?access_token=YOUR_MAPBOX_ACCESS_TOKEN" --output example-mapbox-static-1.png
# 経度 0、緯度 10、ズーム 3、方位角 20 の地図を取得し、
# ピッチはデフォルトの 0 となります。出力を PNG 画像として保存します。
$ curl -g "https://api.mapbox.com/styles/v1/mapbox/streets-v12/static/0,10,3,20/600x600?access_token=YOUR_MAPBOX_ACCESS_TOKEN" --output example-mapbox-static-2.png
# 経度 0、緯度 0、ズーム 2 の地図を取得します。
# 方向角とピッチはデフォルトで 0 になります。出力は PNG 画像として保存されます。
$ curl -g "https://api.mapbox.com/styles/v1/mapbox/streets-v12/static/0,0,2/600x600?access_token=YOUR_MAPBOX_ACCESS_TOKEN" --output example-mapbox-static-3.png
# ラスターレイヤーのみを含むスタイルのクエリを行い、JPEG 画像として出力を保存します。
$ curl -g "https://api.mapbox.com/styles/v1/mapbox/satellite-v9/static/0,0,2/600x600?access_token=YOUR_MAPBOX_ACCESS_TOKEN" --output example-mapbox-static-4.jpg
例リクエスト: バウンディングボックスを使用してスタティック地図を取得する
バウンディングボックス [-77.043686,38.892035,-77.028923,38.904192] にフィットする地図を取得し、幅 400 ピクセル、高さ 400 ピクセルの PNG 画像として出力を保存します。
$ curl -g "https://api.mapbox.com/styles/v1/mapbox/streets-v12/static/[-77.043686,38.892035,-77.028923,38.904192]/400x400?access_token=YOUR_MAPBOX_ACCESS_TOKEN" --output example-mapbox-static-bbox-1.png
例レスポンス: バウンディングボックスを使用してスタティック地図を取得する
例リクエスト: パディングを使用してバウンディングボックスでスタティック地図を取得する
バウンディングボックスの bbox パラメータはパディングと組み合わせることもできます。前の例と同じバウンディングボックスを使用し、このリクエストでは上側に 50 ピクセルのパディング、側面に 10 ピクセルのパディング、下側に 20 ピクセルのパディングを追加しています。
$ curl -g "https://api.mapbox.com/styles/v1/mapbox/streets-v12/static/[-77.043686,38.892035,-77.028923,38.904192]/400x400?padding=50,10,20&access_token=YOUR_MAPBOX_ACCESS_TOKEN" --output example-mapbox-static-bbox-2.png
例レスポンス: パディングを使用してバウンディングボックスでスタティック地図を取得する
例リクエスト: HTML ファイルでスタティック地図画像を取得する
{/* 経度 -87.0186、緯度 32.4055、 */} {/* ズーム 14、方位角 0。ピッチはデフォルトの
0 です。 */} {/* 地図は幅 500 ピクセル、高さ 300 ピクセルです。 */}
<img
src="https://api.mapbox.com/styles/v1/mapbox/light-v11/static/-87.0186,32.4055,14/500x300?access_token=YOUR_MAPBOX_ACCESS_TOKEN"
alt="セリマ、アラバマ州のエドマウンド・ペットゥス橋の地図。真ん中に黒い 'L' マーカーが配置されている。"
/>
レスポンス: スタイルからスタティック地図を取得する
- ベクター層を含むスタイルでは、返されるスタティック地図は PNG になります。
- ラスター層のみを含むスタイルでは、返されるスタティック地図は JPEG になります。
サポートされているライブラリ: スタイルからスタティック地図を取得する
Mapbox ラッパーライブラリは、既存のアプリケーションに Mapbox API を統合するのに役立ちます。次の SDK はこのエンドポイントをサポートしています：
- Mapbox Python CLI
- Mapbox JavaScript SDK
- Mapbox Java SDK
- MapboxStatic.swift (Objective-C と Swift 対応)
SDK のドキュメントを参照し、関連するメソッドを使用してこのエンドポイントをクエリする方法の詳細とサンプルを確認してください。
オーバーレイオプション
オーバーレイオプションを使用して、リクエスト時にスタティック地図画像の上にマーカー、カスタム画像、およびその他の形状を追加できます。
いくつかのパラメータについて、スタティック画像 API は値を URI コンポーネントとしてエンコードすることを要求します。これらの値は encodeURIComponent() やその他のエンコードツールを使用してエンコードできます。
GeoJSON
geojson({geojson})
| 引数 | タイプ | 説明 |
|---|---|---|
geojson | object | {geojson} 引数は、URI コンポーネントとしてエンコードされた有効な GeoJSON オブジェクトである必要があります。GeoJSON フィーチャには simplestyle-spec スタイルが適用され、レンダリングされます。なお、URL 内の # 文字は %23 に置き換える必要があります（例: "fill":"#FF0000" → "fill":"%23FF0000"）。 |
トラブルシューティング: スタティック画像 API リクエストの短縮
スタティック画像 API は 8,192 文字以下 のリクエストしか受け付けません。overlay パラメータの引数に大きな GeoJSON オブジェクトを使用すると、リクエスト URL が長くなります。以下の最適化を使用すると、スタティック画像 API リクエストの長さを短縮できます：
1. サードパーティーツールを使用した簡略化。 リクエストを渡す前に、simplify-geojson のようなサードパーティーライブラリを使用して GeoJSON を簡略化できます。
2. Studio でカスタムスタイルを作成。 大きな GeoJSON ポリゴンや他のオブジェクトを Mapbox Studio のカ スタム スタイル に追加し、その スタイル ID をスタティック画像 API の style_id パラメータに渡すことで、GeoJSON を overlay パラメータに渡す代わりに設定します。チュートリアル「コロプレス地図の作成 パート 1」 を参照してください。
3. エンコードパスオーバーレイの冗長な座標を削除。 Web メルカトル地図では直線フィーチャには 2 つの座標のみが必要です。多数の点を含むパスオーバーレイが含まれる場合、中間座標を削除してエンコードパスの長さを短縮できます。例：線 [[0,52], [0,51], [0,50],[0,49]] → [[0,52], [0,49]]
4. 複数のマーカーオーバーレイに GeoJSON を使用。 同じアイコンを使用する複数のマーカーオーバーレイが含まれる場合、pin-* や url-* オーバーレイを指定する冗長性を削減するため MultiPoint フィーチャおよび simplestyle-spec を使用する GeoJSON オーバーレイを活用できます。
例：以下のパスオーバーレイがある場合
pin-s-airport+0000FF(1,2),pin-s-airport+0000FF(2,1),pin-s-airport+0000FF(3,2),pin-s-airport+0000FF(1,3)
以下のデータを持つ GeoJSON オーバーレイを追加できます：
{
"type": "Feature",
"properties": {
"marker-size": "small",
"marker-symbol": "airport",
"marker-color": "#0000FF"
},
"geometry": {
"type": "MultiPoint",
"coordinates": [
[1, 2],
[2, 1],
[3, 2],
[1, 3]
]
}
}
同じ視覚 結果が得られます。
カスタムマーカーを複数のポイントに再利用する場合、GeoJSON オーバーレイの "marker-url" プロパティとしてカスタム URL を含めることができます。
5. 座標の精度を減らす。 Web アプリケーションでは、高度に正確な latitude（緯度）および longitude（経度）値を使用することが一般的ですが、スタティック画像 API リクエストでは浮動小数点数の精度を 6 桁に丸めるのが実用的であり、長い URL を短縮するのに役立ちます。
6. デフォルト値に頼る場合はフィーチャプロパティを削除。 スタティック画像 API のオーバーレイでは、特定の simplestyle プロパティが指定されていない場合はデフォルト値が設定されます。元からデフォルト値を使用している場合やデフォルト値を使用して問題ない場合、その simplestyle プロパティの明示的な宣言を削除することで URL の長さを減らせます：
| プロパティ | デフォルト値 |
|---|---|
marker-color | #7e7e7e |
stroke | #555555 |
stroke-width | 2 |
stroke-opacity | 1.0 |
fill | #555555 |
fill-opacity | 0.6 |
marker-size | medium |
例リクエスト: GeoJSON Point オーバーレイを使用してスタティック地図を取得する
# GeoJSONオーバーレイでスタティック地図を取得し、
# 結果を PNG 画像として保存
$ curl -g "https://api.mapbox.com/styles/v1/mapbox/streets-v12/static/geojson(%7B%22type%22%3A%22Point%22%2C%22coordinates%22%3A%5B-73.99%2C40.7%5D%7D)/-73.99,40.70,12/500x300?access_token=YOUR_MAPBOX_ACCESS_TOKEN" --output example-mapbox-static-overlay-GeoJSON.png
例レスポンス: GeoJSON Point オーバーレイを使用してスタティック地図を取得する
例リクエスト: GeoJSON FeatureCollection オーバーレイを使用してスタティック地図を取得する
# 3 つの 色付きマーカー（マキアイコン付き）を含む GeoJSON
# オーバーレイで 500×300px のスタティック地図画像を取得し、
# 結果を PNG 画像として保存
$ curl -g "https://api.mapbox.com/styles/v1/mapbox/streets-v12/static/geojson(%7B%22type%22%3A%22FeatureCollection%22%2C%22features%22%3A%5B%7B%22type%22%3A%22Feature%22%2C%22properties%22%3A%7B%22marker-color%22%3A%22%23462eff%22%2C%22marker-size%22%3A%22medium%22%2C%22marker-symbol%22%3A%22bus%22%7D%2C%22geometry%22%3A%7B%22type%22%3A%22Point%22%2C%22coordinates%22%3A%5B-122.25993633270264,37.80988566878777%5D%7D%7D%2C%7B%22type%22%3A%22Feature%22%2C%22properties%22%3A%7B%22marker-color%22%3A%22%23e99401%22%2C%22marker-size%22%3A%22medium%22%2C%22marker-symbol%22%3A%22park%22%7D%2C%22geometry%22%3A%7B%22type%22%3A%22Point%22%2C%22coordinates%22%3A%5B-122.25916385650635,37.80629162635318%5D%7D%7D%2C%7B%22type%22%3A%22Feature%22%2C%22properties%22%3A%7B%22marker-color%22%3A%22%23d505ff%22%2C%22marker-size%22%3A%22medium%22%2C%22marker-symbol%22%3A%22music%22%7D%2C%22geometry%22%3A%7B%22type%22%3A%22Point%22%2C%22coordinates%22%3A%5B-122.25650310516359,37.8063933469406%5D%7D%7D%5D%7D)/-122.256654,37.804077,13/500x300?access_token=YOUR_MAPBOX_ACCESS_TOKEN" --output example-mapbox-static-overlay-GeoJSON3.png
例レスポンス: GeoJSON FeatureCollection オーバーレイを使用してスタティック地図を取得する
マーカー
{name}-{label}+{color}({lon},{lat})
| 引数 | タイプ | 説明 |
|---|---|---|
name | string | マーカーの形状とサイズ。オプションは pin-s と pin-l です。 |
label | string | オプション。 マーカー記号。オプションは小文字の英数字 a から z および 0 から 99、または有効な Maki アイコンです。文字を指定した場合、大文字でレンダリングされます。 |
color | string | オプション。 3 桁または 6 桁の 16 進数カラーコード。 |
lon, lat | number | マーカーを中央に配置する位置。非対称マーカーを使用する場合は、ピンの先端が画像中央にあることを確認してください。 |
例リクエスト: マーカーオーバーレイを使用してスタティック地図を取得する
# マーカーオーバーレイでスタティック地図を取得し、
# 結果を PNG 画像として保存
$ curl -g "https://api.mapbox.com/styles/v1/mapbox/light-v11/static/pin-s-l+000(-87.0186,32.4055)/-87.0186,32.4055,14/500x300?access_token=YOUR_MAPBOX_ACCESS_TOKEN" --output example-mapbox-static-overlay-marker.png
例レスポンス: マーカーオーバーレイを使用してスタティック地図を取得する
例リクエスト: Maki アイコンオーバーレイを使用してスタティック地図を取得する
# 大きなマーカーオーバーレイでスタティック地図を取得し、
# マーカーには Maki アイコンラベルと背景色 `#f74e4e` がある
# 出力を PNG 画像として保存
$ curl -g "https://api.mapbox.com/styles/v1/mapbox/dark-v11/static/pin-l-embassy+f74e4e(-74.0021,40.7338)/-74.0021,40.7338,16/500x300?access_token=YOUR_MAPBOX_ACCESS_TOKEN" --output example-mapbox-static-overlay-marker-pin-maki-icon.png
例レスポンス: Maki アイコンオーバーレイを使用してスタティック地図を取得する
例リクエスト: HTML ファイルでマーカーオーバーレイを使用してスタティック地図を取得する
{/* マーカーオーバーレイ付きのスタティック地図を取得 */}
{/* 小型ピン、ラベル 'L'、黒色のマーカー */}
<img
src="https://api.mapbox.com/styles/v1/mapbox/light-v11/static/pin-s-l+000(-87.0186,32.4055)/-87.0186,32.4055,14/500x300?access_token=YOUR_MAPBOX_ACCESS_TOKEN"
alt="黒い 'L' マーカー付きのセリマ、アラバマ州エドマウンド・ペットゥス橋の地図スタティック画像"
/>
カスタムマーカー
url-{url}({lon},{lat})
| 引数 | タイプ | 説明 |
|---|---|---|
url | string | 画像の URL をパーセントエンコードしたもの 。 |
lon, lat | number | マーカーを中央に配置する位置。 |
カスタムマーカーオーバーレイは、@2x を使用しても自動的にスケーリングまたは変更されないため、カスタムマーカーとして使用する画像が適切なサイズであることを確認する必要があります。カスタムマーカーとして使用する画像の高さと幅は 1,024 ピクセルを超えてはいけません。
カスタムマーカーは Expires および Cache-Control ヘッダーに基づいてキャッシュされます。キャッシュを防ぐために少なくともこれらのヘッダーの 1 つを適切な値に設定してください。
カスタムマーカーのタイプ値を Content-Type キーで宣言する必要があります。許容される値は image/png および image/jpeg です。
例リクエスト: カスタムマーカーオーバーレイを使用してスタティック地図を取得する
# カスタムマーカーオーバーレイでスタティック地図を取得し、
# 結果を PNG 画像として保存
$ curl -g "https://api.mapbox.com/styles/v1/mapbox/light-v11/static/url-https%3A%2F%2Fdocs.mapbox.com%2Fapi%2Fimg%2Fcustom-marker.png(-76.9,38.9)/-76.9,38.9,15/500x300?access_token=YOUR_MAPBOX_ACCESS_TOKEN" --output example-mapbox-static-overlay-marker-custom.png
例レスポンス: カスタムマーカーオーバーレイを使用してスタティック地図を取得する
/-76.9,38.9,15/500x300?access_token=pk.eyJ1IjoiZXhhbXBsZXMiLCJhIjoiY2p1dHRybDR5MGJuZjQzcGhrZ2doeGgwNyJ9.a-vxW4UaxOoUMWUTGnEArw)
パス
path-{strokeWidth}+{strokeColor}-{strokeOpacity}+{fillColor}-{fillOpacity}({polyline})
エンコードされたポリライン を path パラメータで使用できます。
| 引数 | タイプ | 説明 |
|---|---|---|
strokeWidth | number | オプション。 ラインのストローク幅の正の数 |
strokeColor | string | オプション。 ラインストロークの 16 進数カラーコード |
strokeOpacity | number | オプション。 ラインストロークの不透明度（0 から 1 の数値） |
fillColor | string | オプション。 塗りつぶしの 16 進数カラーコード |
fillOpacity | number | オプション。 塗りつぶしの不透明度（0 から 1 の数値） |
polyline | string | 有効なエンコード済みポリラインの URI コンポーネント |
例リクエスト: パスオーバーレイを使用してスタティック地図を取得する
# 2 つのポイントとポリラインオーバーレイがある地図を取得し、
# 中心点が `auto` で自動的に決定され、
# 結果を PNG 画像として保存
$ curl -g "https://api.mapbox.com/styles/v1/mapbox/streets-v12/static/pin-s-a+9ed4bd(-122.46589,37.77343),pin-s-b+000(-122.42816,37.75965),path-5+f44-0.5(%7DrpeFxbnjVsFwdAvr@cHgFor@jEmAlFmEMwM_FuItCkOi@wc@bg@wBSgM)/auto/500x300?access_token=YOUR_MAPBOX_ACCESS_TOKEN" --output example-mapbox-static-overlay-polyline.png
例レスポンス: パスオーバーレイを使用してスタティック地図を取得する
スタイルパラメータ
スタイルパラメータを使用して、レンダリング時にリクエストされた地図スタイルを変更できます。
スタイルパラメータリクエストは、リクエストで lon、lat、および zoom を指定する必要があります。オーバーレイを含ま ないリクエストでは auto 範囲を使用するとエラーになります。
スタイルレイヤーを追加する
addlayer クエリパラメータを使用して、静的画像リクエストにスタイルレイヤーを追加できます。addlayer クエリパラメータは、新しいレイヤーをレンダリングされた地図に追加するための Mapbox スタイルレイヤー を受け入れます。追加するレイヤーは、Mapbox ソースまたはアカウント内の既存のソースからでなければなりません。
addlayer パラメータを使用するには、リクエストを以下のようにフォーマットします:
# 既存のコンポジットソースから道路オーバーレイレイヤーを追加
# "line-color" の16進コードはURIエンコードされています
https://api.mapbox.com/styles/v1/mapbox/streets-v12/static/-122,37,9/600x600?access_token=YOUR_MAPBOX_ACCESS_TOKEN&addlayer={"id":"road-overlay","type":"line","source":"composite","source-layer":"road","filter":["==",["get","class"],"motorway"],"paint":{"line-color":"%23ff0000","line-width":5}}
新しいレイヤーの z-index を before_layer クエリパラメータを使用して指定します。例えば、以下のリクエストは新しいレイヤー road-overlay を road-label の前に配置します:
# 既存のコンポジットソースから道路オーバーレイレイヤーを追加
# "line-color" の16進コードはURIエンコードされています
https://api.mapbox.com/styles/v1/mapbox/streets-v12/static/-122,37,9/600x600?access_token=YOUR_MAPBOX_ACCESS_TOKEN&addlayer={"id":"road-overlay","type":"line","source":"composite","source-layer":"road","filter":["==",["get","class"],"motorway"],"paint":{"line-color":"%23ff0000","line-width":5}}&before_layer=road-label
オーバーレイと before_layer の優先順位
addlayer がオーバーレイ および before_layer と併用される場合、addlayer パラメータで定義されたレイヤーは常に指定されたレイヤーの下に挿入され、オーバーレイは地図の上に追加されます。
スタイルの一部でないソースからスタイルレイヤーを追加するには、新しいスタイルレイヤーで source.url と source.type を指定する必要があります:
"source": {
"type": "vector",
"url": "mapbox://{username}.{tileset}"
}
source.url は mapbox:// タイルセット URL でなければならず、リクエストに使用されるアクセストークンでアクセス可能でなければなりません。source.type は raster または vector のいずれかでなければなりません。新しいレイヤーとして image または geojson を追加したい場合は、それぞれの オーバーレイオプション を使用する必要があります。
例: スタイルレイヤーを追加した静的地図を取得するリクエスト
# ソースレイヤー `admin` からのデータを使用して "better-boundary" というレイヤーを追加
# 州境のみを含むようにフィルタリングし、米国のワールドビューに一致するようにする
# 結果の境界線を赤（#DB6936）で破線としてスタイル設定
# リクエストの特殊文字はエンコードされています
$ curl -g "https://api.mapbox.com/styles/v1/mapbox/light-v11/static/-96.561208,38.790325,3/800x400@2x?addlayer={%22id%22:%22better-boundary%22,%22type%22:%22line%22,%22source%22:%22composite%22,%22source-layer%22:%22admin%22,%22filter%22:[%22all%22,[%22==%22,[%22get%22,%22admin_level%22],1],[%22==%22,[%22get%22,%22maritime%22],%22false%22],[%22match%22,[%22get%22,%22worldview%22],[%22all%22,%22US%22],true,false],[%22==%22,[%22get%22,%22iso_3166_1%22],%22US%22]],%22layout%22:{%22line-join%22:%22bevel%22},%22paint%22:{%22line-color%22:%22%23DB6936%22,%22line-width%22:1.5,%22line-dasharray%22:[1.5,1]}}&before_layer=road-label&access_token=YOUR_MAPBOX_ACCESS_TOKEN" --output example-mapbox-static-style-parameters-addlayer.png
例: スタイルレイヤーを追加した静的地図の取得レスポンス
既存のフィーチャーをフィルタリングする
既存のスタイルレイヤーにフィルター式を適用するには、setfilter および layer_id クエリパラメータを使用します。setfilter は有効なフィルター 表現 を受け入れ、layer_id はフィルターを追加するスタイル内のレイヤーを指定します。
例えば、国名ラベルをフィルタリングして「カナダ」のみを表示するには、次のようにします:
https://api.mapbox.com/styles/v1/mapbox/streets-v12/static/-91,60,2/800x600?access_token=YOUR_MAPBOX_ACCESS_TOKEN&setfilter=["==","name_en","Canada"]&layer_id=country-label
setfilter を使用する場合は、layer_id でレイヤーを指定する必要があります。layer_id はスタイル内の有効なレイヤーである必要があります。
例: フィルタリングされたレイヤーを含む静的地図を取得するリクエスト
# `country-label` レイヤー内のデータをフィルタリングして
# "Canada" に一致するデータのみを表示
# リクエストの特殊文字はエンコードされています
$ curl -g "https://api.mapbox.com/styles/v1/mapbox/streets-v12/static/-96.8,47.3,1.8/800x400?access_token=YOUR_MAPBOX_ACCESS_TOKEN&setfilter=[%22==%22,%22name_en%22,%22Canada%22]&layer_id=country-label" --output example-mapbox-static-style-parameters-setfilter.png
例: フィルタリングされたレイヤーを含む静的地図の取得レスポンス
静的画像APIエラー
レスポンス本文 message | HTTPステータスコード | 説明 |
|---|---|---|
Not Authorized - Invalid Token | 401 | クエリで使用されたアクセストークンを確認してください。 |
Forbidden | 403 | アカウントに問題がある可能性があります。詳細についてはアカウントページを確認してください。 一部の場合、URL制限付きのアクセストークンを使用すると 403エラーが発生することがあります。詳細についてはトークン管理ガイドを参照してください。 |
Style not found | 404 | クエリで使用されたスタイルIDを確認してください。 |
Classic styles are no longer supported | 410 | クラシックスタイルはサポートされていません。追加の廃止詳細については、このブログ記事をご覧ください。 |
Style may not composite raster sources with vector sources | 400 | リクエストが使用するスタイルには、異なる種類のソースを合成する不正なソース参照が含まれています。 |
Invalid style source | 422 | リクエストが参照するスタイル内のsourcesキーには無効な値が含まれています。 |
Zoom level must be between 0-22. | 422 | クエリで指定されたズームレベルが22を超えているか、数値以外の文字が含まれています。 |
Pitch must be between 0-60. | 422 | クエリで指定されたピッチが60を超えているか、数値以外の文字が含まれています。 |
{Width}/{Height} must be between 1-1280. | 422 | クエリで指定された幅または高さが1280を超えているか、数値以外の文字が含まれています。 |
Auto extent cannot be used with style parameters and no overlay | 422 | スタイルパラメータを含むリクエストでオーバーレイがない場合に、/auto/は使用できません。代わりに、リクエストに経度、緯度、ズームを指定してください。 |
Auto extent cannot be determined when GeoJSON has no features | 422 | フィーチャがないGeoJSONオーバーレイを含むリクエストで/auto/は使用できません。例えば、geojson({"type":"FeatureCollection","features":[]})。代わりに、リクエストに経度、緯度、ズームを指定してください。 |
The auto parameter cannot be used with additional location parameters, bearing, or pitch. | 422 | 追加の位置パラメータ（lon、lat、zoom）、方位、ピッチはautoパラメータと一緒に使用できません。 |
The bounding box parameter cannot be used with additional location parameters, bearing, or pitch. | 422 | 追加の位置パラメータ（lon、lat、zoom）、方位、ピッチはbboxパラメータと一緒に使用できません。 |
The GeoJSON argument has an unknown or unsupported geometry type | 422 | オーバーレイのGeoJSONジオメトリタイプがサポートされていないジオメトリタイプです。 |
You can only use {addlayer}/{setfilter} once per request | 422 | 1つのリクエストで使用できるスタイルパラメータは1つだけです。 |
addlayer and setfilter cannot be used in the same request | 422 | 1つのリクエストで使用できるスタイルパラメータは1つだけです。新しいスタイルレイヤーにフィルタを適用する場合は、addlayerリクエスト内のスタイルレイヤーオブジェクトにfilterを追加する必要があります。 |
The new layer's source reference key does not match any source keys in the requested style. Specify url and type in the source for the new layer. | 422 | addlayerリクエストで指定されたsourceがリクエストされたスタイルと一致していません。新しいレイヤーのソースをtypeとurlを含むオブジェクトとして再フォーマットしてください（例えば、source: { url: 'mapbox://mapbox.mapbox-streets-v8', type: 'vector'}）。 |
The new layer source url must be a properly formatted mapbox:// url (for example mapbox://mapbox.mapbox-streets-v7) | 422 | 新しいレイヤーのソースURLが正しくフォーマットされていません。 |
Layer is missing required attributes (id, type, source) | 422 | レイヤーにid、type、またはsourceの値が欠けています。新しいレイヤーはMapboxスタイルレイヤーの構文に従う必要があります。 |
New layer sources must contain a source type and url | 422 | 新しいレイヤーソースにソースtypeまたはurlが欠けています。 |
New layers must be added with unique ids | 422 | 新しく追加されたレイヤーがスタイル内の既存のレイヤーと同じ名前です。レイヤーIDを別の名前に変更してください。 |
New layer type must be one of the following types: background, fill, line, symbol, circle, fill-extrusion, heatmap, hillshade, raster | 422 | 新しいレイヤータイプは、有効なMapbox GL JSレイヤータイプの1つでなければなりません。 |
Must include layer_id in setfilter request | 422 | setfilterは、フィルタを適用するレイヤーを識別するためにlayer_idと一緒に使用する必要があります。 |
layer_id must be an existing layer in the requested style | 422 | setfilterパラメータは、スタイル内の既存のレイヤーにのみ適用できます。 |
Invalid filter syntax | 422 | setfilterに渡された式が有効な式ではありません。 |
Invalid layer passed to addlayer. Unable to parse JSON. | 422 | addlayerに渡されたJSONが無効です。 |
Padding must be 1-4 numbers, comma-delimited. | 422 | パディングは、カンマ区切りの1-4の数字でなければなりません（単位はピクセルとして暗黙的に指定されます）。CSSのパディング仕様に似ています（例えば、padding=5やpadding=5,8,10,7）。 |
The padding cannot exceed the height or width of the requested image. | 422 | 上下のパディングの合計は画像の高さを超えることができず、左右のパディングの合計は画像の幅を超えることができません。 |
Padding cannot be used without the auto parameter or without a provided bounding box. | 422 | パディングはautoパラメータまたは指定されたバウンディングボックス（bbox）と一緒に使用する場合にのみ使用できます。autoパラメータまたはbboxパラメータがない場合、リクエストにはlon、lat、およびzoomが必要であり、固定された画像サイズでパディングを要求するとこれらの値が変更される可能性があります。 |
Invalid bbox: * | 422 | 提供されたバウンディングボックス（bbox）が無効です。bboxが4つの有効な座標を含み、角括弧で囲まれ、[lon(min),lat(min),lon(max),lat(max)]の順序であることを確認してください。 |
Overlay bounds are out of range. | 422 | オーバーレイの座標がマップの範囲外です。オーバーレイの座標が範囲内（経度が-180から180、緯度が-85.0511から85.0511の間）にあることを確認してください。 |
Height and width must not exceed 1024px | 422 | カスタムマーカーオーバーレイとして使用される画像の幅と高さは1024ピクセル未満でなければなりません。 |
スタティック イメージ API の制限と制限
- Mapbox スタティック イメージ API エンドポイントのデフォルトのレート制限は、1,250 リクエスト/分です。 If you require a higher rate limit, contact us.
- レート制限を超えると、
HTTP 429 Too Many Requestsレスポンスが返されます。レート制限ヘッダーについては、レート制限ヘッダー セクションを参照してください。 - スタティック イメージ API のキャッシュ動作は、他の Mapbox サービスのキャッシュ動作とは異なります。変更がスタティック マップに伝播するまでに最大で 12 時間待つ必要がある場合があります。スタティック イメージ API エンドポイントは、次のキャッシュ ヘッダーをレスポンスに設定します。
max-age=43200,s-maxage=604800(スタイルでmapbox.satelliteが使用されている場合) およびmax-age=43200、s-maxage=43200(その他の場合)。これらのCache-Controlヘッダーは、ソースがクライアントまたは当社の CDN によって処理されるリクエストに対してどのくらいの期間有効と見なされるかを示しています。したがって、変更後のスタティック マップが更新されるまでに最大 12 時間かかることがあります。 - 一般的なキャッシュに関する情報については、Maps API キャッシュトラブルシューティングガイド を参照してください。
静的画像APIの料金
- Billed by requests
- See rates and discounts per Static Images API request in the pricing page's Maps section
静的画像 API の使用はAPI リクエストで測定されます。無料プランに含まれるリクエスト数や、無料プランに含まれないリクエストに対するコストの詳細については、料金ページをご覧ください。
このpageは役に立ちましたか？