Tìm dọc theo tuyến đường

Công cụ search_along_route cho phép LLM tìm các địa điểm dọc theo tuyến đường du lịch từ một truy vấn bằng ngôn ngữ tự nhiên, chẳng hạn như các trạm sạc xe điện trên đường đến Hồ Tahoe hoặc các quán cà phê giữa San Francisco và San Jose. Công cụ này trả về một bản tóm tắt do AI tạo về các địa điểm phù hợp và những điểm cần cân nhắc khi đi đường vòng. Đối với mỗi địa điểm được trích dẫn trong bản tóm tắt, câu trả lời cũng bao gồm Mã địa điểm, toạ độ vĩ độ/kinh độ, đường liên kết đến Google Maps, thông tin ghi nhận tác giả bắt buộc và chỉ số về đường vòng.

Mỗi yêu cầu search_along_route là một lựa chọn Pro và được tính phí theo SKU Maps Grounding Pro.

Bạn có thể gọi search_along_route thông qua máy chủ MCP hoặc dưới dạng phương thức REST searchAlongRoute. Trang này mô tả các lựa chọn yêu cầu, cách chỉ định tuyến đường, nội dung phản hồi và cách tính phí cho các yêu cầu. Để xem giản đồ đầy đủ, hãy xem tài liệu tham khảo về MCP search_along_route và tài liệu tham khảo về REST searchAlongRoute.

Lựa chọn yêu cầu

LLM đặt các tuỳ chọn này khi gọi công cụ, dựa trên yêu cầu của người dùng và nội dung mô tả công cụ. Bạn có thể tác động đến các lựa chọn mà mô hình sử dụng bằng hướng dẫn của riêng bạn; hãy xem phần Kiểm soát việc sử dụng Pro.

Bảng sau đây mô tả các tuỳ chọn yêu cầu cho search_along_route:

Phương thức Mô tả
text_query Bắt buộc. Cụm từ tìm kiếm bằng ngôn ngữ tự nhiên cho các địa điểm dọc theo tuyến đường, ví dụ: ev chargers, coffee hoặc vegetarian restaurants.
retrieval_token, route_endpoints hoặc encoded_polyline Bắt buộc. Tuyến đường để tìm kiếm dọc theo. Chỉ định một trong ba trường này trong mỗi yêu cầu. Xem phần Chỉ định tuyến đường.
travel_mode Không bắt buộc. Phương thức di chuyển dùng để tính toán tuyến đường và đường vòng: DRIVE (mặc định), WALK hoặc BICYCLE. WALK và BICYCLE chỉ được hỗ trợ với route_endpoints. TRANSIT không được hỗ trợ. Tuyến đường WALK đang trong giai đoạn thử nghiệm và đôi khi có thể thiếu vỉa hè hoặc lối đi rõ ràng cho người đi bộ. Bạn phải hiển thị cảnh báo này cho người dùng đối với tất cả tuyến đường đi bộ mà bạn hiển thị trong ứng dụng của mình.
routing_preference Không bắt buộc. Cách dữ liệu giao thông được dùng để tính toán thời gian đi theo tuyến đường và thời gian đi đường vòng: ROUTING_PREFERENCE_TRAFFIC_UNAWARE (mặc định) hoặc ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL. ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL sử dụng tình trạng giao thông trực tiếp khi có sẵn và không được hỗ trợ cho WALK hoặc BICYCLE.
include_extended_details Không bắt buộc. Khi true, bản tóm tắt sẽ bao gồm thông tin chi tiết mở rộng về địa điểm, chẳng hạn như thông tin chi tiết từ các bài đánh giá, món ăn trong thực đơn, bầu không khí, mẹo cho khách truy cập, tình trạng còn bộ sạc xe điện hoặc giá xăng. Mặc định là false.
language_code Không bắt buộc. Mã ngôn ngữ BCP-47 cho thông tin tóm tắt và khoảng cách đường vòng được bản địa hoá, ví dụ: en-US hoặc ja. Mặc định là en-US.
region_code Không bắt buộc. Mã vùng CLDR gồm hai chữ cái của người dùng, ví dụ: US hoặc CA. Ảnh hưởng đến tên địa điểm theo khu vực cụ thể và có thể ảnh hưởng đến kết quả dựa trên luật hiện hành.

Chỉ định một tuyến đường

