Chỉ định vị trí cho tuyến đường

Nhà phát triển ở Khu vực kinh tế Châu Âu (EEA)

Để tính toán một tuyến đường, bạn phải chỉ định ít nhất vị trí của điểm xuất phát và điểm đến của tuyến đường. Bạn xác định các vị trí này là điểm tham chiếu trên tuyến đường.

Ngoài điểm xuất phát và điểm đến, bạn có thể chỉ định nhiều loại điểm tham chiếu và cách xử lý điểm tham chiếu cho một tuyến đường. Để biết thêm thông tin và ví dụ, hãy xem các chủ đề sau:

Chỉ định vị trí cho một tuyến đường

Bạn biểu thị một vị trí bằng cách tạo đối tượng Waypoint (REST) hoặc Waypoint (gRPC). Trong định nghĩa điểm tham chiếu, bạn có thể chỉ định một vị trí theo bất kỳ cách nào sau đây:

Bạn có thể chỉ định vị trí cho tất cả điểm tham chiếu trong một yêu cầu theo cùng một cách hoặc kết hợp các cách. Ví dụ: bạn có thể sử dụng toạ độ vĩ độ/kinh độ cho điểm tham chiếu xuất phát và sử dụng mã địa điểm cho điểm tham chiếu đích.

Để đảm bảo hiệu quả và độ chính xác, hãy sử dụng mã địa điểm thay vì toạ độ vĩ độ/kinh độ hoặc chuỗi địa chỉ. Mã địa điểm là giá trị nhận dạng duy nhất và cung cấp các lợi ích của việc mã hoá địa lý cho việc định tuyến, chẳng hạn như điểm truy cập và biến lưu lượng truy cập. Các giá trị này giúp tránh những tình huống sau đây có thể xảy ra khi bạn chỉ định vị trí theo cách khác:

  • Việc sử dụng toạ độ vĩ độ/kinh độ có thể khiến vị trí được ghim vào đường gần nhất với toạ độ đó. Tuy nhiên, đường đó có thể không phải là điểm vào cơ sở lưu trú hoặc thậm chí không phải là đường dẫn đến điểm đến một cách nhanh chóng hoặc an toàn.
  • Trước tiên, chuỗi địa chỉ phải được Routes API mã hoá địa lý để chuyển đổi thành toạ độ vĩ độ/kinh độ trước khi có thể tính toán tuyến đường. Lượt chuyển đổi này có thể ảnh hưởng đến hiệu suất.

Chỉ định một vị trí làm Mã địa điểm

Bạn có thể sử dụng mã địa điểm để chỉ định vị trí của một điểm tham chiếu. Vì toạ độ vĩ độ và kinh độ được ghim vào đường, nên bạn có thể thấy mã địa điểm mang lại kết quả chính xác hơn trong một số trường hợp.

Truy xuất mã địa điểm từ Geocoding API và Places API (Mới) (bao gồm cả tính năng Tự động hoàn thành (Mới)). Để biết thêm thông tin về mã địa điểm, hãy xem bài viết Tổng quan về mã địa điểm.

Ví dụ sau đây sử dụng thuộc tính placeId để truyền mã địa điểm cho cả origin và destination:

{
  "origin":{
    "placeId": "ChIJayOTViHY5okRRoq2kGnGg8o"
  },
  "destination":{
    "placeId": "ChIJTYKK2G3X5okRgP7BZvPQ2FU"
  },
  ...
}

Chỉ định một vị trí dưới dạng toạ độ vĩ độ và kinh độ

Để xác định vị trí trong một điểm tham chiếu, hãy chỉ định Vị trí (REST) hoặc Vị trí (gRPC) bằng cách sử dụng toạ độ vĩ độ/kinh độ.

Ví dụ: chỉ định một điểm tham chiếu cho tuyến đường origin và destination bằng cách sử dụng toạ độ latitude và longitude:

{
  "origin":{
    "location":{
      "latLng":{
        "latitude": 37.419734,
        "longitude": -122.0827784
      }
    }
  },
  "destination":{
    "location":{
      "latLng":{
        "latitude": 37.417670,
        "longitude": -122.079595
      }
    }
  },
...
}

