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"
/>
サポートされているライブラリ: 埋め込み可能な HTML をリクエストする
Mapbox ラッパーライブラリは既存のアプリケーションに Mapbox API を統合するのに役立ちます。次の SDK がこのエンドポイントをサポートしています。
SDK ドキュメントを参照して、このエンドポイントをクエリするための関連メソッドの使用例や詳細を確認してください。
マップの WMTS ドキュメントを取得する
Mapbox は WMTS 標準によるアクセスをサポートしており、ArcMap や QGIS のようなデスクトップおよびオンラインの GIS ソフトウェアとマップを使用することができます。
必須パラメータ | タイプ | 説明 |
---|---|---|
username | string | スタイル所有アカウントのユーザー名 |
style_id | string | WMTS ドキュメントを返すスタイルのID |
リクエスト例: マップの WMTS ドキュメントを取得する
$curl "https://api.mapbox.com/styles/v1/mapbox/streets-v12/wmts?access_token=YOUR_MAPBOX_ACCESS_TOKEN"
レスポンス: マップの WMTS ドキュメントを取得する
このエンドポイントへのリクエストへのレスポンスは、マップの WMTS ドキュメントとなります。
スプライト
スプライトは、Mapbox GL JS と Mapbox モバイル SDK が効率的に画像を要求および表示する方法です。スプライトは、symbol
レイヤーのアイコンやパターンとしてスタイルに使用できる画像のコレクションです。スプライト内の画像は、アイコン、パターン、またはイラストです。これらの SVG 画像はいつでも追加および削除できます。Styles API はこれらの SVG 画像を自動的に収集し、1 つの PNG 画像および各画像が配置されている場所を説明する JSON ドキュメントにレンダリングします。
スプライト JSON ドキュメントは Mapbox Style Specification の一部として指定されています。
スプライトはスタイルごとに管理されます。各スプライトはスタイルに属しているため、1,000 画像のスプライト制限もスタイルごとの制限です。
スプライト画像は、限られたカラーパレットに最適化された PNG-8 ファイルです。通常、ソース SVG ファイルからの視覚的な違いはほとんどありませんが、スプライト画像を詳細に検査すると色の違いやディザリングが発生する場合があります。
すべてのスプライト関連 API メソッドには、スプライトが属するスタイルを指す {style_id}
パラメータが必要です。
スプライト画像または JSON の取得
Mapbox スタイルからスプライト画像またはその JSON ドキュメントを取得します。
必須パラメータ | タイプ | 説明 |
---|---|---|
username | string | スタイル所有アカウントのユーザー名 |
style_id | string | スプライトが属するスタイルのID |
このエンドポイントからの結果をさらに絞り込むために、次のオプションパラメータを使用できます。
オプションパラメータ | タイプ | 説明 |
---|---|---|
sprite_id | string | 変更不可能なスプライトの ID。スプライトの一意の ID を見つける方法については、スプライト ID の取得方法 を参照してください。 |
@2x | string | 高密度ディスプレイ用にスプライトを @2x 、@3x 、または @4x スケール ファクターでレンダリングします。 @2.5x などの小数値もサポートされています。 |
format | string | デフォルトでは、このエンドポイントはスプライトの JSON ドキュメントを返します。スプライト画像を返すには .png を指定します。 |
リクエスト例: スプライト画像または JSON を取得する
# png 形式でスプライト画像をリクエスト
$curl "https://api.mapbox.com/styles/v1/YOUR_MAPBOX_USERNAME/{style_id}/sprite.png?access_token=YOUR_MAPBOX_ACCESS_TOKEN"
# 3x スケールのスプライトの json をリクエスト
$curl "https://api.mapbox.com/styles/v1/YOUR_MAPBOX_USERNAME/{style_id}/sprite@3x?access_token=YOUR_MAPBOX_ACCESS_TOKEN"
# 変更不可能なスプライト画像を png 形式でリクエスト
$curl "https://api.mapbox.com/styles/v1/YOUR_MAPBOX_USERNAME/{style_id}/{sprite_id}/sprite.png?access_token=YOUR_MAPBOX_ACCESS_TOKEN"
レスポンス: スプライト画像または JSON の取得
このエンドポイントへの成功したリクエストへのレスポンスは、要求されたスプライト画像またはその JSON レスポンスのいずれかとなります。
レスポンス例: スプライト画像または JSON の取得
{
"default_marker": {
"width": 20,
"height": 50,
"x": 0,
"y": 0,
"pixelRatio": 2
},
"secondary_marker": {
"width": 20,
"height": 50,
"x": 20,
"y": 0,
"pixelRatio": 2
}
}
スプライト ID の取得方法
スプライトは長期間静的であることが多いため、一意の URL を持つ変更不可能なスプライトを提供しています。これにより、長時間のキャッシュ期間を持つことが可能になり、読み込み時間の短縮につながります。これにより、スプライトの下で更新されてもスタイルが壊れません。これらの一意の URL は、URL に挿入できる sprite_id
により可能となります。
スプライト画像を Add new image to sprite エンドポイントまたは Add multiple new images to sprite エンドポイントを使用してアップロードした後、スタイルを更新 リクエストを行います。スタイル更新のレスポンス ペイロードには、sprite
ペイロードに一意のスプライト URL が含まれます。
注: Mapbox Studio はこの作業を自動で行ってくれます。
サポートされているライブラリ: スプライト画像または JSON の取得
Mapbox ラッパーライブラリは、既存のアプリケーションに Mapbox API を統合するのに役立ちます。次の SDK がこのエンドポイントをサポートしています。
SDK ドキュメントを参照して、このエンドポイントをクエリするための関連メソッドの使用例や詳細を確認してください。
スプライトに新しい画像を追加する
既存のスプライトに新しい画像を追加します。リクエスト本体は raw SVG データ である必要があります。
必須パラメータ | タイプ | 説明 |
---|---|---|
username | string | スタイル所有アカウントのユーザー名 |
style_id | string | スプライトが属するスタイルのID |
icon_name | string | スタイルに追加される新しい画像の名前 |
リクエスト例: スプライトに新しい画像を追加する
# 既存スプライトに新しい画像(`aerialway`)を追加
$curl -X PUT \
"https://api.mapbox.com/styles/v1/YOUR_MAPBOX_USERNAME/{style_id}/sprite/aerialway?access_token=YOUR_SECRET_MAPBOX_ACCESS_TOKEN" \
--data @aerialway-12.svg
レスポンス: スプライトに新しい画像を追加する
このエンドポイントへの成功したリクエストのレスポンスは、更新されたスプライトとなります。
レスポンス例: スプライトに新しい画像を追加する
{
"newsprite": {
"width": 1200,
"height": 600,
"x": 0,
"y": 0,
"pixelRatio": 1
},
"default_marker": {
"width": 20,
"height": 50,
"x": 0,
"y": 600,
"pixelRatio": 1
}
}
サポートされているライブラリ: スプライトに新しい画像を追加する
Mapbox ラッパーライブラリは既存のアプリケーションに Mapbox API を統合するのに役立ちます。次の SDK がこのエンドポイントをサポートしています。
SDK ドキュメントを参照して、このエンドポイントをクエリするための関連メソッドの使用例や詳細を確認してください。
スプライトに複数の新しい画像を追加する
Mapbox スタイルの既存のスプライトに複数の新しい画像をバッチで追加します。リクエスト本体は images
というフォームフィールド名を使用する multipart フォームデータである必要があります。
1 回のリクエストには最大 25 個の画像ファイルを含めることができます。リクエスト内の各個別の画像ファイルは 30 KB 未満でなければなりません。
必須パラメータ | タイプ | 説明 |
---|---|---|
username | string | スタイル所有アカウントのユーザー名 |
style_id | string | スプライトが属するスタイルのID |
リクエスト例: スプライトに複数の新しい画像を追加する
# ローカルファイル ('star.svg' と 'square.svg') から既存スプライトに 2 つの新しい画像を追加:
$curl -F images=@star.svg -F images=@square.svg \
"https://api.mapbox.com/styles/v1/YOUR_MAPBOX_USERNAME/{style_id}/sprite?access_token=YOUR_SECRET_MAPBOX_ACCESS_TOKEN"
レスポンス: スプライトに複数の新しい画像を追加する
このエンドポイントへの成功したリクエストのレスポンスは、更新されたスプライトとなります。
レスポンス例: スプライトに複数の新しい画像を追加
{
"star": {
"width": 15,
"height": 15,
"x": 0,
"y": 0,
"pixelRatio": 1
},
"square": {
"width": 15,
"height": 15,
"x": 0,
"y": 15,
"pixelRatio": 1
},
"default_marker": {
"width": 20,
"height": 50,
"x": 0,
"y": 65,
"pixelRatio": 1
}
}
サポートされているライブラリ: スプライトに複数の新しい画像を追加する
Mapbox ラッパーライブラリは、既存のアプリケーションに Mapbox API を統合するのに役立ちます。次の SDK がこのエンドポイントをサポートしています。
SDK ドキュメントを参照して、このエンドポイントをクエリするための関連メソッドの使用例や詳細を確認してください。
スプライトから画像を削除する
既存のスプライトから画像を削除します。
必須パラメータ | タイプ | 説明 |
---|---|---|
username | string | スタイル所有アカウントのユーザー名 |
style_id | string | スプライトが属するスタイルのID |
icon_name | string | スタイルから削除する画像の名前 |
リクエスト例: スプライトから画像を削除する
$curl -X DELETE "https://api.mapbox.com/styles/v1/YOUR_MAPBOX_USERNAME/{style_id}/sprite/{icon_name}?access_token=YOUR_SECRET_MAPBOX_ACCESS_TOKEN"
レスポンス: スプライトから画像を削除する
このエンドポイントへの成功したリクエストのレスポンスは、変更されたスプライトとなります。
レスポンス例: スプライトから画像を削除する
{
"default_marker": {
"width": 20,
"height": 50,
"x": 0,
"y": 600,
"pixelRatio": 1
},
"secondary_marker": {
"width": 20,
"height": 50,
"x": 20,
"y": 600,
"pixelRatio": 1
}
}
サポートされているライブラリ: スプライトから画像を削除する
Mapbox ラッパーライブラリは、既存のアプリケーションに Mapbox API を統合するのに役立ちます。次の SDK がこのエンドポイントをサポートしています。
SDK ドキュメントを参照して、このエンドポイントをクエリするための関連メソッドの使用例や詳細を確認してください。
スプライトから複数の画像を削除する
既存のスプライトから複数の画像を一括削除します。
必須パラメータ | タイプ | 説明 |
---|---|---|
username | string | スタイル所有アカウントのユーザー名 |
style_id | string | スプライトが属するスタイルのID |
リクエスト本体は、指定されたスプライトから削除する画像の名前の JSON エンコード配列である必要があります。
リクエスト例: スプライトから複数の画像を削除する
# 既存のスプライトから "star" および "square" という名前の 2 つの画像を削除します。
$curl -X DELETE "https://api.mapbox.com/styles/v1/YOUR_MAPBOX_USERNAME/{style_id}/sprite/?access_token=YOUR_SECRET_MAPBOX_ACCESS_TOKEN" \
--data '["star", "square"]' \
--header "Content-Type:application/json"
レスポンス: スプライトから複数の画像を削除する
このエンドポイントへの成功したリクエストのレスポンスは、変更されたスプライトとなります。
レスポンス例: スプライトから複数の画像を削除する
{
"default_marker": {
"width": 20,
"height": 50,
"x": 0,
"y": 600,
"pixelRatio": 1
},
"secondary_marker": {
"width": 20,
"height": 50,
"x": 20,
"y": 600,
"pixelRatio": 1
}
}
サポートされているライブラリ: スプライトから複数の画像を削除する
Mapbox ラッパーライブラリは、既存のアプリケーションに Mapbox API を統合するのに役立ちます。次の SDK がこのエンドポイントをサポートしています。
SDK ドキュメントを参照して、このエンドポイントをクエリするための関連メソッドの使用例や詳細を確認してください。
スタイル API のエラー
レスポンス本体 message | HTTP ステータスコード | 説明 |
---|---|---|
Not Authorized - Invalid Token | 401 | クエリで使用したアクセス トークンを確認してください。 |
This endpoint requires a token with {scope} scope | 403 | クエリで使用されたアクセス トークンには、指定された scope が必要です。 |
Forbidden | 403 | 要求されたアカウントのスタイルを表示する権限がありません。 一部の場合では、URL 制限付きアクセス トークンを使用すると 403 エラーが発生する場合もあります。詳細については、トークン管理ガイド を参照してください。 |
Style not found | 404 | クエリで使用したスタイル ID を確認してください。 |
Failed to create style | 422 | スタイル作成時にリクエスト本体の JSON 構文を確認してください。 |
スタイル API の制約と制限
- Mapbox Styles API エンドポイントのデフォルトのレート制限は 2,000 リクエスト/分 です。もし、レート制限をの数を高くしたい場合は、お問い合わせください。.
- レート制限を超えると、
HTTP 429 Too Many Requests
レスポンスが返されます。レート制限ヘッダーの情報については、レート制限ヘッダー セクションを参照してください。 - スタイルは 15 を超えるソースを参照することはできません。
- スタイルは 1 MB を超えることはできません。この制限はスタイルドキュメント自体にのみ適用され、スプライト、フォント、タイルセット、その他の参照リソースには適用されません。
- アカウントにはその 価格プラン に関係なく無制限のスタイルを持つことができます。
- Styles API からのレスポンスはデバイスと CDN の両方の TTL を 15 分に設定します。
- キャッシュに関する一般的な情報については、Maps API キャッシュトラブルシューティング ガイド を参照してください。
Styles API スプライトの制約および制限
- 各画像は 400 KB 未満でなければなりません。
- Mapbox は大部分の SVG プロパティをサポートしていますが、一部のプロパティはサポートしていません。これらの制限に関する詳細は、SVG トラブルシューティング ガイド に記載されています。
- 画像は各次元で最大 512 ピクセルです。
- 画像名は 255 文字未満でなければなりません。
- スプライトには最大 1,000 個の画像を含むことができます。
以上が、Mapbox Styles API の日本語による完全なドキュメントです。必要に応じて各 API エンドポイントの使用方法や制限事項について確認することができます。