Routes API は、経路を計算する際、指定された地点と設定パラメータを入力として使用します。API は、default ルートと 1 つ以上の代替ルートを含むレスポンスを返します。
レスポンスには、リクエストしたフィールドに応じて、さまざまな種類のルートやその他のデータを含めることができます。
回答に含めるには | こちらのドキュメントをご覧ください |
---|---|
車両のエンジンの種類に基づく、燃料またはエネルギー効率が最も高いルート。 | 環境に優しいルートを設定する |
最大 3 つの代替ルート | 代替ルートをリクエストする |
ルート全体、ルートの各区間、区間の各ステップのポリライン。 | ルートのポリラインをリクエストする |
通行料金の割引や運転手または車両が利用できるパスを考慮した推定通行料金。 | 通行料を計算する |
言語コードと測定単位(インペリアルまたはメートル法)によってローカライズされたレスポンス。 | ローカライズされた値をリクエストする |
ナビゲーション手順を HTML テキスト文字列としてフォーマットするには、HTML_FORMATTED_NAVIGATION_INSTRUCTIONS を extraComputations に追加します。 |
追加の計算 |
入力オプションの一覧については、使用可能なルート オプションとリクエストの本文をご覧ください。
レスポンスを使用すると、要件に合った適切なルートを選択するために必要な情報を顧客に提供できます。
フィールド マスクについて
ルートを計算するメソッドを呼び出す際には、レスポンスで返すフィールドを定義するフィールド マスクを指定する必要があります。返されるフィールドのデフォルト リストはありません。このリストを省略すると、メソッドはエラーを返します。
このドキュメントの例では、フィールド マスクを考慮せずにレスポンス オブジェクト全体を示しています。本番環境では、レスポンスにはフィールド マスクで明示的に指定したフィールドのみが含まれます。
詳しくは、返される情報を選択するをご覧ください。
著作権の表示について
検索結果をユーザーに表示する場合、次の著作権に関する文言を含める必要があります。
Powered by Google, ©YEAR Google
次に例を示します。
Powered by Google, ©2023 Google
ルート、区間、歩数について
Routes API から返されるレスポンスを確認する前に、経路を構成するコンポーネントについて理解しておく必要があります。
レスポンスには、次のルート コンポーネントに関する情報を含めることができます。
ルート: 出発地の地点から任意の中間地点を経由し、目的地の地点に至るルート全体。ルートは 1 つ以上の区間で構成されます。
区間: ルート内のある地点から次の地点までの経路。各区間は、1 つ以上の個別のステップで構成されます。
ルートには、各ウェイポイントから次のウェイポイントまでの経路の区間が 1 つずつ含まれます。たとえば、ルートに 1 つの出発地の地点と 1 つの目的地の地点が含まれている場合、ルートには 1 つの区間が含まれます。中間地点と呼ばれる、出発地と目的地の後のルートに追加する地点ごとに、API によって別個の区間が追加されます。
API では、パススルー中間地点の区間は追加されません。たとえば、出発地の地点、通過の中間地点、目的地の地点を含むルートには、出発地から目的地までの 1 つの区間のみが含まれます。パススルー地点について詳しくは、パススルー地点を定義するをご覧ください。
ステップ: ルートの区間に沿った 1 つの指示。ステップはルートの 最小単位ですたとえば、ステップで「大通りを左に曲がる」と示すことができます。
レスポンスの内容
API レスポンスを表す JSON オブジェクトには、次のトップレベル プロパティが含まれています。
routes
。Route 型の要素の配列。routes
配列には、API から返されたルートごとに 1 つの要素が含まれます。配列には最大 5 つの要素(デフォルト ルート、環境に優しいルート、最大 3 つの代替ルート)を含めることができます。geocodingResults
: GeocodingResults 型の要素の配列。住所文字列または Plus コードとして指定したリクエスト内のすべての場所(出発地、目的地、中間地点)について、API はプレイス ID 検索を実行します。この配列の各要素には、ビジネスに対応するプレイス ID が含まれます。プレイス ID または緯度/経度の座標として指定されたリクエスト内の場所は含まれません。プレイス ID または緯度と経度の座標を使用してすべてのビジネス情報を指定した場合、この配列は提供されません。FallbackInfo 型の
fallbackInfo
。API ですべての入力プロパティからルートを計算できない場合は、別の計算方法が使用されることがあります。フォールバック モードが使用されている場合、このフィールドにはフォールバック レスポンスに関する詳細情報が含まれます。それ以外の場合、このフィールドは設定されません。
レスポンスの形式は次のとおりです。
{ // The routes array. "routes": [ { object (Route) } ], // The place ID lookup results. "geocodingResults": [ { object (GeocodedWaypoint) } ], // The fallback property. "fallbackInfo": { object (FallbackInfo) } }
ルート配列を解読する
レスポンスには routes
配列が含まれます。ここで、各配列要素は Route 型です。各配列要素は、出発地から目的地までのルート全体を表します。API は常に、デフォルト ルートと呼ばれる少なくとも 1 つのルートを返します。
追加のルートをリクエストできます。環境に優しいルートをリクエストする場合、配列にはデフォルト ルートと環境に優しいルートの 2 つの要素を含めることができます。または、リクエストの computeAlternativeRoutes
を true
に設定して、レスポンスに最大 3 つの代替ルートを追加します。
配列内の各ルートは routeLabels
配列プロパティで識別されます。
値 | 説明 |
---|---|
DEFAULT_ROUTE |
デフォルト ルートを指定します。 |
FUEL_EFFICIENT |
環境に優しいルートを識別する ID を指定します。 |
DEFAULT_ROUTE_ALTERNATE |
代替ルートを示します。 |
legs
配列にはルートの各区間の定義が含まれます。残りのプロパティ(distanceMeters
、duration
、polyline,
など)には、ルート全体に関する情報が含まれています。
{ "routeLabels": [ enum (RouteLabel) ], "legs": [ { object (RouteLeg) } ], "distanceMeters": integer, "duration": string, "routeLabels": [string], "staticDuration": string, "polyline": { object (Polyline) }, "description": string, "warnings": [ string ], "viewport": { object (Viewport) }, "travelAdvisory": { object (RouteTravelAdvisory) } "routeToken": string }
現在の運転状況やその他の要因により、デフォルト ルートと環境に優しいルートは同じになる場合があります。この場合、routeLabels
配列には DEFAULT_ROUTE
と FUEL_EFFICIENT
の両方のラベルが含まれます。
{ "routes": [ { "routeLabels": [ "DEFAULT_ROUTE", "FUEL_EFFICIENT" ], … } ] }
legs 配列について
レスポンス内の各 route
には legs
配列が含まれます。この配列の各 legs
配列要素は RouteLeg 型です。配列内の各区間は、ルートを経由するある地点から次の地点までの経路を定義します。ルートには常に 1 つ以上の区間が含まれます。
legs
プロパティには、steps
配列内の区間の各ステップの定義が含まれます。残りのプロパティ(distanceMeters
、duration
、polyline
など)には、区間に関する情報が含まれます。
{ "distanceMeters": integer, "duration": string, "staticDuration": string, "polyline": { object (Polyline) }, "startLocation": { object (Location) }, "endLocation": { object (Location) }, "steps": [ { object (RouteLegStep) } ], "travelAdvisory": { object (RouteLegTravelAdvisory) } }
steps 配列を理解する
レスポンスの各区間には steps
配列が含まれます。この配列の各 steps
配列要素は RouteLegStep 型です。1 ステップは、その区間の 1 つの指示に対応します。1 つの区間には常に少なくとも 1 つのステップが含まれます。
steps
配列の各要素には、ステップ命令を含む NavigationInstruction 型の navigationInstruction
プロパティが含まれます。次に例を示します。
"navigationInstruction": { "maneuver": "TURN_LEFT", "instructions": "Turn left toward Frontage Rd" }
instructions
には、ステップに関する追加情報が含まれる場合があります。次に例を示します。
"navigationInstruction": { "maneuver": "TURN_SLIGHT_LEFT", "instructions": "Slight left (signs for I-90 W/Worcester)nParts of this road may be closed at certain times or days" }
ステップの残りのプロパティは、ステップに関する情報を記述します(distanceMeters
、duration
、polyline
など)。
{ "distanceMeters": integer, "staticDuration": string, "polyline": { object (Polyline) }, "startLocation": { object (Location) }, "endLocation": { object (Location) }, "navigationInstruction": { object (NavigationInstruction) } }
ステップの指示の言語を指定します
API は、優先言語を監視しながら、必要に応じてユーザーが読み取れるスクリプトに文字変換されたルート情報をローカル言語で返します。住所コンポーネントはすべて同じ言語で返されます。
リクエストの
languageCode
パラメータを使用して、サポートされている言語のリストからルート言語を明示的に設定します。サポートされている言語は頻繁に更新されるため、このリストがすべての言語を網羅しているとは限りません。指定した言語で名前を使用できない場合、API は最も近い言語を使用します。
指定された言語は、API が返す結果のセットと、それらが返される順序に影響を与える可能性があります。ジオコーダによる略語の解釈は言語によって異なります。たとえば、通りの略語や、ある言語では有効な同義語は別の言語では使用できない同義語などがこれに該当します。たとえば、ハンガリー語では、「utca」と「tér」は「街」の同義語です。
geocodingResults の配列について
住所文字列または Plus コードとして指定されたリクエストに含まれるすべての場所(出発地、目的地、中間地点)について、API は対応するプレイス ID を持つ最も関連性の高い場所を探します。geocodingResults
配列の各要素には、場所 ID として店舗を含む placeID
フィールドと、地域タイプ(street_address
、premise
、airport
など)を指定する type
フィールドが含まれます。
geocodingResults
配列には、次の 3 つのフィールドがあります。
origin
: 住所文字列または Plus Code として指定された場合は、出発地のプレイス ID。それ以外の場合、このフィールドはレスポンスから除外されます。destination
: 住所文字列または Plus Code として指定された場合は、目的地のプレイス ID。それ以外の場合、このフィールドはレスポンスから除外されます。intermediates
: 住所文字列または Plus Code として指定された中間地点のプレイス ID を含む配列。プレイス ID または緯度と経度の座標を使用して中間地点を指定すると、レスポンスから除外されます。レスポンスのintermediateWaypointRequestIndex
プロパティを使用して、レスポンスのプレイス ID に対応するリクエストの中間ウェイポイントを決定します。
"geocodingResults": { "origin": { "geocoderStatus": {}, "type": [ enum (Type) ], "placeId": string }, "destination": { "geocoderStatus": {}, "type": [ enum (Type) ], "placeId": string }, "intermediates": [ { "geocoderStatus": {}, "intermediateWaypointRequestIndex": integer, "type": [ enum (Type) ], "placeId": string }, { "geocoderStatus": {}, "intermediateWaypointRequestIndex": integer, "type": [ enum (Type) ], "placeId": string } ] }
ローカライズされたレスポンス値について
ローカライズされたレスポンス値は、返されるパラメータ値にローカライズされたテキストを提供する追加のレスポンス フィールドです。移動時間、距離、単位系(メートル法またはヤードポンド法)については、ローカライズされたテキストが提供されます。ローカライズされた値はフィールド マスクを使用してリクエストし、言語と単位系を指定するか、API によって推定された値を使用します。詳しくは、LocalizedValues をご覧ください。
たとえば、ドイツ語(de)とヤードポンド単位の言語コードを指定した場合、distanceMeters
の値は 49889.7 になりますが、距離の測定値がドイツ語とインペリアル単位で提供されるローカライズされたテキストも「31 Meile」になります。
ローカライズされた値の表示例を次に示します。
{ "localized_values": { "distance": { "text": "31,0 Meile/n" }, "duration": { "text": 38 Minuten}. "static_duration": { "text": 36 Minuten}. } }
言語または単位系を指定しない場合、API は次のように言語と単位を推測します。
ComputeRoutes
メソッドは、起点のウェイポイントから位置と距離の単位を推測します。そのため、米国でのルーティング リクエストの場合、API はen-US
言語とIMPERIAL
単位を推測します。ComputeRouteMatrix
メソッドのデフォルトは、「en-US」言語と METRIC 単位です。