スタティック·イメージ (Static Images)

Mapbox Static Images APIは、Mapbox Studioスタイルで生成するスタンドアロンのスタティック(静的)マップ画像を提供します。マッピングライブラリやAPIを使用せずに、これらの画像をWebおよびモバイル機器に表示することができます。一件、埋め込みマップのように見えますが、インタラクティブ機能やコントロール機能はありません。

  • ベクター·レイヤーを含むスタイルの場合、返すスタティックマップは、PNG形式になります。
  • ラスタ·レイヤーを含むスタイルの場合、返すスタティックマップは、JPEG形式になります。

Static Images APIリクエストを作成するには、Static Images APIプレイグラウンドを使用し、インタラクティブマップをズームおよびパンします。

Static Images APIの請求方法については、製品別価格ガイドをご覧ください

スタイルからスタティックマップを取得する方法

/styles/${constants.VERSION_STYLES_API}/{username}/{style_id}/static/{overlay}/{lon},{lat},{zoom},{bearing},{pitch}|{auto}/{width}x{height}{@2x}

マップの位置は、「auto」 または 5 つの数値 (経度、緯度、ズーム、ベアリング、ピッチ) で表します。最後の 2 つの数値(ベアリングとピッチ)は任意です。ベアリングのみを指定すると、ピッチはデフォルトで0になります。どちらも指定しない場合、どちらもデフォルトで 0 になります。「auto」を指定する場合は、これらの数値を指定しないでください。

必須パラメーター説明
usernameスタイルが属するアカウントのユーザー名。
style_idスタティックマップを作成するスタイル ID。
overlay1 つ以上のコンマで区切られた特徴。これらは、リクエスト時にマップの上に適用できます。オーバーレイ内の特徴の順序は、ページ上の Z 順序を決めます。リストの最後の項目は Z オーダーが最も高く(リスト内の他の特徴より上にあり)、最初の項目はオーダーが最も低くなります (他の特徴より下にあります)。形式は、geojson、marker、またはpathの組み合わせにすることができます。各オプションの詳細については、「オーバーレイ オプション」セクションを参照してください。
lonスタティックマップの中心点の経度。-180 ~ 180の数値。
latスタティックマップの中心点の緯度。-90 ~ 90の数値。
zoomズームレベル。0 ~ 20の間の数値。ズームレベルが分数の場合、小数点以下2桁に丸めます。
autoautoを追加すると、ビューポートはオーバーレイの境界に適合します。autoは、lon、lat、zoom、bearing、およびpitchを置換します。
widthイメージの幅。1 ~ 1280 ピクセルの数値。
height画像の高さ。1 ~ 1280 ピクセルの数値。

次の任意のパラメータを使用して、このエンドポイントからの結果をさらに絞り込むことができます。

任意のパラメータ説明
bearingベアリングは、マップ中心の周りにマップを回転します。10進度として解釈される0 ~360の間の数値。90 はマップを 時計回りに90° 回転し、180 はマップを反転します。既定値は0 です。
pitchピッチはマップを傾け、遠近効果を生み出します。0 ~ 60の数値(度単位)。既定値は 0 です(マップをまっすぐ見下ろす)。
@2x高密度ディスプレイ用にスタティックマップを@2xのスケールでレンダリングします。
attribution画像にアトリビューション(属性)があるかどうかを制御するboolean (ブール値)。既定値は trueです。注: attribution=false の場合、透かしのアトリビューションを画像から削除します。OpenStreetMapデータを使用するマップを属性化する法的責任は依然としてあります。これは、Mapboxのほとんどのマップを含みます。 attribution=false を指定する場合は、ウェブページまたはドキュメント上の他の場所に適切なアトリビューションを含める必要があります。
logo画像にMapboxロゴがあるかどうかを制御するboolean 値。既定値は trueです。
overlayがスタイル内のどこに挿入されるかを制御するためのstring 値。指定レイヤーの前に、すべてのオーバーレイを挿入します。

リクエスト例: スタイルからスタティックマップを取得する

# Retrieve a map at -122.4241 longitude, 37.78 latitude,
# zoom 14.24, bearing 0, and pitch 60. The map
# will be 600 pixels wide and 600 pixels high
$ curl "https://api.mapbox.com/styles//mapbox/streets-/static/-122.4241,37.78,14.25,0,60/600x600?access_token=YOUR_MAPBOX_ACCESS_TOKEN"

# Retrieve a map at 0 longitude, 10 latitude, zoom 3,
# and bearing 20. Pitch will default to 0.
$ curl "https://api.mapbox.com/styles//mapbox/streets-/static/0,10,3,20/600x600?access_token=YOUR_MAPBOX_ACCESS_TOKEN"

