Trang này được dịch bởi Cloud Translation API.

Yêu cầu nhiều tuyến

Phương thức computeRoutes (REST) và phương thức ComputeRoutes (gRPC) đều trả về tuyến đường được biểu thị bằng một hình nhiều đường trong phản hồi. Các API này trả về 2 loại hình nhiều đường:

Hình nhiều đường cơ bản (mặc định), biểu thị một tuyến đường nhưng không có thông tin giao thông được nhúng trong hình nhiều đường. Các yêu cầu trả về hình nhiều đường cơ bản sẽ được tính phí theo mức giá Tuyến cơ bản. Tìm hiểu thêm về việc thanh toán cho Routes API.
Hình nhiều đường nhận biết giao thông chứa thông tin về tình trạng giao thông dọc theo tuyến đường. Điều kiện giao thông được biểu thị dưới dạng danh mục tốc độ (NORMAL, SLOW, TRAFFIC_JAM) áp dụng trên một khoảng nhất định của hình nhiều đường. Các yêu cầu hình nhiều đường nhận biết lưu lượng sẽ được tính phí theo mức giá Ưu tiên của Tuyến đường. Tìm hiểu thêm về cách thanh toán cho Routes API. Để biết thông tin chi tiết, hãy xem phần Định cấu hình chất lượng hình nhiều đường

Để biết thêm thông tin về hình nhiều đường, hãy xem:

Thông tin khái niệm về hình nhiều đường
Tiện ích bộ mã hoá nhiều đường tương tác cho phép bạn tạo các hình nhiều đường được mã hoá trong một giao diện người dùng hoặc giải mã các hình nhiều đường để hiển thị trên bản đồ. Ví dụ: sử dụng tiện ích này để giải mã một hình nhiều đường do mã bên dưới tạo.

Lưu ý: Các ký tự đặc biệt trong hình nhiều đường do API REST trả về là ký tự thoát JSON. Để hiển thị những hình nhiều đường này trong Tiện ích bộ mã hoá Polyline tương tác, trước tiên, bạn phải huỷ thoát chúng. Có nhiều tiện ích hiện có để thực hiện thao tác huỷ thoát JSON, chẳng hạn như Freeformatter.

Yêu cầu hình nhiều đường cơ bản cho một tuyến đường, chặng hoặc chặng

Hình nhiều đường được biểu thị bằng đối tượng Polyline (REST) hoặc Polyline (gRPC). Bạn có thể trả về một hình nhiều đường trong phản hồi ở cấp độ tuyến đường, chân và bậc thang.

Chỉ định hình nhiều đường cần trả về bằng cách sử dụng mặt nạ trường phản hồi:

Ở cấp tuyến đường, hãy trả về một hình nhiều đường trong phản hồi bằng cách đưa routes.polyline vào mặt nạ trường phản hồi.
Ở cấp chân, hãy trả về một hình nhiều đường trong phản hồi cho mỗi chặng của tuyến đường bằng cách thêm routes.legs.polyline.

Lưu ý: Mỗi chặng tương ứng với chuyến đi giữa hai điểm tham chiếu khi via sai để điểm tham chiếu biểu thị một điểm dừng trên tuyến đường. Ví dụ: một tuyến đường không có điểm tham chiếu trung gian chỉ có một chặng. Một tuyến đường bao gồm một điểm tham chiếu trung gian có một điểm dừng có hai chân. Một tuyến bao gồm một điểm tham chiếu trung gian có via được đặt thành true sẽ có một chân.
Ở cấp bước, hãy trả về một hình nhiều đường trong phản hồi cho mỗi bước của chân bằng cách thêm routes.legs.steps.polyline.

Ví dụ: để trả về một hình nhiều đường cho toàn bộ tuyến đường, mỗi chặng và mỗi bước của mỗi chặng:

