ค้นหาบนเส้นทาง

เครื่องมือ search_along_route ช่วยให้ LLM ค้นหาสถานที่ตามเส้นทางการเดินทางจากการค้นหาด้วยภาษาธรรมชาติ เช่น สถานีชาร์จ EV ระหว่างทางไปทะเลสาบทาโฮ หรือร้านกาแฟระหว่างซานฟรานซิสโกกับซานโฮเซ เครื่องมือจะแสดงข้อมูลสรุปที่ AI สร้างขึ้นเกี่ยวกับสถานที่ที่ตรงกันและข้อดีข้อเสียของการอ้อมเส้นทาง สำหรับสถานที่แต่ละแห่งที่อ้างถึงในข้อมูลสรุป คำตอบจะรวมรหัสสถานที่ พิกัดละติจูด/ลองจิจูด ลิงก์ Google Maps การระบุแหล่งที่มาที่จำเป็น และเมตริกการออกนอกเส้นทางด้วย

คำขอ search_along_route ทุกรายการเป็นตัวเลือก Pro และจะเรียกเก็บเงินภายใต้ SKU Maps Grounding Pro

คุณเรียกใช้ search_along_route ผ่านเซิร์ฟเวอร์ MCP หรือเป็นเมธอด REST searchAlongRoute ได้ หน้านี้อธิบายตัวเลือกคำขอ วิธีระบุเส้นทาง สิ่งที่การตอบกลับมี และวิธีเรียกเก็บเงินสำหรับคำขอ ดูสคีมาทั้งหมดได้ที่เอกสารอ้างอิง MCP ของ search_along_route และเอกสารอ้างอิง REST ของ searchAlongRoute

ตัวเลือกคำขอ

LLM จะตั้งค่าตัวเลือกเหล่านี้เมื่อเรียกใช้เครื่องมือ โดยอิงตามคำขอของผู้ใช้และคำอธิบายเครื่องมือ คุณสามารถกำหนดตัวเลือกที่โมเดลจะใช้ได้ด้วยคำสั่งของคุณเอง โปรดดูหัวข้อควบคุมการใช้งาน Pro

ตารางต่อไปนี้อธิบายตัวเลือกคำขอสำหรับ search_along_route

ตัวเลือก คำอธิบาย
text_query ต้องระบุ คำค้นหาโดยใช้ภาษาธรรมชาติสำหรับสถานที่ตามเส้นทาง เช่น ev chargers, coffee หรือ vegetarian restaurants
retrieval_token, route_endpoints หรือ encoded_polyline ต้องระบุ เส้นทางที่จะค้นหาตาม ระบุช่องใดช่องหนึ่งใน 3 ช่องนี้ในคำขอแต่ละรายการ โปรดดูหัวข้อระบุเส้นทาง
travel_mode ไม่บังคับ รูปแบบการเดินทางที่ใช้ในการคำนวณเส้นทางและทางอ้อม: DRIVE (ค่าเริ่มต้น), WALK หรือ BICYCLE WALK และ BICYCLE รองรับเฉพาะ route_endpoints เท่านั้น ไม่รองรับ TRANSIT เส้นทางWALKอยู่ในเวอร์ชันเบต้า และบางครั้งอาจไม่มีทางเท้าหรือทางเดินเท้าที่ชัดเจน คุณต้องแสดงคำเตือนนี้แก่ผู้ใช้สำหรับเส้นทางการเดินเท้าทั้งหมดที่แสดงในแอป
routing_preference ไม่บังคับ วิธีใช้ข้อมูลการจราจรเพื่อคำนวณเส้นทางและเวลาที่ใช้ในการอ้อม: ROUTING_PREFERENCE_TRAFFIC_UNAWARE (ค่าเริ่มต้น) หรือ ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL ใช้สภาพการจราจรแบบเรียลไทม์เมื่อพร้อมใช้งาน และไม่รองรับ WALK หรือ BICYCLE
include_extended_details ไม่บังคับ เมื่อtrue ข้อมูลสรุปจะรวมรายละเอียดสถานที่เพิ่มเติม เช่น ข้อมูลเชิงลึกจากรีวิว รายการเมนู บรรยากาศ เคล็ดลับสำหรับผู้เข้าชม ความพร้อมให้บริการที่ชาร์จ EV หรือราคาน้ำมัน ค่าเริ่มต้นคือ false
language_code ไม่บังคับ รหัสภาษา BCP-47 สำหรับสรุปและระยะทางอ้อมที่แปลแล้ว เช่น en-US หรือ ja ค่าเริ่มต้นคือ en-US
region_code ไม่บังคับ รหัสภูมิภาค CLDR 2 ตัวอักษรของผู้ใช้ เช่น US หรือ CA ส่งผลต่อชื่อสถานที่เฉพาะภูมิภาคและอาจส่งผลต่อผลลัพธ์ตามกฎหมายที่เกี่ยวข้อง

