WebサービスAPI
Mapbox WebサービスAPI を使用して、Mapboxのツールやサービスにアクセスできます。これらのAPIを使用して、アカウントに関する情報を取得したり、リソースをアップロードしたり変更したり、コアのMapboxツールを使用したりすることができます。
MapboxのAPIは、Maps、Navigation、Search、Accounts の4つの サービス に分割されています。各サービスには、それぞれの概要ページがあり、その中でサービスを構成する個別のAPIが紹介されています。各APIのドキュメントはエンドポイントごとに構成されています。エンドポイントとは、API内で特定のアクションを実行する特定のメソッドのことで、固有のURLにあります。
このドキュメントで紹介されるMapboxのAPIは、Mapboxの 利用規約 に従う必要があります。
このドキュメントの読み方
このドキュメント内の各APIエンドポイントは、次の複数の部分を使用して説明されています:
- HTTPメソッド:
GET、POST、PUT、PATCH、DELETEが含まれます。 - ベースパス: ドキュメントに記載されているすべてのURLは、ベースパスが
https://api.mapbox.comであることを前提としています。このベースパスはエンドポイントパスの 前に 来ます。 - エンドポイントパス: 例えば、
/directions/v5/{profile}/{coordinates}のように記載されます。 - 必須パラメータ: これらのパラメータはリクエストに含める必要があります。上記の例では、
{profile}と{coordinates}が必須パラメータです。リクエスト時に、プレースホルダーを実際の値に置き換えます。 - オプショナルパラメータ: クエリをカスタマイズするためにリクエストに含めることができるパラメータです。クエリパラメータは、URLの末尾に クエリ文字列のエンコード が追加され。
- トークンのスコープ: もしAPIエンドポイントがデフォルトのアクセストークンではカバーされていないトークンスコープ を必要とする場合、そのスコープが記載されます。
- コード例: 各エンドポイントには、cURL形式の例のリクエストが含まれています。Mapboxは、WebサービスAPIと統合するために使用できる いくつかのSDKやライブラリ を提供しています。該当するエンドポイントのドキュメントには、その言語でのコード例が含まれる関連ツールのドキュメントへのリンクが含まれます。
アクセストークンとトークンスコープ
https://api.mapbox.com/{endpoint}?access_token={your_access_token}
MapboxのAPIエンドポイントにアクセスするには、APIリクエストをアカウントに接続する有効な アクセストークン が必要です。リクエストごとに access_token クエリパラメータを使用して有効なアクセストークンを提供する必要があります。
デフォルトのアクセストークンは、アカウントダッシュボード で利用可能です。また、Access tokens page または Tokens API を使用して追加のトークンを作成および管理することもできます。
新しいアクセストークンを作成する際には、1つ以上の トークン スコープ を設定できます。各スコープは、トークンに異なる権限を付与するため、制限されたAPIにアクセスするために使用できます。このドキュメントでは、各エンドポイントにアクセスするために必要なスコープが明示されています。スコープが指定されていない場合、デフォルトのアクセストークンを使用してそのエンドポイントにアクセスすることができます。
このドキュメントのリクエストの例には、Mapboxアカウントにサインインしている場合、デフォルトのアクセストークンが含まれます。APIリクエストに特別なスコープが必要でない限り、デフォルトのアクセストークンが使用されます。もしリクエストが秘密のスコープが必要である場合、必要なスコープの例を指定します。
APIバージョン管理
各Mapbox APIは、ベースURLで指定されたバージョン文字列があります。特定のMapbox APIのバージョン文字列は、他のMapbox APIとは独立して更新されることがあります。常にMapbox APIの最新バージョンを使用することをお勧めします。
互換性のある変更
次の変更は、Mapbox APIの 互換性のある 変更と見なされます。APIのバージョン文字列は更新されません。
- JSONオブジェクトにプロパティを追加する場合
- 単一のリストリクエストで返されるアイテム数を変更する場合
- レート制限のしきい値を変更する場合
- APIによって生成される識別子の構造や長さを変更する場合
- エラーメッセージを変更する場合
互換性のない変更
次の変更は、 互換性のない 変更と見なされます。APIのバージョン文字列は更新されます。
- JSONオブジェクトからプロパティを削除する場合
- APIのURL構造を変更する場合
使用中のAPIやAPIエンドポイントが非推奨になった場合、少なくとも90日前通知するためにメールが送信されます。
レート制限ヘッダー
Mapbox APIの応答には、以下のレート制限ヘッダーが含まれる場合があります:
| ヘッダー | 説明 |
|---|---|
X-Rate-Limit-Interval | レート制限の間隔の長さ（秒）。常に 60 になります。す。 |
X-Rate-Limit-Limit | 現在のインターバルで制限に達する前に送送信送信できるリクエストの最大数。各個別APIの レートリミット はレート制限セクションにリストされています。 |
X-Rate-Limit-Reset | 現在のインターバルが終了し、レート制限カウンターがリセットされる時刻を示すUnixタイムスタンプ。 |
これらのヘッダーが存在することは予期されるものであり、エラー条件を示すものではありません。
レート制限
各Mapbox APIには、エンドポイントに対して行うリクエストの数を制限するレート制限があります。レート制限を超えると、リクエストが制限され、APIから HTTP 429 Too Many Requests のレスポンスを受け取ります。デフォルトよりも高いレート制限が必要な場合は、Mapbox販売チーム にお問い合わせください。
次の表は、各APIのデフォルトのレート制限を掲載しています。すべてのレート制限は アクセストークン ごとにカウントされます。
| API | リクエストあたりのデフォルトの座標数（coordinates） | 1分あたりのデフォルトのリクエスト数 |
|---|---|---|
| Vector Tiles API | N/A | 100,000 リクエスト数 |
| Raster Tiles API | N/A | 100,000 リクエスト数 |
| Static Images API | N/A | 1,250 リクエスト数 |
| Static Tiles API | N/A | 6,000 リクエスト数 |
| Styles API | N/A | 2,000 リクエスト数 |
| TileQuery API | N/A | 600 リクエスト数 |
| Uploads API | N/A | 60 リクエスト数 |
| Mapbox Tiling Service （読み取り） | N/A | 3,000 リクエスト数 |
| Mapbox Tiling Service （書き込み） | N/A | 100 リクエスト数 |
| Mapbox Tiling Service （公開） | N/A | 2 リクエスト数 |
| Datasets API (読み取り) | N/A | 480 リクエスト数 |
| Datasets API (書き込み) | N/A | 40 リクエスト数 |
| Directions API | 25 リクエストあたりの座標数 | 300 リクエスト数 |
| Isochrone API | 1 リクエストあたりの座標数 | 300 リクエスト数 |
| Map Matching API | 100 リクエストあたりの座標数 | 300 リクエスト数 |
| Matrix API ( driving, walking, and cycling profiles) | 25 リクエストあたりの座標数 | 60 リクエスト数 |
| Matrix API ( driving-traffic profile) | 10 リクエストあたりの座標数 | 30 リクエスト数 |
| Optimization API | 12 リクエストあたりの座標数 | 300 リクエスト数 |
| Geocoding API | N/A | 600 リクエスト数 |
| Tokens API | N/A | 100 リクエスト数 |
URLの長さ制限
MapboxのAPIが返すHTTP 414 URI too long のステータスコードを返す前に受けつける最長のURLは、当社のCDNであるAWS CloudFrontによって課せられた8,192バイトの制限です。詳細については、AWS CloudFront一般制限文書 を参照してください。いくつかのAPIは、この制限の回避策として、クエリパラメータをリクエスト本文に含める POST リクエストを受け入れます。各エンドポイントのドキュメントには、APIが受け入れるHTTPリクエストメソッドが示されています。
HTTPSとCORS
すべてのMapboxへのアクセスはHTTPS経由で行うことをお勧めします。HTTP経由で開始されたリクエストは自動的にHTTPSにアップグレードさ れます。
MapboxWebサービスは、ドメイン制限なしで Cross-Origin Requests をサポートしています。Internet Explorer 8および9をサポートするには、 corslite のように XDomainRequest にフォールバックするライブラリを使用してください。
座標フォーマット
Mapbox APIに地理座標を提供する際、それらは 経度、緯度 の順序で、WGS84座標系 の10進度で指定されている必要があります。このパターンは、GeoJSONやKMLを含む既存の標準に準拠しています。Mapbox APIは、地理空間データを表現する場合、可能な限りGeoJSON形式を使用します。
この 経度、緯度 の順序以外の例外は、ポリライン形式 であり、[Static Images APIオーバーレイおよび、Directions API、Map Matching API、Optimization API のレスポンスでれていますサポートされるポリライン形式があります。ポリライン入力または出力が指定されている場合、ポリラインのコンテンツは、Googleエンコードされたポリライン形式に従う必要があり、これは 緯度、経度 の順序を指定します。
日付と時間の形式
Mapbox APIから返される日付と時刻は、特に指定されていない限り、RFC 3339 形式で表されます。この形式は、多くのライブラリやプログラム言語で解析可能です。
唯一の例外は、Mapbox Tiling Service（MTS）の タイルJSONメタデータを取得する エンドポイントで、created と modified プロパティが Unix時刻 で返されます。
ページネーション
ページネーションを使用すると、複数のリクエストを使用してAPIから多数のオブジェクトを一覧表示することができます。ページネーションは、次のAPIの list エンドポイントでサポートされています:
オブジェクトの1ページを受信し た後、応答の Link ヘッダー内の next リンクを使用して次のページをリクエストできます。このプロセスは、サーバーが Link ヘッダーまたは next リンクを含まないレスポンスを送信するまで繰り返すことができます。これは、コレクションの終わりを示します。
Link: <https://api.mapbox.com/uploads/v1/1454024795582?start=cijywvxlm004rtikohhqf99jv&limit=100>; rel="next"
ページネーションをサポートするMapbox APIエンドポイントでは、オプションの limit パラメータは返すオブジェクトの最大数を指定します。APIはリクエストされた数のオブジェクトを返そうとしますが、ページネーション開始はクエリ応答のサイズに依存するため、より少ないオブジェクトを受け取っても、コレクションの終わりを示すわけではありません。Link ヘッダーまたは next リンクが含まれないレスポンスを受信することで、コレクションの終わりを知ることができます。
ページごとに返されるアイテム数は、クエリレスポンスのサイズに依存するため、ページネーションの開始が特定のアイテムを返した後に始まることを覚えておくべきです。この数はクエリレスポンスによって異なり、予測不可能なため、特定の数のオブジェクトがページごとに返されることを想定して構築すべきではありません。特に「styles」はデータサイズが大きいため、スタイルの一覧 エンドポイントへでは他のリストエンドポイントよりも早くページネーションを開始する可能性が高いです。
アプリケーションは、特定のURLを構築するのではなく、ページネーションに Link ヘッダーを使用する必要があります。これは、いつでも特定のURLが変更される可能性があるためです。Pythonリクエストライブラリ およびJavaScriptの link-header-parser モジュールは Link ヘッダーを解析することができます。Link ヘッダーは、RFC 5988の仕様 に従います。
高 DPI画像
Mapboxは、画像を提供するすべてのMapsServiceAPIで高DPI画像出力をサポートしています。画像のURLのファイル拡張子の前に @2x を追加すると、画像を2倍のスケールでリクエストすることができます。たとえば、256×256ピクセルのマップタイルは @2x を付けると512×512ピクセルになりますが、同じコンテンツが表示されます。ページ上で表示される際には、画像は引き続き256×256ピクセルのサイズになりますが、元の4ピクセルが画像上では１ピクセルとして表現されますURLの @2x の部分は、フォーマット全体の前に来ます。つまり、.png で終わるURLは @2x.png で高DPI画像をリクエストします。 (MBTilesとしてアップロードされたタイルセットはこのスケールで利用できません。)
SDKおよびライブラリサポート
Mapboxは、次のSDKおよびライブラリを提供して、WebサービスAPIにアクセスして統合する際のサポートを行っています:
- Mapbox Python CLI
- Mapbox Java SDK
- Mapbox JavaScript SDK
- Mapbox Ruby SDK
- Mapbox Search SDK for iOS (Swift)
- Mapbox Search SDK for Android (Kotlin)
- Mapbox Swift/Objective-Cライブラリ:
これらのライブラリの中で、Mapbox APIのエンドポイントをサポートするものは異なります。ライブラリが特定のエンドポイントをサポートしている場合、エンドポイントの Request セクションは、関連するメソッドへのリンクを含むライブラリのドキュメントへのリンクを含みます。各ライブラリのドキュメントには、そのライブラリのインストールと使用方法に関する情報が提供されます。