ルートの場所を指定する

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

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

ルートの場所を指定する

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

リクエスト内のすべてのウェイポイントの位置を同じ方法で指定することも、組み合わせて指定することもできます。たとえば、出発地のウェイポイントには緯度と経度の座標を使用し、目的地のウェイポイントにはプレイス 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」、目的地として「Madrid」を指定して、ドライブ ルートのリクエストを送信します。

{
  "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 パラメータを含む「トレド」から「マドリード」へのルート検索リクエストでは、「トレド」がスペインの都市として解釈されるため、適切な結果が返されます。

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

レスポンスには、スペインのトレドからスペインのマドリッドに計算されたルートが含まれます。

{
  "routes": [
    {
      "distanceMeters": 75330,
      "duration": "4137s",
      ...
    }
  ]
}

場所を Plus Code として指定する

多くの人が正確な住所がないために、配達物の受け取りが困難な場合があります。一方、住所がある人は裏口や発送センターなど、より特定の場所で配達物を受け取りたい場合があります。

Plus Codes は、実際の住所がない人物や場所の番地のようなものです。plus code は、緯度と経度の座標に基づいており、番地や住所の代わりに数字と文字で表示されます。

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 文字のプラスコード全体を使用して、位置情報の値を「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 を特定できます。