Hãy tham gia Ngày cộng đồng nhà phát triển Google Maps Platform tiếp theo của chúng tôi tại San Francisco vào tháng 12! Đăng ký ngay để tham dự.

Google sử dụng công nghệ AI để dịch nội dung sang ngôn ngữ bạn ưu tiên. Bản dịch bằng AI có thể có lỗi.

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

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

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ề hai loại hình nhiều đường:

Đườ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 về tình hình giao thông được nhúng trong đường đa tuyến. Những yêu cầu trả về một hình nhiều đường cơ bản sẽ được tính phí theo mức giá của Routes Basic. Tìm hiểu thêm về thông tin thanh toán cho Routes API.
Đường đa tuyến nhận biết tình trạng 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 cho một khoảng thời gian nhất định của hình nhiều đường. Yêu cầu về hình nhiều đường có thông tin về tình hình giao thông được tính phí theo mức giá của Routes Preferred. 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
Interactive Polyline Encoder Utility (Tiện ích mã hoá hình nhiều đường tương tác) cho phép bạn tạo hình nhiều đường được mã hoá trong giao diện người dùng hoặc giải mã hình nhiều đường để hiển thị trên bản đồ. Ví dụ: hãy sử dụng tiện ích này để giải mã một hình nhiều đường được tạo bằng mã bên dưới.

Lưu ý: Các ký tự đặc biệt trong hình nhiều đường do API REST trả về sẽ được thoát JSON. Để hiển thị các hình nhiều đường này trong Interactive Polyline Encoder Utility (Tiện ích mã hoá hình nhiều đường tương tác), trước tiên, bạn phải huỷ thoát các hình nhiều đường này. Có nhiều tiện ích có thể thực hiện việc huỷ thoát JSON. Để tìm một công cụ, hãy tìm JSON unescape.

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

Một 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ặng và bước.

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 vào mặt nạ trường phản hồi.
Ở cấp chặng, 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 là false cho điểm tham chiếu để cho biế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ó điểm dừng sẽ có hai chặng. Một tuyến đường có một điểm tham chiếu trung gian với via được đặt thành true sẽ có một chặng.
Ở 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ặng 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, cho từng chặng và cho từng 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 từng chặng của tuyến đường và cho từng 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 điểm xuất phát và điểm đến, nên tuyến đường được trả về 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 tham chiếu 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ặng, mỗi chặng có một hình nhiều đường riêng biệ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

Bạn có thể mô tả chất lượng của một hình nhiều đường 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. Cách này hoạt động hiệu quả đối với các giá trị nhỏ (có thể được biểu thị chính xác), nhưng độ chính xác sẽ giảm khi giá trị tăng lên do lỗi làm tròn dấu phẩy động.

Trong phương thức computeRoutes (REST) và ComputeRoutes, điều này được kiểm soát bằng polylineEncoding.
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 (đặc biệt là ở các đường cong).

Trong phương thức computeRoutes (REST) và ComputeRoutes, điều này được kiểm soát bằng polylineQuality.

Đị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 sẽ được mã hoá dưới dạng ENCODED_POLYLINE (mặc định), tức là Định dạng thuật toán hình nhiều đường được mã hoá sẽ được sử dụng, hay GEO_JSON_LINESTRING, tức là định dạng GeoJSON LineString sẽ được sử dụng.

Ví dụ: trong 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 của 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 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 một hình nhiều đường có thông tin về tình hình giao thông

Các ví dụ nêu trên đều trả về hình nhiều đường cơ bản, tức là hình nhiều đường không có thông tin về tình hình 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 về tình hình giao thông cho tuyến đường và cho từng chặng của tuyến đường.

Đường đa tuyến nhận biết lưu lượng truy cập 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 theo 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 được xác định bằng chỉ mục của điểm bắt đầu (bao gồm) và điểm kết thúc (không bao gồm) của 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 các điểm của hình nhiều đường 2 và 4:

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