# Retrieve a map at 0 longitude, 0 latitude, zoom 2.
# Bearing and pitch default to 0.
$ curl "https://api.mapbox.com/styles//mapbox/streets-/static/0,0,2/600x600?access_token=YOUR_MAPBOX_ACCESS_TOKEN"

# Querying a style with raster layers returns a JPEG
$ curl "https://api.mapbox.com/styles//mapbox/satellite-/static/0,0,2/600x600?access_token=YOUR_MAPBOX_ACCESS_TOKEN"

# Retrieve a map with a custom marker overlay
$ curl "https://api.mapbox.com/styles//mapbox/streets-/static/url-https%3A%2F%2Fwww.mapbox.com%2Fimg%2Frocket.png(-76.9,38.9)/-76.9,38.9,15/1000x1000?access_token=YOUR_MAPBOX_ACCESS_TOKEN"

# Retrieve a map with a GeoJSON overlay
$ curl "https://api.mapbox.com/styles//mapbox/streets-/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"

# Retrieve a map with two points and a polyline overlay,
# with its center point automatically determined with `auto`
$ curl "https://api.mapbox.com/styles//mapbox/streets-/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"
エンドポイントのサポート

Mapboxwrapper librariesは、既存のアプリケーションとMapbox APIを統合するのに使用します。次の SDK は、このエンドポイントをサポートします。

関連するメソッドを使用して、このエンドポイントを照会する方法の詳細と例については、SDKドキュメントを参照してください。

応答: スタイルからスタティックマップを取得する

  • ベクター·レイヤーを含むスタイルの場合、返されるスタティックマップは、PNG形式になります。
  • ラスタ·レイヤーを含むスタイルの場合、返されるスタティックマップは、JPEG形式になります。

オーバーレイのオプション

GeoJSON

geojson({geojson})
引数説明
geojson{geojson}引数は有効な GeoJSON オブジェクトでなければなりません。GeoJSON機能のsimplestyle-specスタイルが尊重され、レンダリングされます。# 文字は URL内で %23 に置き換える必要があることに注意してください (たとえば、"fill":"#FF0000"は"fill":"%23FF0000"になります)。

マーカー

{name}-{label}+{color}({lon},{lat})
引数説明
nameマーカーの形状とサイズ。オプションはpin-s とpin-l.です。
label (任意)マーカー記号。選択肢は、英数字ラベルa~z、0 ~99、または有効なMakiアイコンです。文字がリクエストされた場合は、大文字のみでレンダリングされます。
color (任意)3 桁または 6 桁の16進数の色コード。
lon, latマーカーを配置する場所。非対称マーカーを使用する場合、ピンの先端が画像の中心にあることを確認してください。

カスタム マーカー

url-{url}({lon},{lat})
引数説明
url画像のパーセントエンコードURL。形式については、PNG または JPG が指定可能である。
lon, latマーカーを配置する場所。ピンのような非対称マーカーを作成する場合、ピンの先端が画像の中心にあることを確認してください。

Expires およびCache-Controlヘッダーに従って、カスタムマーカーをキャッシュします。カスタムマーカー画像のリクエストが繰り返されないように、少なくともヘッダーの1つを適切な値に設定してください。

パス

path-{strokeWidth}+{strokeColor}-{strokeOpacity}+{fillColor}-{fillOpacity}({polyline})

Static APIでは、pathパラメーターを経て、小数点以下5桁の精度でエンコードされたポリラインを使用することができます。

引数説明
strokeWidth
(任意)
線のストローク幅のための正数
strokeColor
(任意)
線ストローク用の3 桁または 6 桁の16進数の色コード。
strokeOpacity
(任意)
線のストロークの不透明度を表すため、 0 (透明) と 1 (不透明) の間の数値
fillColor塗りつぶし用の3 桁または 6 桁の16進数の色コード。
fillOpacity塗りつぶしの不透明度を表すため、0 (透明) と 1 (不透明) の間の数値
polylineURIコンポーネントとしてエンコードされた有効なポリライン

Static Images API エラー

応答の本文messageHTTP ステータス コード説明
Not Authorized - Invalid Token401クエリで使用したアクセス トークンを確認します。
Style not found404クエリで使用したスタイル ID を確認します。
Zoom level must be between 0-20.422クエリで指定されたズームレベルが 20より大きいか、数字以外の文字を含んでいます。
Pitch must be between 0-60.422クエリで指定されたピッチが60より大きいか、数字以外の文字を含んでいます。
{Width}|{Height} must be between 1-1280.422クエリで指定された幅または高さが1280より大きいか、数字以外の文字を含んでいます。

Static Images APIの制限