メインコンテンツまでスキップ

Styles API

Mapbox Styles API を使用すると、マップスタイル、フォント、および画像を読み取ったり変更したりできます。この API は Mapbox Studio の基礎です。

Studio、Mapbox GL JS、または Mapbox Mobile SDK を使用している場合、既に Styles API を使用しています。このドキュメントは、これらのリソースをプログラム的に読み書きしたいソフトウェア開発者に役立ちます。Mapbox マップの設計や使用には、このリファレンスを読む必要はありません。

Styles API を使用するには、Mapbox Style Specification に精通している必要があります。Mapbox Style Specification は、マップスタイルの構造を定義し、Studio が API と通信し、Mapbox ライブラリと互換性のあるマップを作成するためのオープンスタンダードです。

Mapbox スタイル

Mapbox Standard

スタイル名スタイル URL
スタイル画像
Mapbox Standard
mapbox://styles/mapbox/standard
Mapbox Standard
Mapbox Standard Satellite
mapbox://styles/mapbox/standard-satellite
Mapbox Standard Satellite

Mapbox Standard または Mapbox Standard Satellite を使用するには、GL JS v3 以上のバージョンをウェブおよび mobile Mobile Maps SDKs v11 以上で使用する必要があります。他のスタイル URL が指定されていない限り、これらの SDK バージョンのデフォルトのマップは Mapbox Standard です。

Standard スタイルの基本的なパラダイムは、他の Mapbox スタイルと異なります。Standard のレイヤーは、事前定義された設定オプションを除いて変更できません。Mapbox はベースマップの体験を管理し、主要なグローバルスタイル設定のみを提供します。その結果、常に最新のデータ、スタイル、およびレンダリング機能を備えた統一された視覚体験と、最新のマップを得ることができます。

詳細については、開始ガイド をご覧ください。

Mapbox クラシックスタイル

次の Mapbox 所有の スタイル は、有効な アクセス トークン を使用しているすべてのアカウントで利用できます。以下のスタイル名をクリックしてスタイルの詳細を確認したり、スタイル URL をコピーしてプロジェクトでスタイルを使用したりできます。

スタイル名スタイル URL
スタイル画像
Mapbox Streets
mapbox://styles/mapbox/streets-v12
Mapbox Streets
Mapbox Outdoors
mapbox://styles/mapbox/outdoors-v12
Mapbox Outdoors
Mapbox Light
mapbox://styles/mapbox/light-v11
Mapbox Light
Mapbox Dark
mapbox://styles/mapbox/dark-v11
Mapbox Dark
Mapbox Satellite
mapbox://styles/mapbox/satellite-v9
Mapbox Satellite
Mapbox Satellite Streets
mapbox://styles/mapbox/satellite-streets-v12
Mapbox Satellite Streets
Mapbox Navigation Day
mapbox://styles/mapbox/navigation-day-v1
Mapbox Navigation Day
Mapbox Navigation Night
mapbox://styles/mapbox/navigation-night-v1
Mapbox Navigation Night

スタイルオブジェクト

スタイルオブジェクトは Mapbox Style Specification に準拠し、いくつかの追加のアカウント関連プロパティが含まれるオブジェクトです。

プロパティタイプ説明
versionnumberスタイル仕様バージョン番号
namestringスタイルの読みやすい名前
metadataobjectMapbox Studio で使用されるスタイルに関する情報
sourcesobjectマップに表示されるデータを提供するソース
layersarrayレイヤーはこの配列の順序で作成されます
createdstringスタイルの作成日時
idstringスタイルのID
modifiedstring最後にスタイルが修正された日時
ownerstringスタイルの所有者のユーザー名
visibilitystringスタイルのアクセス制御 (public または private)
protectedbooleanスタ イルが保護されているか (true) されていないか (false)
draftbooleanスタイルが草案であるか (true) 公開されたか (false)

