ルートを計算するには、少なくともルートの出発地とルートの目的地の場所を指定する必要があります。これらの位置は、ルート上の地点として定義します。
出発地と目的地だけでなく、さまざまな種類のウェイポイントと、ルートのウェイポイントの処理方法を指定できます。詳細と例については、次のトピックをご覧ください。
ルートのロケーションを指定する
ロケーションを表すには、ウェイポイント(REST)オブジェクトまたは ウェイポイント(gRPC)オブジェクトを作成します。地点の定義では、次のいずれかの方法で場所を指定できます。
- 場所 ID(推奨)
- 緯度と経度の座標
- Address string(「シカゴ、イリノイ州」、「ダーウィン、NT、オーストラリア」)
- Plus Code
リクエスト内のすべての地点を同じ方法で指定することも、複数の地点を混在させることもできます。たとえば、出発地の地点に緯度と経度の座標を使用し、目的地の地点にプレイス ID を使用できます。
効率性と正確性を高めるため、緯度と経度の座標や住所文字列の代わりにプレイス ID を使用します。プレイス ID は一意に明示されており、アクセス ポイントや交通変数など、ジオコーディングのメリットが得られます。これにより、他の方法によるロケーション指定によって次のような状況を回避できます。
- 緯度と経度の座標を使用すると、その座標に最も近い道路に位置がスナップされることがあります。このような場所は、宿泊施設へのアクセス ポイントや、目的地にすばやく安全に通じる道路ではない場合があります。
- 住所文字列は、ルートを計算する前に、まず Routes API でジオコーディングして緯度と経度の座標に変換する必要があります。このコンバージョンはパフォーマンスに影響する可能性があります。
場所をプレイス ID として指定する
プレイス ID を使って地点の位置を指定できます。緯度と経度の座標は道路に合わせて設定されるため、状況によってはプレイス ID のほうが適切な結果が得られることがあります。
Geocoding API と Places API(Place 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 で間違ったジオコーディングされた緯度と経度の座標が使用されることがあります。たとえば、運転ルートの出発地として「Toledo」、目的地として「マドリッド」を指定してリクエストを行うとします。
{ "origin":{ "address": "Toledo" }, "destination":{ "address": "Madrid" }, "travelMode": "DRIVE" }
この例では、「トレド」はスペインではなく米国のオハイオ州の都市と解釈されます。したがって、リクエストは空の配列を返します。つまり、ルートは存在しません。
{ [] }
regionCode
パラメータを含めると、特定の地域を優先した結果を返すように API を構成できます。このパラメータでは、リージョン コードを 2 文字の ccTLD(「トップレベル ドメイン」)値として指定します。ほとんどの ccTLD コードは ISO 3166-1 コードと同一ですが、いくつか注意が必要な例外もあります。たとえば、英国の ccTLD は「uk」(.co.uk)ですが、ISO 3166-1 コードは「gb」(厳密には「グレート ブリテンおよび北アイルランド連合王国」のエンティティ)です。
「トレド」から「マドリード」へのルート リクエストに regionCode
パラメータを指定すると、「トレド」はスペインの都市として解釈されるため、適切な結果が返されます。
{ "origin":{ "address": "Toledo" }, "destination":{ "address": "Madrid" }, "travelMode": "DRIVE", "regionCode": "es" }
レスポンスには、スペインのトレドからスペインのマドリッドまで計算されたルートが含まれています。
{ "routes": [ { "distanceMeters": 75330, "duration": "4137s", ... } ] }
Plus Code で場所を指定する
正確な住所がわからず、荷物を受け取るのが難しい人も多いでしょう。または、住所があるユーザーが、裏口や荷物置き場など、より具体的な場所での配送を希望する場合もあります。
Plus Codes は、実際の住所を持たない人や場所の番地のようなものです。Plus Codes は、番地と番地を含む住所ではなく、緯度と経度の座標に基づいており、数字と文字で表示されます。
Google は、すべての人に住所のメリットを提供するために Plus Codes を開発しました。Plus Code はエンコードされた位置参照で、緯度と経度の座標から導出され、1/8, 000 度から 1/8, 000 度(赤道で約 14 m x 14 m)以下の地域を表します。Plus Codes は、番地が存在しない場所、建物に番号が付いていない場所、通りに名前が付いていない場所において、番地の代わりに使用できます。
Plus Codes は、グローバル コードまたは複合コードとしてフォーマットする必要があります。
- グローバル コードは、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 Codes を使用してルート
origin
とdestination
の地点を指定してルートを計算します。{ "origin":{ "address": "849VCWC8+R9" }, "destination":{ "address": "CRHJ+C3 Stanford, CA 94305, USA" }, "travelMode": "DRIVE" }
Plus Codes は、Place Autocomplete、Place Details、Directions API、Geocoding API などの Google Maps Platform API でサポートされています。たとえば、Geocoding API を使用すると、緯度と経度の座標で指定された場所をリバース ジオコーディングして、その場所の Plus Code を特定できます。