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 đa tuyến trong phản hồi. Các API này trả về hai loại đa tuyến:

  • Đường đa tuyến 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 đường đa tuyến. Yêu cầu trả về hình nhiều đường cơ bản được tính phí theo mức giá cơ bản cho Tuyến đường. Tìm hiểu thêm về 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. Tình trạng giao thông được thể hiện bằng các danh mục tốc độ (NORMAL, SLOW, TRAFFIC_JAM) áp dụng trên một khoảng thời gian nhất định của đường đa tuyến. Yêu cầu hình nhiều đường nhận biết lưu lượng truy cập được lập hoá đơn tại Mức phí ưu tiên cho tuyến đường. Tìm hiểu thêm về cách thanh toán cho Route API. Để biết thông tin chi tiết, hãy xem Định cấu hình chất lượng hình nhiều đường

Để biết thêm về đa tuyến, hãy xem:

Yêu cầu một đường đa giác cơ bản cho một tuyến đường, chặng hoặc bước

Hình nhiều đường được biểu thị bằng Hình nhiều đường (REST) hoặc Đối tượng 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 thêm routes.polyline trong 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 câu trả lời cho mỗi chân của bằng cách bao gồm routes.legs.polyline.

  • Ở cấp bước, 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à cho mỗi bước của mỗi chân:

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, bao gồm hình nhiều đường cho thuộc tính tuyến đường, cho mỗi đoạn của tuyến đường và cho mỗi bước của chặng đường đi:

{
  "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 điểm đến, nên yêu cầu được trả về tuyến đường chỉ chứa một chặng. Do đó, hình nhiều đường cho chặng và cho tuyến đường là giống nhau.

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

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 đường đa tuyến

Chất lượng của một đa tuyến 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

    Các điểm được chỉ định dưới dạng giá trị vĩ độ và kinh độ, được biểu thị ở định dạng dấu phẩy động có độ chính xác đơn. Phương pháp 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 lên do lỗi làm tròn dấu phẩy động.

    Ngang bằng computeRoutes phương thức (REST) và ComputeRoutes tính năng này do polylineEncoding kiểm soát.

  • Số điểm tạo nên đường đa tuyến

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

    Ngang bằng computeRoutes phương thức (REST) và ComputeRoutes tính năng 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), nghĩa là Định dạng thuật toán đa dòng đã mã hoá sẽ được sử dụng, hay GEO_JSON_LINESTRING, có nghĩa là Định dạng GeoJSON LineString 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 tham số đ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ề hình nhiều đường cơ bản, nghĩa là hình nhiều đường không có giao thông. 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ị theo các danh mục tốc độ (NORMAL, SLOW, TRAFFIC_JAM) cho một khoảng thời gian nhất định của đường đa tuyến phản hồi. Các khoảng thời gian này được xác định theo chỉ mục bắt đầu của khoảng thời gian đó (bao gồm cả ngày này) và kết thúc (loại trừ) các điểm hình nhiều đường.

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

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

Để tạo yêu cầu tính toán đường đa tuyến có tính đến 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 để bật tính toán lưu lượng truy cập.

  • Đặt travelMode thành DRIVE hoặc TWO_WHEELER. Yêu cầu về bất kỳ nội dung nào khác phương tiện đi lại trả về lỗi.

  • Chỉ định tuỳ chọ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 so với độ 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 đi lại trong phản hồi bằng cách bao gồm routes.travelAdvisory trong mặt nạ trường phản hồi. Cần trả lại thông tin giao thông, hãy nêu rõ 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 mỗi chặng của tuyến đường bằng cách bao gồm routes.legs.travelAdvisory. Cần trả lại thông tin giao thông, hãy nêu rõ 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á theo hình nhiều đường và nằm trong Trường travelAdvisory, thuộc loại RouteLegTravelAdvisory đối tượng (mỗi chân) 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ả RouteTravelAdvisoryRouteLegTravelAdvisory đều có một trường mảng tên là speedReadingIntervals chứa thông tin về tốc độ giao thông. Một một đối tượng trong mảng được biểu thị bằ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 nhau. Điểm bắt đầu của một thuộc tính được chỉ định khoảng thời gian giống với điểm kết thúc của khoảng 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. Lưu ý rằng thiếu chỉ mục bắt đầu trong khoảng tương ứng với chỉ mục 0 theo các phương pháp proto3.

Các giá trị startPolylinePointIndexendPolylinePointIndex không luôn 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ó khả năng nhận biết giao thông trên bản đồ bằng cách sử dụng các tính năng được SDK của Google Maps cung cấp bao gồm màu sắc tuỳ chỉnh, nét vẽ và các mẫu hình dọc theo đường kéo dài. Để biết thêm thông tin về cách sử dụng hình nhiều đường, xem Các tính năng hình nhiều đường dành cho AndroidCác tính năng của Polyline dành cho iOS.

Ví dụ về kết xuất Polyline

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

Các đoạn mã sau đây thêm một hình nhiều đường màu xanh dương đậm có các đoạn trắc địa từ Melbourne đến Perth. Để biết thêm thông tin, hãy xem Tuỳ chỉnh giao diện (dành cho Android) và Tuỳ chỉnh hình nhiều đường (đối với 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