スタイルオブジェクトは以下のルールに従わなければなりません:

  • 有効な JSON である必要があります
  • 最新バージョンの Mapbox Style Specification に準拠している必要があります
  • 最大 15 の sources で構成することができます
  • スタイル本体には Style Specification に記載されていないキーを含めることはできません
  • source objecturl プロパティは有効な Mapbox タイルセットIDでなければなりません
  • サポートされるのは rastervector のみです

gl-style-validate CLI ツールを --mapbox-api-supported フラグ と共に使用してスタイルオブジェクトを検証できます。無効なスタイルは詳細な検証エラーメッセージを生成します。

スタイルオブジェクトの例

{
"version": 8,
"name": "{name}",
"metadata": "{metadata}",
"sources": "{sources}",
"sprite": "mapbox://sprites/{username}/{style_id}",
"glyphs": "mapbox://fonts/{username}/{fontstack}/{range}.pbf",
"layers": ["{layers}"],
"created": "2015-10-30T22:18:31.111Z",
"id": "{style_id}",
"modified": "2015-10-30T22:22:06.077Z",
"owner": "{username}",
"visibility": "private",
"protected": false,
"draft": true
}

ドラフト

Styles API はドラフトが可能で、すべてのスタイルには公開済みとドラフトのバージョンが存在します。これにより、アプリに反映させずにスタイルの変更を行うことができます。スタイル関連のエンドポイントごとに、スタイルIDの後に draft/ を付けることでスタイルのドラフトバージョンとやり取りできます。例えば、/styles/v1/{username}/{style_id}/draft/sprite のようになります。

Studio のスタイルエディタで表示されるスタイルは常にドラフトバージョンです。API 呼び出しで draft/ のないURIを使用してスタイルやスプライトの公開バージョンに変更を加えると、ドラフトバージョンにはその変更が反映されません。

スタイルを取得する

get
https://api.mapbox.com/styles/v1/{username}/{style_id}
styles:read

JSON ドキュメントとしてスタイルを取得します。

必須パラメータタイプ説明
usernamestringスタイル所有アカウントのユーザー名
style_idstring取得するスタイルのID

リクエスト例: スタイル を取得する

$curl "https://api.mapbox.com/styles/v1/examples/cjikt35x83t1z2rnxpdmjs7y7?access_token=YOUR_MAPBOX_ACCESS_TOKEN"

レスポンス: スタイルの取得

返される スタイルオブジェクトMapbox Style 形式になります。

レスポンス例: スタイルを取得する

{
"version": 8,
"name": "Meteorites",
"metadata": {
"mapbox:origin": "basic-template-v1",
"mapbox:autocomposite": true,
"mapbox:type": "template",
"mapbox:sdk-support": {
"js": "0.45.0",
"android": "6.0.0",
"ios": "4.0.0"
}
},
"center": [74.24426803763072, -2.2507114487818853],
"zoom": 0.6851443156248076,
"bearing": 0,
"pitch": 0,
"sources": {
"composite": {
"url": "mapbox://mapbox.mapbox-streets-v8,examples.0fr72zt8",
"type": "vector"
}
},
"sprite": "mapbox://sprites/examples/cjikt35x83t1z2rnxpdmjs7y7",
"glyphs": "mapbox://fonts/{username}/{fontstack}/{range}.pbf",
"layers": [
{
"id": "background",
"type": "background",
"layout": {},
"paint": {
"background-color": []
}
},
{}
],
"created": "2015-10-30T22:18:31.111Z",
"id": "cjikt35x83t1z2rnxpdmjs7y7",
"modified": "2015-10-30T22:22:06.077Z",
"owner": "examples",
"visibility": "public",
"protected": true,
"draft": false
}

サポートされているライブラリ: スタイルの取得

Mapbox ラッパーライブラリは、既存のアプリケーションに Mapbox API を統合するのに役立ちます。次の SDK がこのエンドポイントをサポートしています。

SDK ドキュメントを参照して、このエンドポイントをクエリするための関連メソッドの使用例や詳細を確認してください。