Để gửi yêu cầu tính toán một hình nhiều đường có thông tin về tình hình giao thông, 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 năng 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ỳ phương thức di chuyển nào khác đều trả về lỗi.
Chỉ định lựa chọn ưu tiên về tuyến đường TRAFFIC_AWARE hoặc TRAFFIC_AWARE_OPTIMAL trong yêu cầu. Để biết thêm thông tin, hãy xem phần Đị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 việc 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 di chuyển trong phản hồi bằng cách thêm routes.travelAdvisory vào mặt nạ trường phản hồi. Để chỉ trả về thông tin lưu lượng truy cập, hãy chỉ định routes.travelAdvisory.speedReadingIntervals
- Ở cấp chặng, hãy trả về tất cả thông tin về chuyến đ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 giao thông, 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'

Ví dụ về phản hồi cho một đường đa tuyến có thông tin về tình hình giao thông

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 bao gồm một trường mảng có tên là speedReadingIntervals, chứa thông tin về tốc độ giao thông. 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 thông tin về tốc độ cho một khoảng thời gian trên 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 của tuyến đường mà không bị chồng chéo. Điểm bắt đầu của một khoảng thời gian cụ thể 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. 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.

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, tình trạng giao thông từ chỉ mục 2 đến chỉ mục 4 là như nhau.

Hiển thị hình nhiều đường có thông tin về tình hình giao thông bằng Maps SDK

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

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

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 hình nhiều đường. Ví dụ: bạn có thể quyết định hiển thị tốc độ "BÌNH THƯỜNG" dưới dạng một đường màu xanh dương đậm trên bản đồ, còn tốc độ "CHẬM" có thể hiển thị dưới dạng một đường màu cam đậm.

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 phần Tuỳ chỉnh giao diện (dành cho Android) và Tuỳ chỉnh hình nhiều đường (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

Sử dụng hình nhiều đường được mã hoá với tính năng Tìm dọc theo tuyến đường

Sử dụng tính năng Tìm kiếm văn bản (Mới) trong Places API (Mới) để tìm kiếm dọc theo một tuyến đường đã tính toán. Bạn truyền hình nhiều đường được mã hoá của một tuyến đường được tính toán trước từ phương thức Compute Routes của Routes API đến yêu cầu Tìm kiếm văn bản (Mới). Sau đó, phản hồi sẽ chứa các địa điểm khớp với tiêu chí tìm kiếm và cũng nằm gần tuyến đường được chỉ định. Để biết thông tin chi tiết, hãy xem bài viết tìm kiếm dọc theo tuyến đường.

Ví dụ: để trả về các quán cà phê dọc theo tuyến đường giữa điểm xuất phát và điểm đến:

Node.js

const API_KEY = 'YOUR_API_KEY';
const routes_service = 'https://routes.googleapis.com/directions/v2:computeRoutes';
const textSearch_service = 'https://places.googleapis.com/v1/places:searchText';

                       }             } function init(){ const routes_request = { "origin":{ "address": "1600 Amphitheatre Parkway, Mountain View, CA" }, "destination":{ "address": "24 Willie Mays Plaza, San Francisco, CA 94107" }, "travelMode": "DRIVE" }; const textSearch_request = { "textQuery": "cafe", "searchAlongRouteParameters": { "polyline": { "encodedPolyline": "" } } }; fetchResources(routes_service,routes_request).then(routes => { textSearch_request.searchAlongRouteParameters.polyline.encodedPolyline = routes.routes[0].polyline.encodedPolyline; fetchResources(textSearch_service,textSearch_request).then(places => { console.log(places); }); }); async function fetchResources(resource,reqBody){ const response = await fetch(resource, { method: 'POST', body: JSON.stringify(reqBody), headers: { 'Content-Type': 'application/json', 'X-Goog-Api-Key': API_KEY, 'X-Goog-FieldMask': '*' } }); const responseJSON = await response.json(); return responseJSON; >init();