ระบุเส้นทาง

คำขอ search_along_route แต่ละรายการต้องระบุเส้นทางโดยใช้ฟิลด์ใดฟิลด์หนึ่งจาก 3 ฟิลด์ที่แยกกันโดยสิ้นเชิง การตั้งค่าช่องเส้นทางมากกว่า 1 ช่องหรือละเว้นทั้ง 3 ช่องจะแสดงข้อผิดพลาด INVALID_ARGUMENT

ตารางต่อไปนี้เปรียบเทียบวิธีระบุเส้นทาง 3 วิธี

ตัวเลือกเส้นทาง รูปแบบอินพุต รูปแบบการเดินทางที่รองรับ แสดงผล detourDuration ใช้เมื่อใด
retrieval_token สตริง retrievalToken จากการตอบกลับ compute_routes ก่อนหน้า (ใช้ได้ 10 นาที) DRIVE ใช่ ตัวแทนได้เรียกใช้ compute_routes สำหรับเส้นทางการขับรถแล้ว ซึ่งรวมถึงเส้นทางที่มีจุดแวะพักระหว่างทาง และผู้ใช้ขอสถานที่ตามเส้นทางนั้น
route_endpoints ออบเจ็กต์ที่มีจุดอ้างอิง origin และ destination (address, place_id หรือ lat_lng) DRIVE, WALK, BICYCLE ใช่ ผู้ใช้ขอให้ค้นหาสถานที่ระหว่าง 2 ตำแหน่งในขั้นตอนเดียวโดยไม่ต้องเรียกใช้ compute_routes ก่อน หรือเส้นทางใช้การเดินหรือการปั่นจักรยาน
encoded_polyline สตริงเส้นประกอบที่เข้ารหัสซึ่งแสดงเส้นทางการขับรถ DRIVE ไม่ (แสดงเฉพาะ localizedDetourDistance) แอปพลิเคชันของคุณมีเส้นประกอบเส้นทางจากแหล่งที่มาอื่นอยู่แล้ว เช่น Routes API

Chain compute_routes และ search_along_route

เมื่อคำขอ compute_routes ใช้โหมดการเดินทาง DRIVE แต่ละเส้นทางในการตอบกลับจะมีช่อง retrievalToken โทเค็นนี้ใช้ได้เป็นเวลา 10 นาทีและเข้ารหัสเส้นทางที่คำนวณ รวมถึงจุดแวะพักระหว่างทาง เมื่อผู้ใช้ติดตามผลโดยขอสถานที่ตามเส้นทางนั้น LLM จะส่งค่า retrievalToken เป็น retrieval_token ใน search_along_route ได้

รายละเอียดสถานที่เพิ่มเติม

ตั้งค่า include_extended_details เป็น true เมื่อคำขอของผู้ใช้ต้องการข้อมูลเชิงลึกเชิงคุณภาพ สภาพการณ์แบบเรียลไทม์ หรือแอตทริบิวต์เฉพาะทางตลอดเส้นทาง เช่น

  • สิ่งที่ผู้รีวิวพูดถึง: ข้อมูลเชิงลึกจากรีวิว ความรู้สึกของลูกค้า และความคิดเห็น
  • ข้อเสนอที่เฉพาะเจาะจง: รายการเมนู อาหาร อาหารพิเศษ เครื่องดื่ม หรือไฮไลต์ของธุรกิจ
  • บรรยากาศ: การตกแต่งภายใน สุนทรียภาพ บรรยากาศ หรืออารมณ์
  • เคล็ดลับที่เป็นประโยชน์สำหรับผู้เข้าชมและข้อมูลแบบเรียลไทม์ เช่น ต้องจองล่วงหน้าหรือไม่ เวลารอ ความหนาแน่นของสถานที่ ความพร้อมให้บริการของที่ชาร์จ EV ราคาน้ำมัน ที่จอดรถ และสิ่งอำนวยความสะดวก

ปล่อยให้ include_extended_details ตั้งค่าเป็น false (ค่าเริ่มต้น) สำหรับการค้นหามาตรฐานตามเส้นทาง เช่น การค้นหาปั๊มน้ำมัน จุดพักรถ หรือร้านกาแฟตามสถานที่ เวลาทำการ และเวลาที่ใช้ในการออกนอกเส้นทาง คำขอที่มีรายละเอียดเพิ่มเติมจะใช้เวลาดำเนินการนานกว่า แต่จะไม่มีค่าใช้จ่ายเพิ่มเติมเนื่องจากคำขอ search_along_route ทุกรายการจะเรียกเก็บเงินภายใต้ SKU แบบ Pro อยู่แล้ว

