WebサービスAPI
Mapbox WebサービスAPI を使用して、Mapboxのツールやサービスにプログラム的にアクセスできます。これらのAPIを使用して、アカウントに関する情報を取得したり、リソースをアップロードしたり変更したり、コアのMapboxツールを使用したりすることができます。
MapboxのAPIは、Maps、Navigation、Search、Accounts の4つの異なる サービス に分割されています。それぞれのサービスには、このドキュメント内の個別の API があります。これらの概要ページは、サービスを構成する個々の エンドポイント に分割されています。各エンドポイントのドキュメントは エンドポイント ごとに構造化されています。エンドポイントは、特定のURLに位置する1つのアクションを行うメソッドです。
このドキュメントで紹介される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は、ウェブサービス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リクエストが秘密のスコープが必要である場合、例は必要なスコープを指定します。
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分あたりのデフォルトのリクエスト数 |
|---|---|---|
| ベクトルタイルAPI | N/A | 100,000 リクエスト数 |
| ラスタータイルAPI | N/A | 100,000 リクエスト数 |
| 静的画像API | N/A | 1,250 リクエスト数 |
| 静的タイルAPI | N/A | 6,000 リクエスト数 |
| スタイルAPI | N/A | 2,000 リクエスト数 |
| タイルクエリAPI | N/A | 600 リクエスト数 |
| アップロードAPI | N/A | 60 リクエスト数 |
| Mapbox Tiling Service （読み取り） | N/A | 3,000 リクエスト数 |
| Mapbox Tiling Service （書き込み） | N/A | 100 リクエスト数 |
| Mapbox Tiling Service （公開） | N/A | 2 リクエスト数 |
| データセットAPI (読み取り) | N/A | 480 リクエスト数 |
| データセット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 リクエスト数 |
| 最適化API | 12 リクエストあたりの座標数 | 300 リクエスト数 |
| ジオコーディングAPI | N/A | 600 リクエスト数 |
| トークン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にアップグレードされます。
Mapboxウェブサービスは、ドメイン制限なしで 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時刻 で返されます。
ページネーション
ページネーションを使用すると、1つ以上のリクエストを使用してAPIから多数のオブジェクトをリストすることができます。ページネーションは、次のAPIの list エンドポイントでサポートされています:
オブジェクトの1ページを受信した後、応答の Link ヘッダー内の next リンク関係を使用して次のページのオブジェクトをリクエストできます。このプロセスは、サーバーが Link ヘッダーまたは next リンク関係を持たない応答、または Link ヘッダーや next リンク関係を持たない応答を送信するまで繰り返すことができます。これは、コレクションの終わりを示します。
Link: <https://api.mapbox.com/uploads/v1/1454024795582?start=cijywvxlm004rtikohhqf99jv&limit=100>; rel="next"
ページネーションをサポートするMapbox APIエンドポイントでは、オプションの limit パラメータは返すオブジェクトの最大数を指定します。APIはリクエストされたオブジェクト数を返そうとしますが、ページ制限はクエリ応答のサイズに依存するため、より少ないオブジェクトを受け取っても、コレクションの終わりを示すわけではありません。Link ヘッダーまたは next リンク関係が含まれない応答を受信することで、コレクションの終わりを知ることができます。
ページごとに返されるアイテム数は、クエリ応答のサイズに依存するため、ページネーションの開始が特定のアイテム数後に始まることを覚えておくべきです。この数はクエリ応答によって異なり、予測不可能なため、特定のページごとのアイテム数を想定して構築すべきではありません。スタイルは一般的に非常に大きいため、スタイルの一覧 エンドポイントへの応答は他のリストエンドポイントよりも早くページネーションを開始する可能性が高いです。
アプリケーションは、特定のURLを構 築するのではなく、ページネーションに Link ヘッダーを使用する必要があります。これは、いつでも特定のURLが変更される可能性があるためです。 Pythonリクエストライブラリ およびJavaScriptの link-header-parser モジュールは Link ヘッダーをパースすることができます。Link ヘッダーは、RFC 5988の仕様 に従います。
High DPI画像
Mapboxは、画像を提供するすべてのMapsサービスAPIで高DPI画像出力をサポートしています。画像のURLのファイル拡張子の前に @2x を追加すると、画像を2倍のスケールでリクエストすることができます。たとえば、256×256ピクセルのマップタイルは @2x を付けると512×512ピクセルになりますが、同じコンテンツが表示されます。ページ上で表示される際には、画像は引き続き256×256ピクセルのサイズになりますが、元の4ピクセルが1つの画面単位のピクセルを表します。
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 セクションは、関連するメソッドへのリンクを含むライブラリのドキュメントへのリンクを含みます。各ライブラリのドキュメントには、そのライブラリの インストールと使用方法に関する情報が提供されます。