Mỗi yêu cầu search_along_route phải chỉ định tuyến đường bằng một trong ba trường loại trừ lẫn nhau. Nếu bạn đặt nhiều trường tuyến đường hoặc bỏ qua cả ba trường, thì hệ thống sẽ trả về lỗi INVALID_ARGUMENT.

Bảng sau đây so sánh 3 cách chỉ định tuyến đường:

Lựa chọn cho tuyến đường Định dạng đầu vào Các phương tiện được hỗ trợ Trả về detourDuration Trường hợp sử dụng
retrieval_token Chuỗi retrievalToken từ phản hồi compute_routes trước đó (có hiệu lực trong 10 phút) DRIVE Có Tác nhân đã gọi compute_routes cho một tuyến đường lái xe, bao gồm cả các tuyến đường có điểm dừng trung gian và người dùng yêu cầu các địa điểm dọc theo tuyến đường đó.
route_endpoints Một đối tượng có các điểm tham chiếu origin và destination (address, place_id hoặc lat_lng) DRIVE, WALK, BICYCLE Có Người dùng yêu cầu tìm địa điểm giữa hai vị trí trong một bước mà không cần gọi compute_routes trước hoặc tuyến đường sử dụng phương tiện đi bộ hoặc đi xe đạp.
encoded_polyline Một chuỗi hình nhiều đường được mã hoá biểu thị tuyến đường lái xe DRIVE Không (chỉ trả về localizedDetourDistance) Ứng dụng của bạn đã có một hình nhiều đường cho tuyến đường từ một nguồn khác, chẳng hạn như Routes API.

Chuỗi compute_routes và search_along_route

Khi yêu cầu compute_routes sử dụng phương thức di chuyển DRIVE, mỗi tuyến đường trong phản hồi sẽ bao gồm một trường retrievalToken. Mã thông báo này có hiệu lực trong 10 phút và mã hoá tuyến đường được tính toán, bao gồm cả mọi điểm dừng trung gian. Khi người dùng tiếp tục hỏi về các địa điểm dọc theo tuyến đường đó, LLM có thể truyền giá trị retrievalToken dưới dạng retrieval_token trong search_along_route.

Thông tin chi tiết mở rộng về địa điểm

Đặt include_extended_details thành true khi yêu cầu của người dùng cần thông tin chi tiết định tính, điều kiện theo thời gian thực hoặc thuộc tính chuyên biệt dọc theo tuyến đường, chẳng hạn như:

  • Ý kiến của người đánh giá: thông tin chi tiết dựa trên bài đánh giá, cảm nhận và ý kiến phản hồi của khách hàng.
  • Sản phẩm/dịch vụ cụ thể: món trong thực đơn, món ăn, món ăn đặc sản, đồ uống hoặc điểm nổi bật của doanh nghiệp.
  • Bầu không khí: trang trí nội thất, tính thẩm mỹ, không gian hoặc tâm trạng.
  • Mẹo hữu ích cho khách tham quan và dữ liệu theo thời gian thực: có nên đặt trước hay không, thời gian chờ, mức độ đông đúc của địa điểm, tình trạng bộ sạc xe điện, giá xăng, bãi đỗ xe và cơ sở vật chất.

Giữ nguyên include_extended_details thành false (mặc định) cho các lượt tìm kiếm tiêu chuẩn dọc theo tuyến đường, chẳng hạn như tìm trạm xăng, trạm nghỉ hoặc quán cà phê theo vị trí, giờ hoạt động và thời gian đi đường vòng. Các yêu cầu có thông tin chi tiết mở rộng sẽ mất nhiều thời gian hơn để hoàn tất, nhưng không làm tăng thêm phí vì mọi yêu cầu search_along_route đều đã được tính phí theo SKU Pro.

Ví dụ

Yêu cầu MCP sau đây tìm kiếm các trạm sạc xe điện giữa San Francisco và Lake Tahoe bằng cách sử dụng route_endpoints và định tuyến dựa trên tình hình giao thông:

{
  "method": "tools/call",
  "params": {
    "name": "search_along_route",
    "arguments": {
      "text_query": "fast EV chargers with a coffee shop nearby",
      "route_endpoints": {
        "origin": {"address": "San Francisco, CA"},
        "destination": {"address": "Lake Tahoe, CA"}
      },
      "travel_mode": "DRIVE",
      "routing_preference": "ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL",
      "include_extended_details": true
    }
  },
  "jsonrpc": "2.0",
  "id": 1
}

