ルートの場所を指定する

ルートを計算するには、少なくともルートの出発地と目的地の場所を指定する必要があります。これらの地点は、ルート上の地点として定義します。

出発地と目的地以外にも、さまざまな種類の地点と、ルートの地点の処理方法を指定できます。詳細と例については、次のトピックをご覧ください。

ルートのロケーションを指定する

場所を表すには、ウェイポイント（REST）オブジェクトまたは ウェイポイント（gRPC）オブジェクトを作成します。地点の定義では、次のいずれかの方法で位置を指定できます。

1 つのリクエストですべてのウェイポイントの場所を同じ方法で指定することも、組み合わせることもできます。たとえば、出発地の地点には緯度と経度の座標を使用し、目的地の地点にはプレイス 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 が間違ったジオコーディングされた緯度と経度の座標を使用する可能性があります。たとえば、運転ルートの出発地として「トレド」、運転ルートの目的地として「マドリッド」を指定したリクエストを作成します。

{
  "origin":{
    "address": "Toledo"
  },
  "destination":{
    "address": "Madrid"
  },
  "travelMode": "DRIVE"
}

この例では、「Toledo」はスペインではなく、米国のオハイオ州の都市として解釈されます。したがって、リクエストは空の配列を返します。つまり、ルートが存在しないことを意味します。

{
  []
}

regionCode パラメータを含めると、特定の地域を優先して結果を返すように API を構成できます。このパラメータは、地域コードを ccTLD（「トップレベル ドメイン」）の 2 文字の値として指定します。ほとんどの 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 度 1/8, 000 度 1/8, 000 度（赤道では約 14 m x 14 m）以下のエリアを表します。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 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 を特定できます。