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 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 Outdoors |
| |
Mapbox Light |
| |
Mapbox Dark |
| |
Mapbox Satellite |
| |
Mapbox Satellite Streets |
| |
Mapbox Navigation Day |
| |
Mapbox Navigation Night |
|
スタイルオブジェクト
スタイルオブジェクトは Mapbox Style Specification に準拠し、いくつかの追加のアカウント関連プロパティが含まれるオブジェクトです。
プロパティ | タイプ | 説明 |
---|---|---|
version | number | スタイル仕様バージョン番号 |
name | string | スタイルの読みやすい名前 |
metadata | object | Mapbox Studio で使用されるスタイルに関する情報 |
sources | object | マップに表示されるデータを提供するソース |
layers | array | レイヤーはこの配列の順序で作成されます |
created | string | スタイルの作成日時 |
id | string | スタイルのID |
modified | string | 最後にスタイルが修正された日時 |
owner | string | スタイルの所有者のユーザー名 |
visibility | string | スタイルのアクセス制御 (public または private ) |
protected | boolean | スタ イルが保護されているか (true ) されていないか (false ) |
draft | boolean | スタイルが草案であるか (true ) 公開されたか (false ) |
スタイルオブジェクトは以下のルールに従わなければなりません:
- 有効な JSON である必要があります
- 最新バージョンの Mapbox Style Specification に準拠している必要があります
- 最大 15 の
sources
で構成することができます - スタイル本体には Style Specification に記載されていないキーを含めることはできません
- source object の
url
プロパティは有効な Mapbox タイルセットIDでなければなりません - サポートされるのは raster と vector のみです
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を使用してスタイルやスプライトの公開バージョンに変更を加えると、ドラフトバージョンにはその変更が反映されません。
スタイルを取得する
JSON ドキュメントとしてスタイルを取得します。
必須パラメータ | タイプ | 説明 |
---|---|---|
username | string | スタイル所有アカウントのユーザー名 |
style_id | string | 取得するスタイルの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 ドキュメントを参照して、このエンドポイントをクエリするための関連メソッドの使用例や詳細を確認してください。
スタイルの一覧を取得する
特定のアカウントのスタイル一覧を取得します。このエンドポイントは ページネーション をサポートします。スタイルは一般的にかなり大きいため、このエンドポイントへのレスポンスは他のリストエンドポイントよりも早くページネートを開始する可能性があります。アカウントに多数のスタイルがある場合、すべてを取得するために Link
ヘッダーの next
リンクリレーションを繰り返し使用する必要があります。
必須パラメータ | タイプ | 説明 |
---|---|---|
username | string | スタイル所有アカウントのユーザー名 |
このエンドポイントからの結果をさらに絞り込むために、次のオプションパラメータを使用できます。
オプションパラメータ | タイプ | 説明 |
---|---|---|
draft | boolean | ドラフト スタイルのみを一覧表示 (true ) するか、すべてのスタイルを返す (false 、デフォルト) かを指定します。 |
limit | integer | 返すスタイルの最大数。 |
start | string | リスト表示を開始するスタイルの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 バンドルを取得する
このエンドポイントへのアクセスはリクエストによって提供されます。このアクセスを有効にするには、Mapbox サポート に問い合わせてください。
スタイル JSON、スプライト画像、参照されるカスタムフォント、およびライセンスファイルを含む ZIP ファイルを取得します。取得後、スタイル ZIP バンドルのレスポンスは数分間キャッシュされるため、後でリクエストがあっても、スタイルがその間に変更されていた場合でも同じ内容が返されることがあります。
必須パラメータ | タイプ | 説明 |
---|---|---|
username | string | スタイル所有アカウントのユーザー名 |
style_id | string | 取得するスタイルのID |
オプションのパスパラメータ | タイプ | 説明 |
---|---|---|
draft | string | 使用すると、スタイルがドラフトであることを示す。詳細についてはドラフト セクションを参照してください。 |
リクエスト例: スタイル 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
スタイルを作成する
アカウントにスタイルを作成します。投稿されたスタイルオブジェクトは スタイルオブジェクト セクションに記載されたルールに従う必要があります。無効なスタイルは詳細な検証エラーメッセージを生成します。
さらに、Styles API を使用してスタイルを作成する場合:
glyphs
フィールド は、Mapbox グリフエンドポイント (mapbox://fonts/mapbox/{fontstack}/{range}.pbf
) を参照していない限り、ユーザーグリフエンドポイントを指すように上書きされます。- スタイル フィールドがユーザー名を含まず、そのフィールドが
mapbox
またはpublic
のスタイルを指している場合、Styles API は全ての画像を新しいスタイルのスプライトシートにコピーし、スプライト値を新しいスタイルのスプライトに向けて上書きします。 - リクエスト本体にオプションの
name
プロパティが使用されていない場合、新しいスタイルのname
は自動的にスタイルの ID に設定されます。
必須パラメータ | タイプ | 説明 |
---|---|---|
username | string | 新しいスタイルが属するアカウントのユーザー名 |
リクエスト例: スタイルを作成する
$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 から返されるスタイルにはサーバーが追加した以下の新しいプロパティが含まれます: created
、id
、modified
、owner
、および 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 ドキュメントを参照して、このエンドポイントをクエリするための関連メソッドの使用例や詳細を確認してください。
スタイルを更新する
新しい内容で既存のスタイルをアカウントに更新します。リクエスト本体は スタイルオブジェクト セクションに記載されたルールに準拠するスタイルオブジェクトである必要があります。無効なスタイルは詳細な検証エラーメッセージを生成します。
さらに、Styles API を使用してスタイルを更新する場合:
- スタイルを 作成 する際にオプションだった
name
プロパティは、スタイ ルを更新する際にはリクエスト本体に必要です。 - スタイルをリクエストしてから、その未加工のレスポンスを使用して更新すると、このアクションは失敗します。スタイルを更新する前に
created
およびmodified
プロパティを削除する必要があります。 glyphs
フィールド は Mapbox グリフエンドポイント (mapbox://fonts/mapbox/{fontstack}/{range}.pbf
) を指し示していない限り、ユーザーグリフエンドポイントを指すように上書きされます。- スプライトが指すスプライトフィールドがユーザー名を含まず、かつ
mapbox
が属するスタイルやpublic
なスタイルを指している場合、Styles API はすべての画像を更新されたスタイルのスプライトシートにコピーし、スプライト値を更新されたスタイルのスプライトに向けて上書きします。
異なるバージョンの PATCH
リクエストは拒否されます。
必須パラメータ | タイプ | 説明 |
---|---|---|
username | string | スタイル所有アカウントのユーザー名 |
style_id | string | 更新するスタイルの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 ドキュメントを参照して、このエンドポイントをクエリするための関連メソッドの使用例や詳細を確認してください。
スタイルを削除する
スタイルを削除します。このスタイルに属するすべてのスプライトも削除され、スタイルはもう利用できなくなります。
必須パラメータ | タイプ | 説明 |
---|---|---|
username | string | スタイル所有アカウントのユーザー名 |
style_id | string | 削除するスタイルの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 ドキュメントを参照して、このエンドポイントをクエリするための関連メソッドの使用例や詳細を確認してください。
スタイルを保護する
このエンドポイントへ のアクセスはリクエストによって提供されます。このアクセスを有効にするには、Mapbox サポート に問い合わせてください。
スタイルの保護ステータスを更新します。リクエスト本体はプレーンテキストの true
または false
である必要があります。
ステータスを変更できるのは、ドラフトがないスタイルの場合のみです (公開バージョンと比較してドラフトのモディファイドフィールドが先行している場合)。この更新はスタイルの modified
フィールドやスプライトのハッシュを変更しません。保護されたスタイルは、Styles API または Mapbox Studio で 編集 や 削除 することはできません。
必須パラメータ | タイプ | 説明 |
---|---|---|
username | string | スタイル所有アカウントのユーザー名 |
style_id | string | 保護するスタイルの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 をリクエストする
埋め込み可能または共有可能な HTML をリクエストします。
必須パラメータ | タイプ | 説明 |
---|---|---|
username | string | スタイル所有アカウントのユーザー名 |
style_id | string | 埋め込むスタイルのID |
返される埋め込み可能な HTML は、次のオプションのクエリパラメータを使用してさらに修正することができます。
オプションパスパラメータ | タイプ | 説明 |
---|---|---|
draft | string | ドラフト バージョンのスタイルを取得します。詳細については「ドラフト」セクションを参照してください。 |
オプションのクエリパラメータ | タイプ | 説明 |
---|---|---|
zoomwheel | boolean | マップのズームホイールを提供するか (true 、デフォルト)、しないか (false ) です。 |
title | string | マップのタイトル、所有者、およびデフォルトメッセージを表示するタイトルボックス。可能な値は copy (メッセージは「このスタイルをアカウントにコ ピーします」および Copy ボタン)、view (メッセージは「Mapbox Studio で独自のマップをデザインします」および サインアップ ボタン) です。copy オプションは、スタイルの visibility が public の場合にのみ機能します。このパラメータが使用されない場合、またはその値が false の場合は、タイトル ボックスは表示されません。 |
fallback | boolean | フォールバック ラスターマップ (true ) を提供するか、しないか (false 、デフォルト) です。 |
mapboxGLVersion | string | マップをレンダリングするために使用する Mapbox GL JS のバージョンを指定します。 |
mapboxGLGeocoderVersion | string | マップ検索ボックスをレンダリングするために使用する Mapbox GL geocoder プラグイン のバージョンを指定します。 |
hash | number | マップのズームレベルと中心の位置を指定し、フォーマットは #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"
/>