ตัวอย่าง

คำขอ MCP ต่อไปนี้จะค้นหาสถานีชาร์จ EV ระหว่างซานฟรานซิสโกกับทะเลสาบทาโฮโดยใช้ route_endpoints และการกำหนดเส้นทางที่คำนึงถึงการจราจร

{
  "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
}

ตัวอย่างต่อไปนี้ใช้ retrieval_token จากการตอบกลับ compute_routes ก่อนหน้า

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

แทนที่ RETRIEVAL_TOKEN ด้วยสตริง retrievalToken ที่แสดงผลโดย compute_routes

ตัวอย่างต่อไปนี้จะส่งคำขอแรกไปยังเมธอด 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"

แทนที่ API_KEY ด้วยคีย์ API ของคุณ

คำตอบ

การตอบกลับจะมีฟิลด์ต่อไปนี้

  • summary: สรุปผลการค้นหาและข้อดีข้อเสียของการเปลี่ยนเส้นทางโดยใช้ภาษาธรรมชาติ โดยอาจมีการอ้างอิงแบบอิงตามศูนย์ เช่น [0] ซึ่งแมปกับรายการใน results
  • results[]: รายการสถานที่ที่จัดอันดับซึ่งพูดถึงในข้อมูลสรุป แต่ละรายการประกอบด้วยข้อมูลต่อไปนี้
    • place: รายละเอียดเกี่ยวกับสถานที่:
      • place: ชื่อทรัพยากรของสถานที่ในรูปแบบ places/{id}
      • id: รหัสสถานที่ คุณสามารถใช้รหัสนี้กับ API อื่นๆ ของ Google Maps Platform เช่น เพื่อแสดงสถานที่บนแผนที่
      • location: พิกัดละติจูด/ลองจิจูดของสถานที่
      • googleMapsLinks: ลิงก์ Google Maps สำหรับสถานที่ (placeUrl) เส้นทาง (directionsUrl) รีวิว (reviewsUrl) รูปภาพ (photosUrl) และการเขียนรีวิว (writeAReviewUrl)
      • attribution: การระบุแหล่งที่มาที่คุณต้องแสดงพร้อมกับสถานที่ ดูข้อกำหนดในการระบุแหล่งที่มา
    • detourSummary: ระยะเวลาเดินทางและระยะทางเพิ่มเติมที่จำเป็นสำหรับการแวะที่สถานที่นี้ตามเส้นทาง
      • localizedDetourDistance: ระยะทางเพิ่มเติมที่จัดรูปแบบในภาษาของคำขอ เช่น "1.2 mi" หรือ "1.9 km"
      • detourDuration: ระยะเวลาเดินทางเพิ่มเติมเป็นสตริงระยะเวลา เช่น "180s" ระบบจะไม่ตั้งค่าช่องนี้เมื่อระบุเส้นทางด้วย encoded_polyline
  • contentToken: โทเค็นการแสดงข้อมูลผ่านภาพแบบ Agentic (เวอร์ชันตัวอย่าง) ที่ช่วยให้คุณแสดงสถานที่ในคำตอบด้วย Places UI Kit ได้โดยไม่มีค่าใช้จ่ายเพิ่มเติม แสดงผลเมื่อการตอบกลับมีสถานที่อย่างน้อย 1 แห่ง

ดูรายละเอียดช่องทั้งหมดได้ในข้อมูลอ้างอิง search_along_route

การเรียกเก็บเงินและโควต้า

คำขอ search_along_route แต่ละรายการเป็นเหตุการณ์ที่เรียกเก็บเงินได้ 1 รายการภายใต้ SKU Maps Grounding Pro การตั้งค่า include_extended_details เป็น true หรือ routing_preference เป็น ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL จะไม่มีค่าใช้จ่ายเพิ่มเติม หาก Agent เรียกใช้ compute_routes ก่อน แล้วส่ง retrieval_token ไปยัง search_along_route ระบบจะเรียกเก็บเงินสำหรับการเรียกใช้เครื่องมือแต่ละครั้งเป็นคำขอแยกกัน

หากแสดงสถานที่จากการตอบกลับของ search_along_route ด้วย Places UI Kit คุณสามารถใช้โทเค็นการแสดงข้อมูลผ่านภาพแบบ Agentic (เวอร์ชันตัวอย่าง) เพื่อไม่ให้ระบบเรียกเก็บเงินสำหรับคำขอ Places UI Kit เหล่านั้น

โควต้า search_along_route คือคำค้นหา 300 รายการต่อนาทีสำหรับแต่ละโปรเจ็กต์ ดูราคาได้ที่ตารางราคาหลักและตารางราคาสำหรับอินเดีย