curl -X POST -d '{
  "origin":{
    "address": "1600 Amphitheatre Parkway, Mountain View, CA"
  },
  "destination":{
    "address": "24 Willie Mays Plaza, San Francisco, CA 94107"
  },
  "travelMode": "DRIVE"
}' \
-H 'Content-Type: application/json' \
-H 'X-Goog-Api-Key: YOUR_API_KEY' \
-H 'X-Goog-FieldMask: routes.duration,routes.distanceMeters,routes.polyline,routes.legs.polyline,routes.legs.steps.polyline' \
'https://routes.googleapis.com/directions/v2:computeRoutes'

Yêu cầu này trả về phản hồi sau đây, bao gồm hình nhiều đường cho tuyến đường, cho mỗi chặng của tuyến đường và cho mỗi bước của chặng đó:

{
  "routes": [
    {
      "legs": [
        {
          "polyline": {
              "encodedPolyline": "ipkcFfich...@Bs@?A?O?SD{A@o@B}@I?qA?_AA_@@_@?"
          }
        },
          "steps": [
              {
                  "polyline": {
                      "encodedPolyline": "kclcF...@sC@YIOKI"
                  }
              },
              {
                  "polyline": {
                      "encodedPolyline": "wblcF~...SZSF_@?"
                  }
              },
              ...
      ],
      "distanceMeters": 56901,
      "duration": "2420s",
      "polyline": {
        "encodedPolyline": "ipkcFfich...@Bs@?A?O?SD{A@o@B}@I?qA?_AA_@@_@?"
      }
    }
  ]
}

Vì yêu cầu này chỉ chứa một điểm gốc và một đích đến, nên tuyến được trả về chỉ chứa một chặng. Do đó, hình nhiều đường cho chặng đi và tuyến đường đều giống nhau.

Nếu bạn thêm một điểm tham chiếu trung gian vào yêu cầu, thì tuyến được trả về sẽ chứa 2 chân:

curl -X POST -d '{
  "origin":{
    "address": "1600 Amphitheatre Parkway, Mountain View, CA"
  },
  "destination":{
    "address": "24 Willie Mays Plaza, San Francisco, CA 94107"
  },
  "intermediates": [
    { "address": "450 Serra Mall, Stanford, CA 94305, USA"},
  ],
  "travelMode": "DRIVE",
}' \
-H 'Content-Type: application/json' \
-H 'X-Goog-Api-Key: YOUR_API_KEY' \
-H 'X-Goog-FieldMask: routes.duration,routes.distanceMeters,routes.polyline,routes.legs.polyline' \
'https://routes.googleapis.com/directions/v2:computeRoutes'

Yêu cầu này trả về hai chân, mỗi chân có một hình nhiều đường duy nhất và một hình nhiều đường cho toàn bộ tuyến đường:

{
  "routes": [
    {
      "legs": [
        {
          "polyline": {
            "encodedPolyline": "kclcFfqchV?A...?I@G?GAECCCEKICBAFG"
          }
          "steps": [
            {
                "polyline": {
                    "encodedPolyline": "kclcFfqch...YIOKI"
                }
            },
        ...
        },
        {
          "polyline": {
            "encodedPolyline": "ojmcFtethV?K...QOYQOGA?_@MUG[Ga@G"
          }
          "steps": [
            {
                "polyline": {
                    "encodedPolyline": "uypeFbo`jVgJq...PoBiC"
                }
            },
        ...
        }
      ],
      "distanceMeters": 68403,
      "duration": "3759s",
      "polyline": {
          "encodedPolyline": "kclcFfqchV?A?CBKF[Ha...?GAECCCEKICBAFGJEBE"
      }
    }
  ]
}

Chất lượng hình nhiều đường

Chất lượng của hình nhiều đường có thể được mô tả theo các thuật ngữ sau:

Độ chính xác của dấu phẩy động của các điểm

Điểm được chỉ định dưới dạng giá trị vĩ độ và kinh độ, được biểu thị bằng định dạng dấu phẩy động với độ chính xác đơn. Điều này phù hợp với các giá trị nhỏ (có thể được biểu thị chính xác), nhưng độ chính xác giảm khi giá trị tăng do lỗi làm tròn dấu phẩy động.

Trong phương thức computeRoutes (REST) và ComputeRoutes, việc này do polylineEncoding kiểm soát.
Số điểm tạo nên hình nhiều đường

Càng có nhiều điểm thì hình nhiều đường càng mượt mà (đặc biệt là ở đường cong).

Trong phương thức computeRoutes (REST) và ComputeRoutes, việc này do polylineQuality kiểm soát.

Định cấu hình loại mã hoá hình nhiều đường

Sử dụng tuỳ chọn yêu cầu polylineEncoding để kiểm soát loại hình nhiều đường. Thuộc tính polylineEncoding kiểm soát việc hình nhiều đường có được mã hoá thành ENCODED_POLYLINE (mặc định) hay không, nghĩa là Định dạng thuật toán Polyline được mã hoá sẽ được sử dụng hoặc GEO_JSON_LINESTRING, nghĩa là định dạng Chuỗi đường GeoJSON sẽ được sử dụng.

Ví dụ: trong phần nội dung yêu cầu:

curl -X POST -d '{
  "origin":{
    "address": "1600 Amphitheatre Parkway, Mountain View, CA"
  },
  "destination":{
    "address": "24 Willie Mays Plaza, San Francisco, CA 94107"
  },
  "travelMode": "DRIVE",
  "polylineEncoding": "ENCODED_POLYLINE"
}' \
-H 'Content-Type: application/json' \
-H 'X-Goog-Api-Key: YOUR_API_KEY' \
-H 'X-Goog-FieldMask: routes.duration,routes.distanceMeters,routes.polyline,routes.legs.polyline' \
'https://routes.googleapis.com/directions/v2:computeRoutes'

Định cấu hình chất lượng Polyline

polylineQuality chỉ định chất lượng của hình nhiều đường là HIGH_QUALITY hoặc OVERVIEW (mặc định). Với OVERVIEW, hình nhiều đường được tạo bằng một số ít điểm và có độ trễ yêu cầu thấp hơn HIGH_QUALITY.

Ví dụ: trong phần nội dung yêu cầu:

{
  "origin":{
    "location":{
      "latLng":{
        "latitude": 37.419734,
        "longitude": -122.0827784
      }
    }
  },
  "destination":{
    "location":{
      "latLng":{
        "latitude": 37.417670,
        "longitude": -122.079595
      }
    }
  },
  "travelMode": "DRIVE",
  "routingPreference": "TRAFFIC_AWARE",
  "polylineQuality": "HIGH_QUALITY",
  "polylineEncoding": "ENCODED_POLYLINE",
  "departureTime": "2023-10-15T15:01:23.045123456Z",
  ...
}

Yêu cầu hình nhiều đường nhận biết lưu lượng truy cập

Các ví dụ nêu trên đều trả về các hình nhiều đường cơ bản, nghĩa là các hình nhiều đường không có thông tin về lưu lượng truy cập. Ngoài ra, bạn cũng có thể yêu cầu hình nhiều đường chứa thông tin giao thông cho tuyến đường và mỗi chặng của tuyến đường.

Các hình nhiều đường nhận biết giao thông chứa thông tin về tình trạng giao thông dọc theo tuyến đường. Tình trạng giao thông được biểu thị dưới dạng danh mục tốc độ (NORMAL, SLOW, TRAFFIC_JAM) cho một khoảng thời gian nhất định của hình nhiều đường phản hồi. Các khoảng thời gian này được xác định bằng chỉ mục của điểm nhiều đường bắt đầu (bao gồm) và kết thúc (loại trừ).

Ví dụ: phản hồi sau đây cho thấy lưu lượng truy cập NORMAL giữa các điểm nhiều đường 2 và 4:

{
  "startPolylinePointIndex": 2,
  "endPolylinePointIndex": 4,
  "speed": "NORMAL"
}

Để yêu cầu tính toán hình nhiều đường nhận biết lưu lượng truy cập, hãy đặt các thuộc tính sau trong yêu cầu:

Đặt trường mảng extraComputations thành TRAFFIC_ON_POLYLINE để cho phép tính toán lưu lượng truy cập.
Đặt travelMode thành DRIVE hoặc TWO_WHEELER. Các yêu cầu cho mọi phương thức đi lại khác sẽ trả về lỗi.
Chỉ định lựa chọn ưu tiên định tuyến TRAFFIC_AWARE hoặc TRAFFIC_AWARE_OPTIMAL trong yêu cầu. Để biết thêm thông tin, hãy xem bài viết Định cấu hình chất lượng và độ trễ.
Đặt mặt nạ trường phản hồi chỉ định trả về các thuộc tính phản hồi:
- Ở cấp tuyến đường, hãy trả về tất cả thông tin về hành trình trong phản hồi bằng cách đưa routes.travelAdvisory vào mặt nạ trường phản hồi. Để chỉ trả về thông tin giao thông, hãy chỉ định routes.travelAdvisory.speedReadingIntervals
- Ở cấp chân, hãy trả về tất cả thông tin đi lại trong phản hồi cho từng chặng của tuyến đường bằng cách thêm routes.legs.travelAdvisory. Để chỉ trả về thông tin lưu lượng truy cập, hãy chỉ định routes.legs.travelAdvisory.speedReadingIntervals.

curl -X POST -d '{
  "origin":{
    "address": "1600 Amphitheatre Parkway, Mountain View, CA"
  },
  "destination":{
    "address": "24 Willie Mays Plaza, San Francisco, CA 94107"
  },
  "travelMode": "DRIVE",
  "extraComputations": ["TRAFFIC_ON_POLYLINE"],
  "routingPreference": "TRAFFIC_AWARE_OPTIMAL"
}' \
-H 'Content-Type: application/json' \
-H 'X-Goog-Api-Key: YOUR_API_KEY' \
-H 'X-Goog-FieldMask: routes.duration,routes.distanceMeters,routes.polyline,routes.legs.polyline,routes.travelAdvisory,routes.legs.travelAdvisory' \
'https://routes.googleapis.com/directions/v2:computeRoutes'