スタイルの一覧を取得する

get
https://api.mapbox.com/styles/v1/{username}
styles:list

特定のアカウントのスタイル一覧を取得します。このエンドポイントは ページネーション をサポートします。スタイルは一般的にかなり大きいため、このエンドポイントへのレスポンスは他のリストエンドポイントよりも早くページネートを開始する可能性があります。アカウントに多数のスタイルがある場合、すべてを取得するために Link ヘッダーの next リンクリレーションを繰り返し使用する必要があります。

必須パラメータタイプ説明
usernamestringスタイル所有アカウントのユーザー名

このエンドポイントからの結果をさらに絞り込むために、次のオプションパラメータを使用できます。

オプションパラメータタイプ説明
draftbooleanドラフト スタイルのみを一覧表示 (true) するか、すべてのスタイルを返す (false、デフォルト) かを指定します。
limitinteger返すスタイルの最大数。
startstringリスト表示を開始するスタイルのID。Link ヘッダーの start パラメータを参照します。詳細はページネーションセクションを参照してください。

リクエスト例: スタイルの一覧を取得する

$curl "https://api.mapbox.com/styles/v1/YOUR_MAPBOX_USERNAME?access_token=YOUR_SECRET_MAPBOX_ACCESS_TOKEN"

レスポンス: スタイルの一覧を取得する

このエンドポイントは完全なスタイルの代わりにスタイルのメタデータを返します。

レスポンス例: スタイルの一覧を取得する

[
{
"version": 8,
"name": "My Awesome Style",
"created": "{timestamp}",
"id": "cige81msw000acnm7tvsnxcp5",
"modified": "{timestamp}",
"owner": "{username}"
},
{
"version": 8,
"name": "My Cool Style",
"created": "{timestamp}",
"id": "cig9rvfe300009lj9kekr0tm2",
"modified": "{timestamp}",
"owner": "{username}"
}
]

サポートされているライブラリ: スタイルの一覧を取得する

Mapbox ラッパーライブラ リは、既存のアプリケーションに Mapbox API を統合するのに役立ちます。次の SDK がこのエンドポイントをサポートしています。

SDK ドキュメントを参照して、このエンドポイントをクエリするための関連メソッドの使用例や詳細を確認してください。

スタイル ZIP バンドルを取得する

get
https://api.mapbox.com/styles/v1/{username}/{style_id}.zip
styles:download
Note

このエンドポイントへのアクセスはリクエストによって提供されます。このアクセスを有効にするには、Mapbox サポート に問い合わせてください。

スタイル JSONスプライト画像、参照されるカスタムフォント、およびライセンスファイルを含む ZIP ファイルを取得します。取得後、スタイル ZIP バンドルのレスポンスは数分間キャッシュされるため、後でリクエストがあっても、スタイルがその間に変更されていた場合でも同じ内容が返されることがあります。

必須パラメータタイプ説明
usernamestringスタイル所有アカウントのユーザー名
style_idstring取得するスタイルのID
オプションのパスパラメータタイプ説明
draftstring使用すると、スタイルがドラフトであることを示す。詳細についてはドラフト セクションを参照してください。

リクエスト例: スタイル ZIP バンド ルを取得する

# 公開スタイルのスタイルバンドルをリクエスト
$curl "https://api.mapbox.com/styles/v1/YOUR_MAPBOX_USERNAME/cjikt35x83t1z2rnxpdmjs7y7.zip?access_token=YOUR_SECRET_MAPBOX_ACCESS_TOKEN"

# ドラフトスタイルのスタイルバンドルをリクエスト
$curl "https://api.mapbox.com/styles/v1/YOUR_MAPBOX_USERNAME/cjikt35x83t1z2rnxpdmjs7y7/draft.zip?access_token=YOUR_SECRET_MAPBOX_ACCESS_TOKEN"

レスポンス: スタイル ZIP バンドルを取得する

