Styles API | API Docs

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 Satellite	`mapbox://styles/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 Outdoors	`mapbox://styles/mapbox/outdoors-v12`
Mapbox Light	`mapbox://styles/mapbox/light-v11`
Mapbox Dark	`mapbox://styles/mapbox/dark-v11`
Mapbox Satellite	`mapbox://styles/mapbox/satellite-v9`
Mapbox Satellite Streets	`mapbox://styles/mapbox/satellite-streets-v12`
Mapbox Navigation Day	`mapbox://styles/mapbox/navigation-day-v1`
Mapbox Navigation Night	`mapbox://styles/mapbox/navigation-night-v1`

スタイルオブジェクト

スタイルオブジェクトは 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を使用してスタイルやスプライトの公開バージョンに変更を加えると、ドラフトバージョンにはその変更が反映されません。

スタイルを取得する

get

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

styles:read

token scope

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 がこのエンドポイントをサポートしています。

Mapbox JavaScript SDK

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

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

get

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

styles:list

token scope

特定のアカウントのスタイル一覧を取得します。このエンドポイントはページネーションをサポートします。スタイルは一般的にかなり大きいため、このエンドポイントへのレスポンスは他のリストエンドポイントよりも早くページネートを開始する可能性があります。アカウントに多数のスタイルがある場合、すべてを取得するために 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 JavaScript SDK

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

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

get

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

styles:download

token scope

Note

このエンドポイントへのアクセスはリクエストによって提供されます。このアクセスを有効にするには、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

スタイルを作成する

post

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

styles:write

token scope

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

さらに、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 JavaScript SDK

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

スタイルを更新する

patch

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

styles:write

token scope

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

さらに、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 JavaScript SDK

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

スタイルを削除する

delete

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

styles:write

token scope

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

必須パラメータ	タイプ	説明
`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 JavaScript SDK

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

スタイルを保護する

put

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

styles:protect

token scope

Note

このエンドポイントへのアクセスはリクエストによって提供されます。このアクセスを有効にするには、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 をリクエストする

get

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

styles:read

token scope

埋め込み可能または共有可能な 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 がこのエンドポイントをサポートしています。

Mapbox JavaScript SDK

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

マップの WMTS ドキュメントを取得する

get

https://api.mapbox.com/styles/v1/{username}/{style_id}/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 の取得

get

https://api.mapbox.com/styles/v1/{username}/{style_id}/{sprite_id}/sprite{@2x}.{format}

styles:read

token scope

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 JavaScript SDK

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

スプライトに新しい画像を追加する

put

https://api.mapbox.com/styles/v1/{username}/{style_id}/sprite/{icon_name}

styles:write

token scope

既存のスプライトに新しい画像を追加します。リクエスト本体は 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 がこのエンドポイントをサポートしています。

Mapbox JavaScript SDK

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

スプライトに複数の新しい画像を追加する

post

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

styles:write

token scope

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 JavaScript SDK

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

スプライトから画像を削除する

delete

https://api.mapbox.com/styles/v1/{username}/{style_id}/sprite/{icon_name}

styles:write

token scope

既存のスプライトから画像を削除します。

必須パラメータ	タイプ	説明
`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 JavaScript SDK

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

スプライトから複数の画像を削除する

delete

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

styles:write

token scope

既存のスプライトから複数の画像を一括削除します。

必須パラメータ	タイプ	説明
`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 JavaScript 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 エンドポイントの使用方法や制限事項について確認することができます。

追加の開発者リソース

このpageは役に立ちましたか？

Mapbox スタイル​

Mapbox Standard​

Mapbox クラシックスタイル​

スタイルオブジェクト​

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

ドラフト​

スタイルを取得する​

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

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

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

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

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

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

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

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

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

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

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

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

スタイルを作成する​

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

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

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

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

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

スタイルを更新する​

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

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

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

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

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

スタイルを削除する​

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

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

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

スタイルを保護する​

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

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

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

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

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

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

マップの WMTS ドキュメントを取得する​

リクエスト例: マップの WMTS ドキュメントを取得する​

レスポンス: マップの WMTS ドキュメントを取得する​

スプライト​

スプライト画像または JSON の取得​

リクエスト例: スプライト画像または JSON を取得する​

レスポンス: スプライト画像または JSON の取得​

レスポンス例: スプライト画像または JSON の取得​

スプライト ID の取得方法​

サポートされているライブラリ: スプライト画像または JSON の取得​

スプライトに新しい画像を追加する​

リクエスト例: スプライトに新しい画像を追加する​

レスポンス: スプライトに新しい画像を追加する​

レスポンス例: スプライトに新しい画像を追加する​

サポートされているライブラリ: スプライトに新しい画像を追加する​

スプライトに複数の新しい画像を追加する​

リクエスト例: スプライトに複数の新しい画像を追加する​

レスポンス: スプライトに複数の新しい画像を追加する​

レスポンス例: スプライトに複数の新しい画像を追加​

サポートされているライブラリ: スプライトに複数の新しい画像を追加する​

スプライトから画像を削除する​

リクエスト例: スプライトから画像を削除する​

レスポンス: スプライトから画像を削除する​

レスポンス例: スプライトから画像を削除する​

サポートされているライブラリ: スプライトから画像を削除する​

スプライトから複数の画像を削除する​

リクエスト例: スプライトから複数の画像を削除する​

レスポンス: スプライトから複数の画像を削除する​

レスポンス例: スプライトから複数の画像を削除する​

サポートされているライブラリ: スプライトから複数の画像を削除する​

スタイル API のエラー​

スタイル API の制約と制限​

Styles API スプライトの制約および制限​

Mapbox スタイル

Mapbox Standard

Mapbox クラシックスタイル

スタイルオブジェクト

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

ドラフト

スタイルを取得する

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

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

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

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

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

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

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

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

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

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

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

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

スタイルを作成する

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

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

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

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

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

スタイルを更新する

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

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

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

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

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

スタイルを削除する

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

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

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

スタイルを保護する

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

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

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

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

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

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

マップの WMTS ドキュメントを取得する

リクエスト例: マップの WMTS ドキュメントを取得する

レスポンス: マップの WMTS ドキュメントを取得する

スプライト

スプライト画像または JSON の取得

リクエスト例: スプライト画像または JSON を取得する

レスポンス: スプライト画像または JSON の取得

レスポンス例: スプライト画像または JSON の取得

スプライト ID の取得方法

サポートされているライブラリ: スプライト画像または JSON の取得

スプライトに新しい画像を追加する

リクエスト例: スプライトに新しい画像を追加する

レスポンス: スプライトに新しい画像を追加する

レスポンス例: スプライトに新しい画像を追加する

サポートされているライブラリ: スプライトに新しい画像を追加する

スプライトに複数の新しい画像を追加する

リクエスト例: スプライトに複数の新しい画像を追加する

レスポンス: スプライトに複数の新しい画像を追加する

レスポンス例: スプライトに複数の新しい画像を追加

サポートされているライブラリ: スプライトに複数の新しい画像を追加する

スプライトから画像を削除する

リクエスト例: スプライトから画像を削除する

レスポンス: スプライトから画像を削除する

レスポンス例: スプライトから画像を削除する

サポートされているライブラリ: スプライトから画像を削除する

スプライトから複数の画像を削除する

リクエスト例: スプライトから複数の画像を削除する

レスポンス: スプライトから複数の画像を削除する

レスポンス例: スプライトから複数の画像を削除する

サポートされているライブラリ: スプライトから複数の画像を削除する

スタイル API のエラー

スタイル API の制約と制限

Styles API スプライトの制約および制限