search_along_route टूल की मदद से, एलएलएम किसी यात्रा के रास्ते में पड़ने वाली जगहों को ढूंढ सकता है. इसके लिए, वह नैचुरल लैंग्वेज क्वेरी का इस्तेमाल करता है. जैसे, लेक टाहो के रास्ते में पड़ने वाले ईवी चार्जिंग स्टेशन या सैन फ़्रैंसिस्को और सैन होज़े के बीच पड़ने वाली कॉफ़ी शॉप. यह टूल, आपकी क्वेरी से मैच करने वाली जगहों और उनके लिए उपलब्ध रास्तों की खास जानकारी देता है. यह जानकारी एआई की मदद से जनरेट की जाती है. खास जानकारी में बताई गई हर जगह के लिए, जवाब में जगह का आईडी, अक्षांश/देशांतर निर्देशांक, Google Maps में किसी जगह पर ले जाने वाला लिंक, ज़रूरी एट्रिब्यूशन, और रास्ते में पड़ने वाली जगहों की मेट्रिक भी शामिल होती हैं.
search_along_route का हर अनुरोध, Pro विकल्प है. इसके लिए, Maps Grounding Pro एसकेयू के तहत बिल भेजा जाता है.
search_along_route को एमसीपी सर्वर या searchAlongRoute REST तरीके से कॉल किया जा सकता है. इस पेज पर, अनुरोध के विकल्पों, रास्ते की जानकारी देने के तरीके, जवाब में मौजूद जानकारी, और अनुरोधों के लिए बिलिंग के तरीके के बारे में बताया गया है. पूरे स्कीमा के लिए, search_along_route एमसीपी रेफ़रंस और searchAlongRoute REST रेफ़रंस देखें.
अनुरोध करने के विकल्प
एलएलएम, टूल को कॉल करते समय इन विकल्पों को सेट करता है. यह उपयोगकर्ता के अनुरोध और टूल के ब्यौरे के आधार पर किया जाता है. अपने निर्देशों की मदद से, यह तय किया जा सकता है कि मॉडल किन विकल्पों का इस्तेमाल करे. इसके लिए, Pro वर्शन के इस्तेमाल को कंट्रोल करना लेख पढ़ें.
यहां दी गई टेबल में, search_along_route के लिए अनुरोध के विकल्पों के बारे में बताया गया है:
| विकल्प | ब्यौरा |
|---|---|
text_query |
ज़रूरी है. रास्ते में मौजूद जगहों के लिए, बोलचाल की भाषा में सर्च क्वेरी. उदाहरण के लिए, ev chargers, coffee या vegetarian restaurants. |
retrieval_token, route_endpoints या encoded_polyline |
ज़रूरी है. वह रास्ता जिसके आस-पास मौजूद जगहों को खोजना है. हर अनुरोध में, इन तीन फ़ील्ड में से किसी एक की वैल्यू दें. कोई रास्ता तय करना देखें. |
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 होने पर, खास जानकारी में जगह की ज़्यादा जानकारी शामिल होती है. जैसे, समीक्षाओं से मिली अहम जानकारी, मेन्यू आइटम, माहौल, विज़िटर के लिए सलाह, ईवी चार्जर की उपलब्धता या पेट्रोल/डीज़ल की कीमतें. डिफ़ॉल्ट रूप से, यह false पर सेट होता है. |
language_code |
ज़रूरी नहीं. खास जानकारी और स्थानीय भाषा में रास्ते की दूरी के लिए BCP-47 भाषा कोड. उदाहरण के लिए, en-US या ja. डिफ़ॉल्ट रूप से, यह en-US पर सेट होता है. |
region_code |
ज़रूरी नहीं. उपयोगकर्ता के देश/इलाके का दो अक्षरों वाला CLDR कोड. उदाहरण के लिए, US या CA. इससे क्षेत्र के हिसाब से जगहों के नामों पर असर पड़ता है. साथ ही, लागू कानून के आधार पर नतीजों पर भी असर पड़ सकता है. |
कोई रास्ता तय करना
search_along_route के हर अनुरोध में, तीन में से किसी एक फ़ील्ड का इस्तेमाल करके रूट की जानकारी देना ज़रूरी है. ये तीनों फ़ील्ड एक-दूसरे से अलग होते हैं. एक से ज़्यादा रूट फ़ील्ड सेट करने या तीनों को छोड़ने पर, INVALID_ARGUMENT गड़बड़ी का मैसेज दिखता है.
यहां दी गई टेबल में, रूट तय करने के तीन तरीकों की तुलना की गई है:
| रास्ते का विकल्प | इनपुट फ़ॉर्मैट | यात्रा के लिए इस्तेमाल किए जा सकने वाले मोड | detourDuration दिखाता है |
इसका इस्तेमाल कब करें |
|---|---|---|---|---|
retrieval_token |
पिछले compute_routes रिस्पॉन्स से मिली retrievalToken स्ट्रिंग (10 मिनट के लिए मान्य) |
DRIVE |
हां | एजेंट ने पहले ही compute_routes को कॉल करके, ड्राइविंग रूट की जानकारी मांगी है. इसमें बीच में रुकने वाले रास्ते भी शामिल हैं. साथ ही, उपयोगकर्ता ने उस रास्ते पर मौजूद जगहों के बारे में पूछा है. |
route_endpoints |
origin और destination वेपॉइंट वाला ऑब्जेक्ट (address, place_id या lat_lng) |
DRIVE, WALK, BICYCLE |
हां | उपयोगकर्ता ने compute_routes को कॉल किए बिना, एक ही चरण में दो जगहों के बीच की जगहें ढूंढने के लिए कहा है या रास्ते में पैदल या साइकल से यात्रा करने का विकल्प चुना है. |
encoded_polyline |
ड्राइविंग रूट दिखाने वाली एन्कोड की गई पॉलीलाइन स्ट्रिंग | DRIVE |
नहीं (सिर्फ़ localizedDetourDistance दिखाता है) |
आपके ऐप्लिकेशन में पहले से ही किसी अन्य सोर्स से रूट पॉलीलाइन मौजूद है, जैसे कि Routes API. |
चेन compute_routes और search_along_route
जब कोई compute_routes अनुरोध, DRIVE यात्रा मोड का इस्तेमाल करता है, तो जवाब में हर रास्ते में retrievalToken फ़ील्ड शामिल होता है. यह टोकन 10 मिनट के लिए मान्य होता है. इसमें, तय किए गए रास्ते को एन्कोड किया जाता है. इसमें रास्ते में पड़ने वाले स्टॉप भी शामिल होते हैं. जब उपयोगकर्ता उस रास्ते पर मौजूद जगहों के बारे में पूछता है, तो एलएलएम, search_along_route में retrievalToken वैल्यू को retrieval_token के तौर पर पास कर सकता है.
जगह की ज़्यादा जानकारी
जब उपयोगकर्ता के अनुरोध के लिए, रास्ते के बारे में गुणात्मक जानकारी, रीयल-टाइम की स्थितियों या खास एट्रिब्यूट की ज़रूरत हो, तो include_extended_details को true पर सेट करें. जैसे:
- समीक्षा करने वाले लोगों की राय: समीक्षाओं के आधार पर मिली अहम जानकारी, ग्राहकों की भावनाएं, और सुझाव/राय/शिकायत.
- खास ऑफ़र: मेन्यू आइटम, पकवान, खास तरह का खाना, पेय पदार्थ या कारोबार की खास बातें.
- माहौल: इंटीरियर डेकोर, एस्थेटिक, माहौल या मूड.
- विज़िटर के लिए काम की सलाह और रीयल-टाइम डेटा: पहले से बुकिंग करनी है या नहीं, इंतज़ार करने का समय, जगह पर कितनी भीड़ है, ईवी चार्जर की उपलब्धता, पेट्रोल/डीज़ल की कीमतें, पार्किंग, और सुविधाएं.
किसी रास्ते पर स्टैंडर्ड खोजों के लिए, include_extended_details को false (डिफ़ॉल्ट) पर सेट रहने दें. जैसे, जगह की जानकारी, कारोबार के खुले होने का समय, और रास्ते से भटकने के समय के हिसाब से पेट्रोल पंप, रेस्ट स्टॉप या कॉफ़ी शॉप ढूंढना. ज़्यादा जानकारी वाले अनुरोधों को पूरा होने में ज़्यादा समय लगता है. हालांकि, इनके लिए कोई अतिरिक्त शुल्क नहीं लिया जाता, क्योंकि हर search_along_route अनुरोध के लिए, Pro SKU के तहत पहले ही बिल भेजा जा चुका होता है.
उदाहरण
एमसीपी का यह अनुरोध, 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
}
इस उदाहरण में, compute_routes के पिछले जवाब से मिले retrieval_token का इस्तेमाल किया गया है:
{ "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 से मिलती है.
यहां दिए गए उदाहरण में, searchAlongRoute REST तरीके को पहला अनुरोध भेजा गया है:
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 को अपने एपीआई पासकोड से बदलें.
जवाब
जवाब में ये फ़ील्ड शामिल होते हैं:
summary: खोज के नतीजों और रास्ते में पड़ने वाली जगहों की जानकारी की नैचुरल लैंग्वेज में खास जानकारी. इसमें[0]जैसे ज़ीरो-बेस्ड उद्धरण हो सकते हैं, जोresultsमें मौजूद एंट्री से मैप होते हैं.results[]: खास जानकारी में बताई गई जगहों की रैंक की गई सूची. हर एंट्री में ये चीज़ें शामिल होती हैं:place: जगह के बारे में जानकारी:place: जगह के संसाधन का नाम,places/{id}फ़ॉर्मैट में.id: जगह का आईडी. इसे 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: यह एक एजेंटिक डेटा विज़ुअलाइज़ेशन टोकन (झलक) है. इसकी मदद से, जवाब में जगहों की जानकारी को जगहों की जानकारी देने वाली यूआई किट के साथ दिखाया जा सकता है. इसके लिए, आपको कोई अलग से शुल्क नहीं देना होगा. यह तब दिखता है, जब जवाब में कम से कम एक जगह शामिल हो.
फ़ील्ड की पूरी जानकारी के लिए,
search_along_route रेफ़रंस देखें.
बिलिंग और कोटा
search_along_route का हर अनुरोध, Maps Grounding Pro SKU के तहत बिल किया जाने वाला एक इवेंट होता है.
include_extended_details को true या routing_preference को ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL पर सेट करने से, कोई अतिरिक्त शुल्क नहीं लगता. अगर आपका एजेंट पहले compute_routes को कॉल करता है और फिर retrieval_token को search_along_route को पास करता है, तो हर टूल कॉल को एक अलग अनुरोध के तौर पर बिल किया जाता है.
अगर जगहों की जानकारी देने वाली यूआई किट की मदद से, search_along_route के रिस्पॉन्स में मिली जगहों की जानकारी दिखाई जाती है, तो एजेंटिक डेटा विज़ुअलाइज़ेशन टोकन (झलक) का इस्तेमाल किया जा सकता है. इससे, जगहों की जानकारी देने वाली यूआई किट के उन अनुरोधों के लिए शुल्क नहीं लिया जाएगा.
search_along_route के लिए, हर प्रोजेक्ट के लिए हर मिनट 300 क्वेरी का कोटा तय किया गया है. कीमतों के बारे में जानने के लिए, कीमतों की मुख्य टेबल और भारत के लिए कीमतों की टेबल देखें.