ルートを計算するには、少なくともルートの出発地と目的地の場所を指定する必要があります。これらの場所は、ルート上のウェイポイントとして定義します。
出発地と目的地に加えて、さまざまなタイプのウェイポイントと、ルートのウェイポイントの処理方法を指定できます。詳細と例については、次のトピックをご覧ください。
ルートの場所を指定する
場所を表すには、ウェイポイント（REST）オブジェクトまたはウェイポイント（gRPC）オブジェクトを作成します。ウェイポイントの定義では、次のいずれかの方法で場所を指定できます。
- プレイス ID（推奨）
- 緯度と経度の座標
- 住所文字列（「シカゴ、イリノイ」、「ダーウィン、NT、オーストラリア」など）
- ナビゲーション ポイント トークン
- Plus Code
リクエスト内のすべてのウェイポイントの場所を同じ方法で指定することも、異なる方法を組み合わせることもできます。たとえば、出発地のウェイポイントに緯度 / 経度座標を使用し、目的地のウェイポイントにプレイス ID を使用できます。
効率性と正確性を高めるため、緯度 / 経度座標や住所文字列ではなく、プレイス ID を使用します。プレイス ID は一意に明示され、アクセス ポイントや交通変数など、ルート設定に役立つジオコーディングのメリットを提供します。これらは、他の方法でロケーションを指定した場合に発生する可能性のある次の状況を回避するのに役立ちます。
- 緯度 / 経度座標を使用すると、その座標に最も近い道路に位置がスナップされることがあります。その道路は、目的地へのアクセス ポイントではない場合や、目的地に迅速かつ安全に到達できる道路ではない場合があります。
- 住所文字列は、ルートを計算する前に、Routes API によってジオコーディングされ、緯度と経度の座標に変換される必要があります。この変換はパフォーマンスに影響する可能性があります。
プレイス ID として場所を指定する
プレイス ID を使用して、ウェイポイントの場所を指定できます。緯度と経度の座標は道路にスナップされるため、状況によってはプレイス ID の方が適切な結果が得られる場合があります。
Geocoding API と Places API（新版）（Autocomplete（新版）を含む）からプレイス ID を取得します。プレイス ID について詳しくは、プレイス ID の概要をご覧ください。
次の例では、placeId プロパティを使用して、origin と destination の両方のプレイス ID を渡しています。
{ "origin":{ "placeId": "ChIJayOTViHY5okRRoq2kGnGg8o" }, "destination":{ "placeId": "ChIJTYKK2G3X5okRgP7BZvPQ2FU" }, ... }
緯度と経度の座標で位置情報を指定する
ウェイポイントで位置を定義するには、緯度と経度の座標を使用して Location（REST）または Location（gRPC）を指定します。
たとえば、latitude 座標と longitude 座標を使用して、ルート origin と destination のウェイポイントを指定します。
{ "origin":{ "location":{ "latLng":{ "latitude": 37.419734, "longitude": -122.0827784 } } }, "destination":{ "location":{ "latLng":{ "latitude": 37.417670, "longitude": -122.079595 } } }, ... }
場所を住所文字列として指定する
住所文字列は、文字列で表されるリテラル住所です（「1600 Amphitheatre Parkway, Mountain View, CA」など）。ジオコーディングとは、住所文字列を緯度と経度の座標（緯度 37.423021、経度 -122.083739 など）に変換する処理のことです。
ウェイポイントの場所として住所文字列を渡すと、Routes API は内部で文字列をジオコーディングして緯度と経度の座標に変換します。
たとえば、ルートを計算するには、アドレス文字列を使用してルート origin と destination のウェイポイントを指定します。
{ "origin":{ "address": "1600 Amphitheatre Parkway, Mountain View, CA" }, "destination":{ "address": "450 Serra Mall, Stanford, CA 94305, USA" }, ... }
この例では、Routes API が両方の住所をジオコーディングして、緯度と経度の座標に変換します。
アドレス値が曖昧な場合、Routes API は検索を呼び出して、類似したアドレスから曖昧さを解消することがあります。たとえば、「1st Street」は完全な値である場合もあれば、「1st street NE」や「1st St SE」の部分的な値である場合もあります。この結果は、Geocoding API から返される結果とは異なる場合があります。プレイス ID を使用すると、誤った解釈を回避できます。
アドレスのリージョンを設定する
ウェイポイントの場所として不完全な住所文字列を渡すと、API は間違ったジオコーディングされた緯度 / 経度座標を使用する可能性があります。たとえば、出発地として「トレド」、目的地として「マドリード」を指定して、運転ルートをリクエストします。
{ "origin":{ "address": "Toledo" }, "destination":{ "address": "Madrid" }, "travelMode": "DRIVE" }
この例では、「トレド」はスペインではなく、米国のオハイオ州にある都市として解釈されます。したがって、リクエストは空の配列を返します。つまり、ルートは存在しません。
{ [] }
regionCode パラメータを含めることで、特定の地域に結果バイアスをかけて結果を返すように API を構成できます。このパラメータでは、地域コードを ccTLD（「トップレベル ドメイン」）の 2 文字の値として指定します。大半の ccTLD コードは ISO 3166-1 コードと同一ですが、いくつか注意が必要な例外もあります。たとえば、英国の ccTLD は「uk」（.co.uk）ですが、ISO 3166-1 コードは「gb」です（厳密には「グレート ブリテンおよび北アイルランド連合王国」のエンティティ）。
regionCode パラメータを含む「Toledo」から「Madrid」へのルート リクエストでは、「Toledo」がスペインの都市として解釈されるため、適切な結果が返されます。
{ "origin":{ "address": "Toledo" }, "destination":{ "address": "Madrid" }, "travelMode": "DRIVE", "regionCode": "es" }
レスポンスには、スペインのトレドからスペインのマドリードまでのルートが含まれるようになりました。
{ "routes": [ { "distanceMeters": 75330, "duration": "4137s", ... } ] }
ナビゲーション ポイント トークンとして場所を指定する
ナビゲーション ポイント トークンは、位置情報と追加のルート コンテキストをエンコードする文字列です。ナビゲーション ポイント トークンを使用すると、入口、搬入口、指定された乗車エリア付近の特定のアクセス ポイントへの正確なルートを提供できます。これは、乗車場所や降車場所が曖昧な場合があるフード デリバリーやライドシェアなどのユースケースで役立ちます。
ナビゲーション ポイント トークンを取得するには、Geocoding API の Destinations メソッドを呼び出します。
ナビゲーション ポイント トークンを指定するには:
- Geocoding API の
SearchDestinationsメソッドからnavigationPointTokenを取得します。詳しくは、Geocoding API のドキュメントをご覧ください。 navigationPointTokenを渡してウェイポイントを作成します。
次の例では、navigation_point_token プロパティを使用して、origin と destination の両方にナビゲーション ポイント トークンを渡しています。
{ "origin":{ "navigation_point_token": "ENCODED_NAVIGATION_POINT_TOKEN_FOR_ORIGIN" }, "destination":{ "navigation_point_token": "ENCODED_NAVIGATION_POINT_TOKEN_FOR_DESTINATION" }, ... }
Plus Code として場所を指定する
多くの人は正確な住所を持っていないため、配達物を受け取るのが困難な場合があります。また、住所がある場合でも、裏口や搬入口など、より具体的な場所での配達を希望する人もいます。
Plus Code は、実際の番地がない人や場所の住所のようなものです。Plus Codes は、番地や番号を含む住所ではなく、緯度と経度の座標に基づいており、数字と文字で表示されます。
Google は、あらゆる人や場所が住所のメリットを享受できるように、Plus Codes を開発しました。Plus Code は、緯度 / 経度の座標から取得される、エンコードされた場所の参照情報です。8000 分の 1 x 8000 分の 1（14 メートル x 14 メートル）以下の領域を表します。Plus Codes は、番地がない場所、建物に番号が付いていない場所、通りに名前がない場所で、番地の代わりに使用できます。
Plus Code は、グローバル コードまたは複合コードの形式にする必要があります。
- グローバル コードは、4 文字の市外局番と 6 文字以上のローカルコードで構成されます。
たとえば、「1600 Amphitheatre Parkway, Mountain View, CA」という住所の場合、グローバル コードは「849V」、ローカルコードは「CWC8+R9」です。次に、10 文字の Plus Code 全体を使用して、位置情報の値を「849VCWC8+R9」として指定します。
- 複合コードは、6 文字以上のローカルコードと明示的な場所を組み合わせたものです。
たとえば、「450 Serra Mall, Stanford, CA 94305, USA」という住所のローカルコードは「CRHJ+C3」です。複合住所の場合は、ローカルコードと住所の市区町村、都道府県、郵便番号、国を組み合わせて、「CRHJ+C3 Stanford, CA 94305, USA」のように指定します。
たとえば、Plus Code を使用してルート
originとdestinationのウェイポイントを指定してルートを計算します。{ "origin":{ "address": "849VCWC8+R9" }, "destination":{ "address": "CRHJ+C3 Stanford, CA 94305, USA" }, "travelMode": "DRIVE" }
Plus Code は、Autocomplete（新版）、Place Details（新版）、Geocoding API などの Google Maps Platform API でサポートされています。たとえば、Geocoding API を使用して、緯度と経度の座標で指定された場所をリバース ジオコーディングし、その場所の Plus Code を特定できます。