指定路線位置

歐洲經濟區 (EEA) 開發人員

如要計算路線，至少必須指定路線起點和路線目的地。您可以在路線上將這些地點定義為中途點。

除了起點和目的地，您還可以指定不同類型的中途點，以及如何處理路線的中途點。如需更多資訊和範例，請參閱下列主題：

指定路線的地點

如要表示位置，請建立 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"
  },
  ...
}

以經緯度座標指定位置

如要在路線控點中定義位置，請使用緯度/經度座標指定「位置 (REST)」或「位置(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"
}

在本例中，「Toledo」會解讀為美國俄亥俄州的城市，而非西班牙的城市。因此，要求會傳回空陣列，表示沒有任何路徑：

{
  []
}

您可以加入 regionCode 參數，設定 API 優先傳回特定區域的結果。這個參數會指定區碼，採 ccTLD (「頂層網域」) 的兩位字元值。大多數 ccTLD 代碼與 ISO 3166-1 代碼相同，但有一些需要注意的例外情況。舉例來說，英國的 ccTLD 是「uk」(即 .co.uk)，而 ISO 3166-1 代碼是「gb」(技術上是指「大不列顛及北愛爾蘭聯合王國」實體)。

如果從「Toledo」到「Madrid」的路線要求包含 regionCode 參數，系統會將「Toledo」解讀為西班牙的城市，並傳回適當結果：

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

回應現在包含從西班牙托雷多到西班牙馬德里計算出的路線：

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

以 Plus Code 指定位置

許多人沒有精確的地址，因此可能難以收到郵件。或者，有地址的使用者可能偏好在更明確的地點收件，例如後門或裝卸貨碼頭。

Plus Code 就像是街道地址，適用於沒有實際地址的人或地點。Plus Code 是以經緯度座標為依據，並以數字和字母顯示，而非街道名稱和號碼。

Google 開發了 Plus Codes，讓所有人都能享有地址的便利性。Plus Code 是經過編碼的位置參照，衍生自經緯度座標，表示面積不超過 1/8000 度 x 1/8000 度 (在赤道區約 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」。

    舉例來說，您可以指定路線的路線控點 origin 和 destination，並使用 Plus Code 計算路線：

    {
  "origin":{
    "address": "849VCWC8+R9"
  },
  "destination":{
    "address": "CRHJ+C3 Stanford, CA 94305, USA"
  },
  "travelMode": "DRIVE"
}

Google 地圖平台 API 支援 Plus Code，包括 Place Autocomplete、Place Details、Directions API (舊版) 和 Geocoding API。 舉例來說，您可以使用 Geocoding API，對經緯度座標指定的某個位置進行反向地理編碼，判斷該位置的 Plus Code。