जगहें खोजें

search_places टूल की मदद से, एलएलएम नैचुरल लैंग्वेज क्वेरी का इस्तेमाल करके, Google Maps पर जगहों को ढूंढ सकता है. यह टूल, क्वेरी से मैच होने वाली जगहों की खास जानकारी देता है. यह जानकारी एआई से जनरेट की जाती है. खास जानकारी में जिन जगहों का ज़िक्र किया जाता है उनके लिए, जगह का आईडी, अक्षांश/देशांतर निर्देशांक, Google Maps में किसी जगह पर ले जाने वाला लिंक, और एट्रिब्यूशन भी मिलता है.

search_places को एमसीपी सर्वर या searchText REST तरीके से कॉल किया जा सकता है. इस पेज पर, अनुरोध के विकल्पों के बारे में बताया गया है. इनमें Pro वर्शन के विकल्प भी शामिल हैं. साथ ही, यह भी बताया गया है कि जवाब में क्या शामिल होता है और अनुरोधों के लिए बिल कैसे भेजा जाता है. पूरे स्कीमा के लिए, search_places एमसीपी रेफ़रंस और searchText REST रेफ़रंस देखें.

अनुरोध करने के विकल्प

एलएलएम, टूल को कॉल करते समय इन विकल्पों को सेट करता है. यह उपयोगकर्ता के अनुरोध और टूल के ब्यौरे के आधार पर किया जाता है. अपने निर्देशों की मदद से, यह तय किया जा सकता है कि मॉडल किन विकल्पों का इस्तेमाल करे. इसके लिए, Pro वर्शन के इस्तेमाल को कंट्रोल करना लेख पढ़ें.

यहां दी गई टेबल में, search_places के लिए अनुरोध के विकल्पों के बारे में बताया गया है:

विकल्प ब्यौरा
text_query ज़रूरी है. सर्च क्वेरी—उदाहरण के लिए, coffee shops near Golden Gate Park. क्वेरी में जगह की इतनी जानकारी होनी चाहिए कि वह साफ़ तौर पर समझ आए या अनुरोध में location_bias शामिल होना चाहिए.
location_bias एक सर्कल (center और वैकल्पिक radius_meters, 50,000 मीटर तक), ताकि नतीजों को बायस किया जा सके. अगर text_query में किसी जगह का नाम साफ़ तौर पर बताया गया है, तो उस जगह का इस्तेमाल किया जाता है.
language_code खास जानकारी की भाषा—उदाहरण के लिए, en या ja. डिफ़ॉल्ट रूप से, यह अंग्रेज़ी पर सेट होती है.
region_code उपयोगकर्ता के देश/इलाके का CLDR कोड—उदाहरण के लिए, US. इससे क्षेत्र के हिसाब से जगहों के नामों पर असर पड़ता है. साथ ही, लागू कानून के आधार पर नतीजों पर भी असर पड़ सकता है.
page_size जगहों की ज़्यादा से ज़्यादा संख्या. डिफ़ॉल्ट रूप से, यह संख्या 5 होती है. 6 से 10 तक की वैल्यू, Pro विकल्प हैं. 10 से ज़्यादा वैल्यू डालने पर, INVALID_ARGUMENT गड़बड़ी का मैसेज दिखता है. ऐसा हो सकता है कि सेवा, अनुरोध की गई जगहों से कम जगहें दिखाए.
include_extended_details true होने पर, खास जानकारी में जगह की ज़्यादा जानकारी शामिल होती है. यह Pro वर्शन का विकल्प है. डिफ़ॉल्ट रूप से, यह false पर सेट होता है.

Pro वर्शन के विकल्प

इन दोनों विकल्पों में से, Maps Grounding Pro SKU को चुनें. इनमें से किसी एक या दोनों का इस्तेमाल करने वाले अनुरोध के लिए, Pro SKU के तहत शुल्क लिया जाता है:

Pro वर्शन इसका इस्तेमाल कब करें
include_extended_details को true पर सेट करें उपयोगकर्ता के अनुरोध के लिए, जगह की ज़्यादा जानकारी की ज़रूरत होती है. जैसे, समीक्षाओं से मिली अहम जानकारी, मेन्यू की खास बातें, माहौल या विज़िटर के लिए सलाह.
6 से 10 तक के लिए page_size उपयोगकर्ता को पांच से ज़्यादा जगहों की तुलना करनी है.