Phản hồi mẫu cho hình nhiều đường nhận biết lưu lượng truy cập

Trong phản hồi, dữ liệu lưu lượng truy cập được mã hoá trong hình nhiều đường và nằm trong trường travelAdvisory, thuộc loại đối tượng RouteLegTravelAdvisory (mỗi chặng) và đối tượng RouteTravelAdvisory (tuyến đường).

Ví dụ:

{
  "routes": [
    {
      "legs": {
        "polyline": {
          "encodedPolyline": "}boeF~zbjVAg@EmB`GWHlD"
        },
        // Traffic data for the leg.
        "travelAdvisory": {
          "speedReadingIntervals": [
            {
              "endPolylinePointIndex": 1,
              "speed": "NORMAL"
            },
            {
              "startPolylinePointIndex": 1,
              "endPolylinePointIndex": 2,
              "speed": "SLOW"
            },
            {
              "startPolylinePointIndex": 2,
              "endPolylinePointIndex": 4,
              "speed": "NORMAL"
            }
          ] 
        }
      },
      "polyline": {
        "encodedPolyline": "}boeF~zbjVAg@EmB`GWHlD"
      },
      // Traffic data for the route.
      "travelAdvisory": {
        "speedReadingIntervals": [
          {
            "endPolylinePointIndex": 1,
            "speed": "NORMAL"
          },
          {
            "startPolylinePointIndex": 1,
            "endPolylinePointIndex": 2,
            "speed": "SLOW"
          },
          {
            "startPolylinePointIndex": 2,
            "endPolylinePointIndex": 4,
            "speed": "NORMAL"
          }
        ] 
      }
    }
  ]
}

