Roads API は、特定の道路セグメントに掲示されている制限速度を返します。速度制限が可変の道路セグメントの場合は、そのセグメントのデフォルトの速度制限が返されます。
Roads API から返される速度制限データの精度は保証されません。提供される速度制限データはリアルタイムではなく、推定値、不正確、不完全、または古くなっている可能性があります。速度制限データを利用できるリージョンについては、対応範囲の詳細をご覧ください。
リクエスト
速度制限のリクエストは、HTTPS で送信する必要があります。形式は
https://roads.googleapis.com/v1/speedLimits?parameters&key=YOUR_API_KEY
です。
パラメータの使用
必須パラメータ
path
パラメータまたはplaceId
パラメータ。path
- パスを表す緯度と経度のペアのリスト(最大 100 個)。緯度と経度の値はカンマで区切る必要があります。 緯度と経度のペアはパイプ文字「|」で区切る必要があります。path
パラメータを指定すると、API はまず、snapToRoads
リクエストと同様に、車両が通行する可能性が高い道路へのパスをスナップしてから、関連する道路セグメントの速度制限を決定します。API がパスをスナップしない場合は、以下で説明するようにplaceId
パラメータを渡す必要があります。次の例は、3 つの緯度と経度のペアを持つpath
パラメータpath=60.170880,24.942795|60.170879,24.942796|60.170877,24.942796
を示しています。placeId
- 1 つ以上の道路セグメントを表すプレイス ID。 各プレイス ID が、異なる種類の場所ではなく、道路セグメントを参照していることを確認してください。1 回のリクエストで最大 100 個のプレイス ID を渡すことができます。API では、指定されたプレイス ID では道路のスナップは行われません。レスポンスには、リクエストの各プレイス ID の速度制限が含まれます。snapToRoads
リクエストまたはnearestRoads
リクエストを送信して関連するプレイス ID を特定し、それらをspeedLimits
リクエストへの入力として指定できます。次の例は、2 つのプレイス ID を指定したplaceId
パラメータです。placeId=ChIJX12duJAwGQ0Ra0d4Oi4jOGE&placeId=ChIJLQcticc0GQ0RoiNZJVa5GxU
key
- アプリケーションの API キー。アプリケーションは、Roads API にリクエストを送信するたびに自身を識別する必要があります。そのためには、各リクエストに API キーを含めます。キーの取得方法を確認する。
オプション パラメータ
units
- 制限速度を 1 時間に km またはマイルで返すかどうかを指定します。KPH
またはMPH
に設定できます。デフォルトはKPH
です。
レスポンス
speedLimits
レスポンスには、次の要素が含まれる場合があります。
speedLimits
- 道路のメタデータの配列。各要素は次のフィールドで構成されます。placeId
- 場所の一意の識別子。Roads API によって返されるすべてのプレイス ID は、道路セグメントに対応しています。speedLimit
- 該当する道路セグメントの制限速度。units
-KPH
またはMPH
を返します。
snappedPoints
- スナップされたポイントの配列。この配列は、リクエストにpath
パラメータが含まれている場合にのみ存在します。各ポイントは次のフィールドで構成されています。location
-latitude
とlongitude
の値が含まれます。originalIndex
- 元のリクエスト内の対応する値を示す整数。リクエストの各値は、レスポンスのスナップ値にマッピングされる必要があります。これらの値は0
からインデックス付けされるため、originalIndex
が4
のポイントは、path
パラメータに渡される 5 番目の緯度と経度のスナップ値になります。placeId
- 場所の一意の識別子。Roads API によって返されるすべてのプレイス ID は、道路セグメントに対応しています。制限速度リクエストでplaceId
を渡して、その道路セグメントの速度制限を求めることができます。
warning_message
- ユーザーに表示される警告を含む文字列。
パスを使用したリクエストの例
このリクエストは、ポルトガルのリスボンのヴァスコ ダ ガマ橋をまたぐパスで、指定された緯度と経度のペアに最も近い各道路セグメントの速度制限を取得します。
リクエスト
https://roads.googleapis.com/v1/speedLimits?path=38.75807927603043,-9.03741754643809|38.6896537,-9.1770515|41.1399289,-8.6094075&key=YOUR_API_KEY
レスポンス
{ speedLimits: [ { placeId: "ChIJX12duJAwGQ0Ra0d4Oi4jOGE", speedLimit: 105, units: "KPH" }, { placeId: "ChIJLQcticc0GQ0RoiNZJVa5GxU", speedLimit: 70, units: "KPH" }, { placeId: "ChIJJ4vQRudkJA0RpednU70A-5M", speedLimit: 55, units: "KPH" } ], snappedPoints: [ { location: { latitude: 38.75807927603043, longitude: -9.037417546438084 }, originalIndex: 0, placeId: "ChIJX12duJAwGQ0Ra0d4Oi4jOGE" }, { location: { latitude: 38.689653701836896, longitude: -9.177051486847693 }, originalIndex: 1, placeId: "ChIJLQcticc0GQ0RoiNZJVa5GxU" }, { location: { latitude: 41.13993011767777, longitude: -8.609400794783655 }, originalIndex: 2, placeId: "ChIJJ4vQRudkJA0RpednU70A-5M" } ], warningMessage: "Input path is too sparse. You should provide a path where consecutive points are closer to each other. Refer to the 'path' parameter in Google Roads API documentation." }
上記のレスポンスには、ポイントのスパース性に関する警告メッセージがあります。任意の地点で最も近い道路セグメントの制限速度をリクエストする場合は、代わりに nearestRoads
エンドポイントから取得したプレイス ID を使用して speedLimits
を呼び出す必要があります。
プレイス ID を使用したリクエストの例
緯度と経度のペアを使用する代わりに、道路セグメントのプレイス ID を渡すことができます。道路セグメントのプレイス ID は、snapToRoads
リクエストまたは nearestRoads
リクエストを使って取得することをおすすめします。プレイス ID を渡すと、API は各プレイス ID で表される道路セグメントの制限速度を返します。この API は、提供されたプレイス ID に道路スナップを適用しません。
次の例では、ポルトガルのリスボンのヴァスコ ダ ガマ橋を横断する一部の道路セグメントについて、制限速度をリクエストしています。
リクエスト
https://roads.googleapis.com/v1/speedLimits?placeId=ChIJX12duJAwGQ0Ra0d4Oi4jOGE&placeId=ChIJLQcticc0GQ0RoiNZJVa5GxU&placeId=ChIJJ4vQRudkJA0RpednU70A-5M&key=YOUR_API_KEY
レスポンス
{ "speedLimits": [ { placeId: "ChIJX12duJAwGQ0Ra0d4Oi4jOGE", speedLimit: 105, units: "KPH" }, { placeId: "ChIJLQcticc0GQ0RoiNZJVa5GxU", speedLimit: 70, units: "KPH" }, { placeId: "ChIJJ4vQRudkJA0RpednU70A-5M", speedLimit: 55, units: "KPH" } ] }
使用に関する推奨事項
Speed Limit サービスの呼び出し数を最小限に抑えるには、5 ~ 15 分間隔でアセットの場所をサンプリングすることをおすすめします(正確な値はアセットの移動速度によって異なります)。アセットが静止している場合は、1 つのロケーション サンプルで十分です(複数の呼び出しを行う必要はありません)。
全体的なレイテンシを最小限に抑えるため、モバイル アセットの場所を受け取るたびに API を呼び出すのではなく、ある程度データが蓄積されたら制限速度サービスを呼び出すことをおすすめします。
一部またはすべての速度制限がないのはなぜですか?
speedLimits
が欠落する最も一般的な原因は、道路セグメントではない場所に速度制限をリクエストした場合です。
上の例では、ヴァスコ ダ ガマ橋を使ってコンセプトを説明しています。この橋は、リオテジョを渡る E90 号線を支えています。ブリッジ自体のプレイス ID は ChIJUzt97ZEwGQ0RM1JzQfqoDtU です。上のレスポンスの最初の道路セグメントは E90 道路の一部で、プレイス ID は ChiJX12duJAwGQ0Ra0d4Oi4jOGE です。このリクエスト例では、道路の場所 ID を橋のプレイス ID に置き換えると、レスポンスでは speedLimits
配列に 2 つの制限速度しかありません。これは、橋のプレイス ID が個々の道路区間を参照していないためです。さらに、プレイス ID が道路セグメントのものでない場合、レスポンスには速度制限は含まれません。
プレイス ID を使って制限速度リクエストを行う場合は、異なるタイプの場所ではなく、道路区間を参照するようにしてください。個々の道路セグメントのプレイス ID を取得するには、snapToRoads
リクエストか nearestRoads
リクエストを使用します。どちらのリクエストも 1 回の呼び出しで複数のプレイス ID を返すことができます。