ऐसे अनुरोध जिनमें इनमें से किसी भी विकल्प का इस्तेमाल नहीं किया जाता है उन्हें Essentials SKU के तहत बिल किया जाता है. इनमें 1 से 5 तक के page_size वाले अनुरोध भी शामिल हैं.

जगह की ज़्यादा जानकारी

जब उपयोगकर्ता के अनुरोध के लिए, क्वालिटी से जुड़ी अहम जानकारी, रीयल-टाइम की स्थितियों या खास एट्रिब्यूट की ज़रूरत हो, तो include_extended_details को true पर सेट करें. जैसे:

  • समीक्षकों की राय: समीक्षाओं के आधार पर अहम जानकारी, ग्राहकों की भावनाएं, और सुझाव/राय या शिकायत.
  • खास ऑफ़र: मेन्यू आइटम, पकवान, खास तरह का खाना, पेय पदार्थ या कारोबार की खास बातें.
  • माहौल: इंटीरियर डेकोर, एस्थेटिक, माहौल या मूड.
  • विज़िटर के लिए काम की सलाह: पहले से बुकिंग करनी है या नहीं, वॉक-इन की नीतियां, इंतज़ार का समय, जगह पर कितनी भीड़ है, पार्किंग, और सुविधाएं.
  • नज़दीकी: क्वेरी में बताई गई जगह या location_biasसेंटर से दूरी या यात्रा में लगने वाला समय. ऐसा तब होता है, जब उपयोगकर्ता आस-पास या सबसे नज़दीक मौजूद जगहों के बारे में पूछता है.

खास जानकारी में मौजूद अहम जानकारी, क्वेरी और हर जगह के लिए उपलब्ध डेटा पर निर्भर करती है. हर जवाब में, हर तरह की अहम जानकारी नहीं दिखती.

स्टैंडर्ड खोजों के लिए, इसे false (डिफ़ॉल्ट) पर सेट रहने दें: पकवान या स्टोर के टाइप, पते, संपर्क जानकारी, कारोबार के खुले होने का समय, और स्टैंडर्ड सुविधाएं. जिन अनुरोधों में ज़्यादा जानकारी मांगी जाती है उन्हें पूरा होने में ज़्यादा समय लगता है.

ज़्यादा जानकारी देने से, जवाब के स्ट्रक्चर में कोई बदलाव नहीं होता. इनके बिना, खास जानकारी में हर जगह के बारे में एक या दो वाक्यों में बताया जाता है. इनकी मदद से, हर जगह के बारे में ज़्यादा जानकारी मिलती है. यह जानकारी, Google Maps के ज़्यादा डेटा के आधार पर तैयार की जाती है. इसमें समीक्षाओं से मिली अहम जानकारी भी शामिल होती है. दोनों एसकेयू के लिए, स्ट्रक्चर्ड places एट्रिब्यूट की वैल्यू एक जैसी हैं.

उदाहरण

यहां दिए गए एमसीपी अनुरोध में, ज़्यादा जानकारी के साथ ज़्यादा से ज़्यादा आठ जगहों की जानकारी मांगी गई है. इसका बिल, Pro SKU के तहत जनरेट किया जाता है:

{
  "method": "tools/call",
  "params": {
    "name": "search_places",
    "arguments": {
      "text_query": "date night Italian restaurants in Chicago",
      "page_size": 8,
      "include_extended_details": true
    }
  },
  "jsonrpc": "2.0",
  "id": 1
}

नीचे दिए गए उदाहरण में, searchText REST तरीके से वही अनुरोध भेजा गया है:

curl -X POST \
-H "Content-Type: application/json" \
-H "X-Goog-Api-Key: API_KEY" \
-d '{
  "textQuery": "date night Italian restaurants in Chicago",
  "pageSize": 8,
  "includeExtendedDetails": true
}' \
"https://mapstools.googleapis.com/v1:searchText"

API_KEY को अपने एपीआई पासकोड से बदलें.

ज़्यादा जानकारी के बिना, खास जानकारी में हर जगह के बारे में एक या दो वाक्यों में बताया जाता है:

Example Trattoria [0] (4.6★ (1,250) · 123 W Example St · $$$) A neighborhood trattoria known for handmade pasta and a long wine list.

With extended details, the summary adds what reviewers highlight and practical tips:

Example Trattoria [0] (4.6★ (1,250) · 123 W Example St · $$$) मोमबत्ती की रोशनी वाला, निजी डाइनिंग रूम. समीक्षा करने वाले लोगों के मुताबिक, यह रोमैंटिक है, लेकिन वीकेंड पर यहां शोर-शराबा होता है. यहां के खास पकवानों में टालियाटेले अल रागु, बुराटा, और तिरामिसू शामिल हैं. यहां आने से पहले बुकिंग करने का सुझाव दिया जाता है. शुक्रवार और शनिवार की शाम को, बिना बुकिंग के आने वाले लोगों को 30 से 45 मिनट तक इंतज़ार करना पड़ सकता है. साथ ही, सड़क के किनारे पार्किंग की सुविधा सीमित है.

जवाब

जवाब में ये फ़ील्ड शामिल होते हैं:

  • summary: खोज के नतीजों की नैचुरल लैंग्वेज में खास जानकारी. इसमें शून्य से शुरू होने वाले उद्धरण हो सकते हैं, जैसे कि [0], जो places में मौजूद एंट्री पर मैप होते हैं.
  • places[]: खास जानकारी में बताई गई जगहें. हर जगह के लिए ये जानकारी शामिल होती है:
    • place: जगह के संसाधन का नाम, places/{id} फ़ॉर्मैट में.
    • id: जगह का आईडी. इसे Google Maps Platform के अन्य एपीआई के साथ इस्तेमाल किया जा सकता है. जैसे, किसी जगह को मैप पर दिखाने के लिए.
    • location: जगह के अक्षांश/देशांतर निर्देशांक.
    • googleMapsLinks: Google Maps में किसी जगह पर ले जाने वाले लिंक (placeUrl), निर्देश (directionsUrl), समीक्षाएं (reviewsUrl), फ़ोटो (photosUrl), और समीक्षा लिखने की सुविधा (writeAReviewUrl).
    • attribution: वह एट्रिब्यूशन जो आपको जगह के साथ दिखाना होगा. जानकारी के स्रोत से जुड़ी ज़रूरी शर्तें देखें.
  • contentToken: यह एक एजेंटिक डेटा विज़ुअलाइज़ेशन टोकन (झलक) है. इसकी मदद से, जवाब में जगहों की जानकारी को जगहों की जानकारी देने वाली यूआई किट के साथ दिखाया जा सकता है. इसके लिए, आपको कोई अलग से शुल्क नहीं देना होगा. यह तब दिखता है, जब जवाब में कम से कम एक जगह शामिल हो.

SKU, एमसीपी, और REST, तीनों के लिए जवाब का स्ट्रक्चर एक जैसा होता है. फ़ील्ड की जानकारी के लिए, search_places रेफ़रंस देखें.

बिलिंग और कोटा

search_places के हर अनुरोध के लिए शुल्क लिया जाता है:

  • जिस अनुरोध में Pro के किसी भी विकल्प का इस्तेमाल नहीं किया जाता है उसका बिल, Maps Grounding Essentials SKU के तहत जनरेट किया जाता है.
  • Pro विकल्प का इस्तेमाल करने वाले अनुरोध के लिए, Maps Grounding Pro SKU के तहत बिल भेजा जाता है. एक ही अनुरोध में दोनों विकल्पों का इस्तेमाल करने पर, शुल्क में कोई बदलाव नहीं होता. Pro प्लान की क़ीमत जानने के लिए, Essentials, Pro, और Google Maps से जानकारी लेने की सुविधा की तुलना करना लेख पढ़ें.

अगर जगहों की जानकारी देने वाली यूआई किट की मदद से, search_places के रिस्पॉन्स में मिली जगहों की जानकारी दिखाई जाती है, तो एजेंटिक डेटा विज़ुअलाइज़ेशन टोकन (झलक) का इस्तेमाल किया जा सकता है. इससे जगहों की जानकारी देने वाली यूआई किट के उन अनुरोधों के लिए शुल्क नहीं लिया जाएगा.

search_places के लिए, हर प्रोजेक्ट के लिए हर मिनट 300 क्वेरी का कोटा होता है. इसे दोनों SKU शेयर करते हैं. कीमत जानने के लिए, कीमत की मुख्य टेबल और भारत के लिए कीमत की टेबल देखें.