Chỉ định một vị trí dưới dạng chuỗi địa chỉ

Chuỗi địa chỉ là địa chỉ cố định được biểu thị bằng một chuỗi (chẳng hạn như "1600 Amphitheatre Parkway, Mountain View, CA"). Mã hoá địa lý là quá trình chuyển đổi một chuỗi địa chỉ thành toạ độ vĩ độ và kinh độ (chẳng hạn như vĩ độ 37,423021 và kinh độ -122,083739).

Khi bạn truyền một chuỗi địa chỉ làm vị trí của một điểm tham chiếu, Routes API sẽ mã hoá địa lý chuỗi đó trong nội bộ để chuyển đổi thành toạ độ vĩ độ và kinh độ.

Ví dụ: để tính toán một tuyến đường, bạn chỉ định một điểm tham chiếu cho tuyến đường origin và destination bằng cách sử dụng chuỗi địa chỉ:

{
  "origin":{
    "address": "1600 Amphitheatre Parkway, Mountain View, CA"
  },
  "destination":{
    "address": "450 Serra Mall, Stanford, CA 94305, USA"
  },
  ...
}

Trong ví dụ này, Routes API mã hoá địa lý cả hai địa chỉ để chuyển đổi thành toạ độ vĩ độ và kinh độ.

Nếu giá trị địa chỉ không rõ ràng, thì Routes API có thể gọi một lượt tìm kiếm để phân biệt với các địa chỉ tương tự. Ví dụ: "Đường số 1" có thể là giá trị hoàn chỉnh hoặc giá trị một phần cho "Đường số 1 NE" hoặc "Đường số 1 SE". Kết quả này có thể khác với kết quả do Geocoding API trả về. Bạn có thể tránh những hiểu lầm có thể xảy ra bằng cách sử dụng mã địa điểm.

Đặt khu vực cho địa chỉ

Nếu bạn truyền một chuỗi địa chỉ không đầy đủ làm vị trí của một điểm tham chiếu, thì API có thể sử dụng toạ độ vĩ độ/kinh độ được mã hoá địa lý không chính xác. Ví dụ: bạn đưa ra yêu cầu chỉ định "Toledo" làm điểm xuất phát và "Madrid" làm điểm đến cho một tuyến đường lái xe:

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

Trong ví dụ này, "Toledo" được hiểu là một thành phố ở bang Ohio của Hoa Kỳ, chứ không phải ở Tây Ban Nha. Do đó, yêu cầu sẽ trả về một mảng trống, nghĩa là không có tuyến đường nào:

{
  []
}

Bạn có thể định cấu hình API để trả về kết quả thiên về một khu vực cụ thể bằng cách thêm tham số regionCode. Tham số này chỉ định mã khu vực dưới dạng giá trị gồm hai ký tự của ccTLD ("miền cấp cao nhất"). Hầu hết các mã ccTLD đều giống với mã ISO 3166-1, ngoại trừ một số trường hợp ngoại lệ đáng chú ý. Ví dụ: ccTLD của Vương quốc Anh là "uk" (.co.uk) trong khi mã ISO 3166-1 của quốc gia này là "gb" (về mặt kỹ thuật là cho thực thể "Vương quốc Liên hiệp Anh và Bắc Ireland").

Yêu cầu chỉ đường từ "Toledo" đến "Madrid" có chứa tham số regionCode sẽ trả về kết quả phù hợp vì "Toledo" được hiểu là một thành phố ở Tây Ban Nha:

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

Phản hồi hiện chứa tuyến đường được tính từ Toledo, Tây Ban Nha đến Madrid, Tây Ban Nha:

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

Mã thông báo điểm điều hướng là một chuỗi mã hoá một vị trí và bối cảnh tuyến đường bổ sung. Mã thông báo điểm điều hướng có thể cung cấp thông tin chỉ đường chính xác đến các điểm truy cập cụ thể gần lối vào, bến bốc dỡ hàng hoặc khu vực đón khách được chỉ định. Điều này rất hữu ích trong những trường hợp như giao đồ ăn hoặc đi chung xe, khi điểm đón hoặc trả khách có thể không rõ ràng.