Ví dụ sau đây sử dụng retrieval_token từ phản hồi compute_routes trước đó:

{
  "method": "tools/call",
  "params": {
    "name": "search_along_route",
    "arguments": {
      "text_query": "coffee shops",
      "retrieval_token": "RETRIEVAL_TOKEN"
    }
  },
  "jsonrpc": "2.0",
  "id": 2
}

Thay thế RETRIEVAL_TOKEN bằng chuỗi retrievalToken do compute_routes trả về.

Ví dụ sau đây gửi yêu cầu đầu tiên đến phương thức REST searchAlongRoute:

curl -X POST \
-H "Content-Type: application/json" \
-H "X-Goog-Api-Key: API_KEY" \
-d '{
  "textQuery": "fast EV chargers with a coffee shop nearby",
  "routeEndpoints": {
    "origin": {"address": "San Francisco, CA"},
    "destination": {"address": "Lake Tahoe, CA"}
  },
  "travelMode": "DRIVE",
  "routingPreference": "ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL",
  "includeExtendedDetails": true
}' \
"https://mapstools.googleapis.com/v1:searchAlongRoute"

Thay thế API_KEY bằng khoá API của bạn.

Phản hồi

Phản hồi chứa các trường sau:

  • summary: Bản tóm tắt bằng ngôn ngữ tự nhiên về kết quả tìm kiếm và những điểm đánh đổi khi đi đường vòng. Câu trả lời có thể chứa các trích dẫn dựa trên số 0, chẳng hạn như [0], liên kết đến các mục trong results.
  • results[]: Danh sách địa điểm được xếp hạng được đề cập trong bản tóm tắt. Mỗi mục nhập bao gồm:
    • place: Thông tin chi tiết về địa điểm:
      • place: Tên tài nguyên của địa điểm, ở định dạng places/{id}.
      • id: Mã địa điểm. Bạn có thể sử dụng mã nhận dạng này với các API khác của Google Maps Platform, chẳng hạn như để hiển thị địa điểm trên bản đồ.
      • location: Toạ độ vĩ độ/kinh độ của địa điểm.
      • googleMapsLinks: Đường liên kết đến Google Maps cho địa điểm (placeUrl), đường đi (directionsUrl), bài đánh giá (reviewsUrl), ảnh (photosUrl) và viết bài đánh giá (writeAReviewUrl).
      • attribution: Thông tin ghi nhận tác giả mà bạn phải hiển thị cùng với địa điểm. Xem Yêu cầu ghi công.
    • detourSummary: Thời gian di chuyển và quãng đường di chuyển thêm cần thiết để dừng tại địa điểm này dọc theo tuyến đường:
      • localizedDetourDistance: Khoảng cách bổ sung được định dạng bằng ngôn ngữ yêu cầu, chẳng hạn như "1.2 mi" hoặc "1.9 km".
      • detourDuration: Thời gian di chuyển thêm dưới dạng chuỗi thời lượng, chẳng hạn như "180s". Trường này không được đặt khi tuyến đường được chỉ định bằng encoded_polyline.
  • contentToken: Một mã thông báo trực quan hoá dữ liệu dựa trên tác nhân (Bản xem trước) cho phép bạn hiển thị các địa điểm trong phản hồi bằng Places UI Kit mà không mất thêm phí. Được trả về khi phản hồi bao gồm ít nhất một địa điểm.

Để biết thông tin chi tiết về trường, hãy xem tài liệu tham khảo về search_along_route.

Thanh toán và hạn mức

Mỗi yêu cầu search_along_route là một sự kiện có tính phí theo SKU Maps Grounding Pro. Việc đặt include_extended_details thành true hoặc routing_preference thành ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL không làm phát sinh thêm phí. Nếu tác nhân của bạn gọi compute_routes trước rồi truyền retrieval_token đến search_along_route, thì mỗi lệnh gọi công cụ sẽ được tính phí dưới dạng một yêu cầu riêng biệt.

Nếu hiển thị các địa điểm từ phản hồi search_along_route bằng Places UI Kit, bạn có thể sử dụng mã trực quan hoá dữ liệu dựa trên tác nhân (Bản xem trước) để không bị tính phí cho các yêu cầu Places UI Kit đó.

Hạn mức của search_along_route là 300 truy vấn mỗi phút cho mỗi dự án. Để biết thông tin về giá, hãy xem Bảng giá chính và Bảng giá tại Ấn Độ.