ルートの場所を指定する

欧州経済領域（EEA）のデベロッパー

ルートを計算するには、ルートの出発地と目的地のロケーションを少なくとも指定する必要があります。これらのロケーションは、ルート上の経由地として定義します。

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

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

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

プレイス ID（推奨）
緯度と経度の座標
住所文字列（「シカゴ、イリノイ」、「ダーウィン、NT、オーストラリア」）
ナビゲーションポイントトークン
Plus Code

リクエスト内のすべての経由地のロケーションを同じ方法で指定することも、組み合わせて指定することもできます。たとえば、出発地の経由地には緯度と経度の座標を使用し、目的地の経由地にはプレイス ID を使用できます。

効率と精度を高めるには、緯度と経度の座標や住所文字列ではなく、プレイス ID を使用します。プレイス ID は一意に明示的であり、アクセスポイントや交通状況変数など、ルート設定にジオコーディングのメリットをもたらします。プレイス ID を使用すると、ロケーションの指定方法によっては発生する可能性がある次の状況を回避できます。

緯度と経度の座標を使用すると、ロケーションがその座標に最も近い道路にスナップされることがあります。これは、物件へのアクセスポイントではない場合や、目的地に迅速かつ安全に到達できる道路ではない場合があります。
住所文字列は、ルートを計算する前に、Routes API でジオコーディングして緯度と経度の座標に変換する必要があります。この変換はパフォーマンスに影響する可能性があります。

ロケーションをプレイス ID として指定する

プレイス ID を使用して、経由地のロケーションを指定できます。緯度と経度の座標は道路にスナップされるため、状況によってはプレイス ID の方が良い結果が得られる場合があります。

プレイス ID は、Geocoding API と Places API（Place Autocomplete を含む）から取得します。プレイス 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 パラメータを含む「トレド」から「マドリード」へのルートリクエストは、「トレド」がスペインの都市として解釈されるため、適切な結果を返します。

{
  "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 を渡して Waypoint を作成します。

次の例では、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 Codes は、実際の住所がない人や場所の番地のようなものです。Plus Codes は、番地と番地ではなく、緯度と経度の座標に基づいており、数字と文字で表示されます。

Google は、すべての人や物に住所のメリットを提供するために Plus Codes を開発しました。Plus Code はエンコードされた場所の参照情報です。緯度 / 経度の座標から取得され、8000 分の 1 x 8000 分の 1（14 メートル x 14 メートル）以下の領域を表します。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 を特定できます。