Bạn có thể lấy mã thông báo điểm đi theo chỉ dẫn bằng cách gọi phương thức Điểm đến của Geocoding API.

Cách chỉ định mã thông báo điểm điều hướng:

  1. Lấy navigationPointToken từ phương thức SearchDestinations của Geocoding API. Hãy xem tài liệu về Geocoding API để biết thêm thông tin.
  2. Tạo một Điểm tham chiếu bằng cách truyền vào navigationPointToken.

Ví dụ sau đây sử dụng thuộc tính navigation_point_token để truyền mã thông báo điểm điều hướng cho cả origin và destination:

{
  "origin":{
    "navigation_point_token": "ENCODED_NAVIGATION_POINT_TOKEN_FOR_ORIGIN"
  },
  "destination":{
    "navigation_point_token": "ENCODED_NAVIGATION_POINT_TOKEN_FOR_DESTINATION"
  },
  ...
}

Chỉ định một vị trí dưới dạng Plus Code

Nhiều người không có địa chỉ chính xác, khiến họ gặp khó khăn khi nhận hàng giao. Hoặc những người có địa chỉ có thể muốn nhận hàng tại những vị trí cụ thể hơn, chẳng hạn như lối vào phía sau hoặc bến bốc dỡ hàng.

Plus Codes giống như địa chỉ đường phố cho những người hoặc địa điểm không có địa chỉ thực tế. Thay vì địa chỉ có tên đường và số nhà, Plus Codes dựa trên toạ độ vĩ độ/kinh độ và được hiển thị dưới dạng số và chữ cái.

Google đã phát triển Mã cộng để mang lại lợi ích của địa chỉ cho mọi người và mọi thứ. Plus Code là một thông tin tham chiếu vị trí được mã hoá, bắt nguồn từ toạ độ vĩ độ/kinh độ, đại diện cho một khu vực: 1/8000 độ x 1/8000 độ (khoảng 14m x 14m tại đường xích đạo) hoặc nhỏ hơn. Bạn có thể sử dụng Plus Code để thay thế cho địa chỉ đường phố ở những nơi không có địa chỉ đường phố hoặc nơi các toà nhà không được đánh số hoặc đường phố không được đặt tên.

Plus Code phải được định dạng dưới dạng mã toàn cầu hoặc mã kết hợp:

  • Mã toàn cầu bao gồm mã vùng gồm 4 ký tự và mã địa phương gồm 6 ký tự trở lên.

    Ví dụ: đối với địa chỉ "1600 Amphitheatre Parkway, Mountain View, CA", mã toàn cầu là "849V" và mã địa phương là "CWC8+R9". Sau đó, bạn sử dụng toàn bộ Plus Code gồm 10 ký tự để chỉ định giá trị vị trí là "849VCWC8+R9".

  • Mã kết hợp bao gồm một mã địa phương có độ dài từ 6 ký tự trở lên kết hợp với một vị trí rõ ràng.

    Ví dụ: địa chỉ "450 Serra Mall, Stanford, CA 94305, USA" có mã địa phương là "CRHJ+C3". Đối với địa chỉ phức hợp, hãy kết hợp mã cộng với thành phố, tiểu bang, mã ZIP và quốc gia của địa chỉ theo dạng "CRHJ+C3 Stanford, CA 94305, USA".

    Ví dụ: tính toán một tuyến đường bằng cách chỉ định một điểm tham chiếu cho tuyến đường origin và destination bằng Plus Codes:

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

Plus Codes được hỗ trợ trong các API của Google Maps Platform, bao gồm Autocomplete (Mới), Place Details (Mới) và Geocoding API. Ví dụ: bạn có thể sử dụng Geocoding API để mã hoá địa lý ngược một vị trí được chỉ định bằng toạ độ vĩ độ/kinh độ nhằm xác định Plus Code của vị trí đó.