Cả RouteTravelAdvisory và RouteLegTravelAdvisory đều có một trường mảng có tên là speedReadingIntervals. Trường này chứa thông tin về tốc độ lưu lượng truy cập. Mỗi đối tượng trong mảng được biểu thị bằng một đối tượng SpeedReadingInterval (REST) hoặc SpeedReadingInterval (gRPC).

Đối tượng SpeedReadingInterval bao gồm đọc tốc độ cho một khoảng thời gian tuyến đường, chẳng hạn như NORMAL, SLOW hoặc TRAFFIC_JAM. Toàn bộ mảng đối tượng bao phủ toàn bộ hình nhiều đường mà không chồng chéo. Điểm bắt đầu của khoảng thời gian được chỉ định giống với điểm kết thúc của khoảng thời gian trước đó.

Mỗi khoảng thời gian được mô tả bằng startPolylinePointIndex, endPolylinePointIndex và danh mục tốc độ tương ứng. Xin lưu ý rằng việc thiếu chỉ mục bắt đầu trong khoảng thời gian tương ứng với chỉ mục 0 theo các phương pháp proto3.

Các giá trị startPolylinePointIndex và endPolylinePointIndex không phải lúc nào cũng liên tiếp. Ví dụ:

{
  "startPolylinePointIndex": 2,
  "endPolylinePointIndex": 4,
  "speed": "NORMAL"
}

Trong trường hợp này, điều kiện giao thông là như nhau từ chỉ mục 2 đến chỉ mục 4.

Kết xuất hình nhiều đường nhận biết lưu lượng truy cập bằng SDK Maps

Bạn nên hiển thị các hình nhiều đường có thể nhận biết giao thông trên bản đồ bằng cách sử dụng nhiều tính năng do SDK Google Maps cung cấp, bao gồm màu sắc, nét vẽ và hoa văn tuỳ chỉnh dọc theo các đường kéo dài. Để biết thêm thông tin về cách sử dụng hình nhiều đường, hãy xem bài viết Các tính năng hình nhiều đường dành cho Android và Các tính năng hình nhiều đường dành cho iOS.

Ví dụ về kết xuất hình nhiều đường

Người dùng SDK Maps có cơ hội xác định logic lập bản đồ tuỳ chỉnh giữa các danh mục tốc độ và giản đồ kết xuất nhiều đường. Ví dụ: người dùng có thể quyết định hiển thị tốc độ "Bình thường" dưới dạng đường dày màu xanh dương trên bản đồ, trong khi tốc độ "SLOW" có thể hiển thị dưới dạng đường màu cam dày.

Các đoạn mã sau đây sẽ thêm một hình nhiều đường màu xanh dương đậm với các đoạn trắc địa từ Melbourne đến Perth. Để biết thêm thông tin, hãy xem phần Tuỳ chỉnh giao diện (dành cho Android) và Tuỳ chỉnh Polyline (dành cho iOS).

Android

Java

Polyline line = map.addPolyline(new PolylineOptions()
    .add(new LatLng(-37.81319, 144.96298), new LatLng(-31.95285, 115.85734))
    .width(25)
    .color(Color.BLUE)
    .geodesic(true));

Kotlin

val line: Polyline = map.addPolyline(
  PolylineOptions()
    .add(LatLng(-37.81319, 144.96298), LatLng(-31.95285, 115.85734))
    .width(25f)
    .color(Color.BLUE)
    .geodesic(true)
)

iOS

Objective-C

GMSMutablePath *path = [GMSMutablePath path];
[path addLatitude:-37.81319 longitude:144.96298];
[path addLatitude:-31.95285 longitude:115.85734];
GMSPolyline *polyline = [GMSPolyline polylineWithPath:path];
polyline.strokeWidth = 10.f;
polyline.strokeColor = .blue;
polyline.geodesic = YES;
polyline.map = mapView;

Swift

let path = GMSMutablePath()
path.addLatitude(-37.81319, longitude: 144.96298)
path.addLatitude(-31.95285, longitude: 115.85734)
let polyline = GMSPolyline(path: path)
polyline.strokeWidth = 10.0
polyline.geodesic = true
polyline.map = mapView