レスポンスは、スタイルの名前に基づいた ZIP ファイルとなります。このファイルには、関連する style.json、スプライト画像、参照されたカスタムフォント、および license.txt ファイルが含まれます。階層の例を以下に示します。

Monochrome-draft(cjikt35x83t1z2rnxpdmjs7y7)/
├── fonts/
│ ├── My Font Bold.ttf
│ └── My Font Regular.ttf
├── license.txt
├── sprite_images/
│ ├── aquarium-11.svg
│ ├── bank-15.svg
│ ├── car-11.svg
│ └── ...
└── style.json

スタイルを作成する

post
https://api.mapbox.com/styles/v1/{username}
styles:write

アカウントにスタイルを作成します。投稿されたスタイルオブジェクトは スタイルオブジェクト セクションに記載されたルールに従う必要があります。無効なスタイルは詳細な検証エラーメッセージを生成します。

さらに、Styles API を使用してスタイルを作成する場合:

  • glyphs フィールド は、Mapbox グリフエンドポイント (mapbox://fonts/mapbox/{fontstack}/{range}.pbf) を参照していない限り、ユーザーグリフエンドポイントを指すように上書きされます。
  • スタイル フィールドがユーザー名を含まず、そのフィールドが mapbox または public のスタイルを指している場合、Styles API は全ての画像を新しいスタイルのスプライトシートにコピーし、スプライト値を新しいスタイルのスプライトに向けて上書きします。
  • リクエスト本体にオプションの name プロパティが使用されていない場合、新しいスタイルの name は自動的にスタイルの ID に設定されます。
必須パラメータタイプ説明
usernamestring新しいスタイルが属するアカウントのユーザー名

リクエスト例: スタイルを作成する

$curl -X POST "https://api.mapbox.com/styles/v1/YOUR_MAPBOX_USERNAME?access_token=YOUR_SECRET_MAPBOX_ACCESS_TOKEN" \
--data @basic-v9.json \
--header "Content-Type:application/json"

リクエスト本体例: スタイルを作成する

{
"version": 8,
"name": "My Awesome Style",
"metadata": {},
"sources": {
"myvectorsource": {
"url": "mapbox://{tileset_id}",
"type": "vector"
},
"myrastersource": {
"url": "mapbox://{tileset_id}",
"type": "raster"
}
},
"glyphs": "mapbox://fonts/{username}/{fontstack}/{range}.pbf",
"layers": []
}

レスポンス: スタイルを作成する

API から返されるスタイルにはサーバーが追加した以下の新しいプロパティが含まれます: createdidmodifiedowner、および draft

レスポンス例: スタイルを作成する

{
"version": 8,
"name": "My Awesome Style",
"metadata": {},
"sources": {
"myvectorsource": {
"url": "mapbox://{tileset_id}",
"type": "vector"
},
"myrastersource": {
"url": "mapbox://{tileset_id}",
"type": "raster"
}
},
"sprite": "mapbox://sprites/{username}/{style_id}",
"glyphs": "mapbox://fonts/{username}/{fontstack}/{range}.pbf",
"layers": [],
"created": "2015-10-30T22:18:31.111Z",
"id": "{style_id}",
"modified": "2015-10-30T22:22:06.077Z",
"owner": "{username}",
"draft": true
}

サポートされているライブラリ: スタイルを作成する

Mapbox ラッパーライブラリは、既存のアプリケーションに Mapbox API を統合するのに役立ちます。次の SDK がこのエンドポイントをサポートしています。

SDK ドキュメントを参照して、このエンドポイントをクエリするための関連メソッドの使用例や詳細を確認してください。

スタイルを更新する

patch
https://api.mapbox.com/styles/v1/{username}/{style_id}
styles:write

新しい内容で既存のスタイルをアカウントに更新します。リクエスト本体は スタイルオブジェクト セクションに記載されたルールに準拠するスタイルオブジェクトである必要があります。無効なスタイルは詳細な検証エラーメッセージを生成します。

さらに、Styles API を使用してスタイルを更新する場合:

  • スタイルを 作成 する際にオプションだった name プロパティは、スタイ ルを更新する際にはリクエスト本体に必要です。
  • スタイルをリクエストしてから、その未加工のレスポンスを使用して更新すると、このアクションは失敗します。スタイルを更新する前に created および modified プロパティを削除する必要があります。
  • glyphs フィールド は Mapbox グリフエンドポイント (mapbox://fonts/mapbox/{fontstack}/{range}.pbf) を指し示していない限り、ユーザーグリフエンドポイントを指すように上書きされます。
  • スプライトが指すスプライトフィールドがユーザー名を含まず、かつ mapbox が属するスタイルや public なスタイルを指している場合、Styles API はすべての画像を更新されたスタイルのスプライトシートにコピーし、スプライト値を更新されたスタイルのスプライトに向けて上書きします。

異なるバージョンの PATCH リクエストは拒否されます。

必須パラメータタイプ説明
usernamestringスタイル所有アカウントのユーザー名
style_idstring更新するスタイルのID

リクエスト例: スタイルを更新する

$curl -X PATCH "https://api.mapbox.com/styles/v1/YOUR_MAPBOX_USERNAME/{style_id}?access_token=YOUR_SECRET_MAPBOX_ACCESS_TOKEN" \
--data @basic-v9.json \
--header "Content-Type:application/json"

リクエスト本体例: スタイルを更新する

{
"version": 8,
"name": "New Style Name",
"metadata": {},
"sources": {},
"sprite": "mapbox://sprites/{username}/{style_id}",
"glyphs": "mapbox://fonts/{username}/{fontstack}/{range}.pbf",
"layers": [
{
"id": "new-layer",
"type": "background",
"paint": {
"background-color": "#111"
},
"interactive": true
}
],
"owner": "{username}",
"draft": true
}

レスポンス: スタイルを更新する

このエンドポイントへの成功したリクエストにより、更新された スタイルオブジェクト が返されます。

レスポンス例: スタイルを更新する

{
"version": 8,
"name": "New Style Name",
"metadata": {},
"sources": {},
"sprite": "mapbox://sprites/{username}/{style_id}",
"glyphs": "mapbox://fonts/{username}/{fontstack}/{range}.pbf",
"layers": [
{
"id": "new-layer",
"type": "background",
"paint": {
"background-color": "#111"
},
"interactive": true
}
],
"created": "2015-10-30T22:18:31.111Z",
"id": "{style_id}",
"modified": "2015-10-30T22:22:06.077Z",
"owner": "{username}",
"draft": true
}

サポートされているライブラリ: スタイルを更新する

Mapbox ラッパーライブラリは、既存のアプリケーションに Mapbox API を統合するのに役立ちます。次の SDK がこのエンドポイントをサポートしています。

SDK ドキュメントを参照して、このエンドポイントをクエリするための関連メソッドの使用例や詳細を確認してください。

スタイルを削除する

delete
https://api.mapbox.com/styles/v1/{username}/{style_id}
styles:write

スタイルを削除します。このスタイルに属するすべてのスプライトも削除され、スタイルはもう利用できなくなります。

必須パラメータタイプ説明
usernamestringスタイル所有アカウントのユーザー名
style_idstring削除するスタイルのID

リクエスト例: スタイルを削除する

$curl -X DELETE "https://api.mapbox.com/styles/v1/YOUR_MAPBOX_USERNAME/{style_id}?access_token=YOUR_SECRET_MAPBOX_ACCESS_TOKEN"

レスポンス: スタイルを削除する

HTTP 204 No Content

サポートされているライブラリ: スタイルを削除する

Mapbox ラッパーライブラリは、既存のアプリケーションに Mapbox API を統合するのに役立ちます。次の SDK がこのエンドポイントをサポートしています。

SDK ドキュメントを参照して、このエンドポイントをクエリするための関連メソッドの使用例や詳細を確認してください。

スタイルを保護する

put
https://api.mapbox.com/styles/v1/{username}/{style_id}/protected
styles:protect
Note

このエンドポイントへ のアクセスはリクエストによって提供されます。このアクセスを有効にするには、Mapbox サポート に問い合わせてください。

スタイルの保護ステータスを更新します。リクエスト本体はプレーンテキストの true または false である必要があります。

ステータスを変更できるのは、ドラフトがないスタイルの場合のみです (公開バージョンと比較してドラフトのモディファイドフィールドが先行している場合)。この更新はスタイルの modified フィールドやスプライトのハッシュを変更しません。保護されたスタイルは、Styles API または Mapbox Studio編集削除 することはできません。

必須パラメータタイプ説明
usernamestringスタイル所有アカウントのユーザー名
style_idstring保護するスタイルのID

リクエスト例: スタイルを保護する

$curl "https://api.mapbox.com/styles/v1/YOUR_MAPBOX_USERNAME/cjikt35x83t1z2rnxpdmjs7y7/protected?access_token=YOUR_SECRET_MAPBOX_ACCESS_TOKEN" \
--data-raw "true" \
--header "Content-Type: text/plain"

レスポンス: スタイルを保護する

{
"protected": true
}

無効なリクエストへのレスポンス: ドラフトスタイルの保護

ドラフトがあるスタイルを保護す ることはできません。このエンドポイントは 400 Bad Request エラーを返します。

ドラフトスタイルを 公開 するか、最後に公開されたバージョンに 戻す 前に保護します。

埋め込み可能な HTML をリクエストする

get
https://api.mapbox.com/styles/v1/{username}/{style_id}.html
styles:read

埋め込み可能または共有可能な HTML をリクエストします。

必須パラメータタイプ説明
usernamestringスタイル所有アカウントのユーザー名
style_idstring埋め込むスタイルのID

返される埋め込み可能な HTML は、次のオプションのクエリパラメータを使用してさらに修正することができます。

オプションパスパラメータタイプ説明
draftstringドラフト バージョンのスタイルを取得します。詳細については「ドラフト」セクションを参照してください。
オプションのクエリパラメータタイプ説明
zoomwheelbooleanマップのズームホイールを提供するか (true、デフォルト)、しないか (false) です。
titlestringマップのタイトル、所有者、およびデフォルトメッセージを表示するタイトルボックス。可能な値は copy (メッセージは「このスタイルをアカウントにコ ピーします」および Copy ボタン)、view (メッセージは「Mapbox Studio で独自のマップをデザインします」および サインアップ ボタン) です。copy オプションは、スタイルの visibilitypublic の場合にのみ機能します。このパラメータが使用されない場合、またはその値が false の場合は、タイトル ボックスは表示されません。
fallbackbooleanフォールバック ラスターマップ (true) を提供するか、しないか (false、デフォルト) です。
mapboxGLVersionstringマップをレンダリングするために使用する Mapbox GL JS のバージョンを指定します。
mapboxGLGeocoderVersionstringマップ検索ボックスをレンダリングするために使用する Mapbox GL geocoder プラグイン のバージョンを指定します。
hashnumberマップのズームレベルと中心の位置を指定し、フォーマットは #zoom/latitude/longitude/bearing/pitch です。方位およびピッチ は任意であり、指定されていない場合は両方ともデフォルトで 0° になります。ハッシュは要求中の access_token の後に配置されます。

例: 埋め込み可能な HTML をリクエストする

{/* Map は、z15 で、45° のベアリングおよび 70° のピッチで、San Francisco に中心を置いています。*/}
<iframe
src="https://api.mapbox.com/styles/v1/mapbox/streets-v12.html?title=true&zoomwheel=false&access_token=YOUR_MAPBOX_ACCESS_TOKEN#15/37.771/-122.436/45/70"
/>

サポートされているライブラリ: 埋め込み可能な HTML をリクエストする