MCP Tools Reference: mapstools.googleapis.com

टूल: resolve_names

यह फ़ंक्शन, किसी खास जगह के बारे में की गई क्वेरी (लैंडमार्क के नाम या सटीक पते) की बैच सूची को Google Maps के कैननिकल प्लेस आईडी में बदलता है.

इनपुट से जुड़ी ज़रूरी शर्तें (अहम):

  1. queries (ऑब्जेक्ट का ऐरे - ज़रूरी है): जगह की जानकारी से जुड़ी क्वेरी की सूची. ज़्यादा से ज़्यादा 20 क्वेरी दी जा सकती हैं.

    • हर क्वेरी ऑब्जेक्ट में ये चीज़ें होनी चाहिए:
      • text (string - ज़रूरी है): यह टेक्स्ट क्वेरी, किसी जगह के नाम या पते को दिखाती है.
        • उदाहरण: 'Googleplex, Mountain View, CA', '1600 Amphitheatre Pkwy, Mountain View, CA', 'Eiffel Tower, Paris'.

  2. location_bias (object - OPTIONAL): इसका इस्तेमाल, किसी खास भौगोलिक जगह के आस-पास के नतीजों को प्राथमिकता देने के लिए करें.

    • फ़ॉर्मैट: {"viewport": {"low": {"latitude": [value], "longitude": [value]}, "high": {"latitude": [value], "longitude": [value]}}}

  3. region_code (स्ट्रिंग - ज़रूरी नहीं है): यह उपयोगकर्ता के लिए यूनिकोड सीएलडीआर रीजन कोड (दो अक्षरों वाला देश का कोड, जैसे कि US, CA) होता है, ताकि खोज के नतीजों को पक्षपात रहित बनाया जा सके.

Instructions for Tool Call:

  • जगह की जानकारी (ज़रूरी): क्वेरी में किसी जगह का नाम या पता होना चाहिए. 'restaurants' जैसे सामान्य खोज या 'Starbucks' जैसे चेन के नाम इस्तेमाल नहीं किए जा सकते.
  • अगर आपको जिन डाउनस्ट्रीम टूल का इस्तेमाल करना है वे पहले से ही पते या जगह के नाम की स्ट्रिंग को सीधे तौर पर स्वीकार करते हैं, तो इस टूल को कॉल न करें.

Google Maps में सेव करें:

  • जवाब में save_to_maps_url फ़ील्ड शामिल होता है: यह एक Google Maps लिंक होता है, जिसमें सभी जगहों की जानकारी होती है.
  • जब उपयोगकर्ता को Google Maps में, हल की गई जगहों को सूची के तौर पर सेव करना, शेयर करना या खोलना हो, तब उसे यह लिंक दिखाएं. इस लिंक को खुद न बनाएं.

गड़बड़ी ठीक करना (CRITICAL):

  • यह एक बैच प्रोसेसिंग टूल है. ऐसा हो सकता है कि किसी अनुरोध के "मिश्रित नतीजे" मिलें. उदाहरण के लिए, कुछ क्वेरी के नतीजे मिल जाएं, जबकि अन्य के न मिलें.
  • results की आउटपुट सूची, queries के इंडेक्स के साथ 1:1 मैप होती है. क्वेरी के पूरा न होने पर, results सूची में मौजूद क्वेरी के इंडेक्स में, Result मैसेज (कोई entity सेट नहीं है) दिखेगा.
  • आपको जवाब में मौजूद failed_requests मैप फ़ील्ड की जांच ज़रूर करनी चाहिए, ताकि यह पता चल सके कि इंडेक्स करने के दौरान किस क्वेरी में गड़बड़ी हुई है. failed_requests की वैल्यू, अनुरोध में मौजूद उस क्वेरी का इंडेक्स दिखाती है जिसे पूरा नहीं किया जा सका. यह इंडेक्स, 0 से शुरू होता है. कुछ कॉल में गड़बड़ी होने की वजह से, यह न मान लें कि बैच में मौजूद सभी कॉल में गड़बड़ी हुई है.

यहां दिए गए कोड सैंपल में, curl का इस्तेमाल करके resolve_names एमसीपी टूल को कॉल करने का तरीका बताया गया है.

कर्ल अनुरोध 
curl --location 'https://mapstools.googleapis.com/mcp' \
--header 'content-type: application/json' \
--header 'accept: application/json, text/event-stream' \
--data '{
  "method": "tools/call",
  "params": {
    "name": "resolve_names",
    "arguments": {
      // Provide these details according to the MCP tool specification.
    }
  },
  "jsonrpc": "2.0",
  "id": 1
}'

इनपुट स्कीमा

ResolveNames के लिए अनुरोध मैसेज.

ResolveNamesRequest

JSON के काेड में दिखाना 
{
  "queries": [
    {
      object (LocationQuery)
    }
  ],
  "locationBias": {
    object (LocationBias)
  },
  "regionCode": string
}
फ़ील्ड
queries[]

object (LocationQuery)

ज़रूरी है. जगह की जानकारी से जुड़ी क्वेरी की सूची, जिन्हें हल करना है. ज़्यादा से ज़्यादा 20 क्वेरी दी जा सकती हैं.
locationBias

object (LocationBias)

ज़रूरी नहीं. यह एक वैकल्पिक क्षेत्र है, जिसका इस्तेमाल रिज़ॉल्यूशन के नतीजों को बेहतर बनाने के लिए किया जाता है. अगर यह तय किया गया है, तो नतीजे उन इकाइयों के हिसाब से तय किए जाएंगे जो इस इलाके के आस-पास हैं. location_bias या region_code को शामिल करने से, खोज के दायरे को सीमित किया जा सकता है. इससे अक्सर बेहतर नतीजे मिलते हैं.

अगर location_bias और region_code, दोनों को सेट किया गया है, तो region_code के मुकाबले location_bias को प्राथमिकता दी जाती है.
regionCode

string

ज़रूरी नहीं. यह एक वैकल्पिक क्षेत्र कोड है. इसका इस्तेमाल, रिज़ॉल्यूशन के नतीजों को बेहतर बनाने के लिए किया जाता है. अगर कोई क्षेत्र तय किया गया है, तो समाधान के नतीजे उन इकाइयों के पक्ष में होंगे जो तय किए गए क्षेत्र में हैं या उसके आस-पास हैं. यह CLDR क्षेत्र का कोड होना चाहिए. उदाहरण के लिए, "US" या "CA". location_bias या region_code को शामिल करने से, खोज के दायरे को सीमित किया जा सकता है. इससे अक्सर बेहतर नतीजे मिलते हैं.

अगर location_bias और region_code, दोनों को सेट किया गया है, तो region_code के मुकाबले location_bias को प्राथमिकता दी जाती है.

LocationQuery

JSON के काेड में दिखाना 
{
  "text": string
}
फ़ील्ड
text

string

ज़रूरी है. Google Maps पर किसी खास भू-स्थानिक इकाई, जैसे कि कोई जगह या पता को हल करने के लिए टेक्स्ट क्वेरी. क्वेरी जितनी सटीक होगी, समस्या का समाधान उतना ही सटीक होगा. उदाहरण के लिए, "सैन फ़्रांसिस्को", "Googleplex, Mountain View, CA", "1600 Amphitheatre Parkway, Mountain View, CA" या "एफ़िल टावर, पैरिस". क्वेरी में किसी जगह का नाम या पता होना चाहिए. चेन का नाम (जैसे, Starbucks) या "रेस्टोरेंट" जैसी खोज क्वेरी के तौर पर सामान्य जगहों के नाम इस्तेमाल नहीं किए जा सकते.

LocationBias

JSON के काेड में दिखाना 
{

  // Union field type can be only one of the following:
  "viewport": {
    object (Viewport)
  }
  // End of list of possible types for union field type.
}
फ़ील्ड
यूनियन फ़ील्ड type. जगह के हिसाब से खोज के नतीजों में बदलाव करने की सुविधा का टाइप. type इनमें से सिर्फ़ एक हो सकता है:
viewport

object (Viewport)

बाउंडिंग बॉक्स से तय किया गया व्यूपोर्ट.

व्यूपोर्ट

JSON के काेड में दिखाना 
{
  "low": {
    object (LatLng)
  },
  "high": {
    object (LatLng)
  }
}
फ़ील्ड
low

object (LatLng)

ज़रूरी है. व्यूपोर्ट का सबसे निचला पॉइंट.
high

object (LatLng)

ज़रूरी है. व्यूपोर्ट का सबसे ऊपरी हिस्सा.

LatLng

JSON के काेड में दिखाना 
{
  "latitude": number,
  "longitude": number
}
फ़ील्ड
latitude

number

डिग्री में अक्षांश. यह [-90.0, +90.0] की रेंज में होना चाहिए.
longitude

number

डिग्री में देशांतर. यह [-180.0, +180.0] की रेंज में होना चाहिए.

आउटपुट स्कीमा

ResolveNames के लिए जवाब का मैसेज.

ResolveNamesResponse

JSON के काेड में दिखाना 
{
  "results": [
    {
      object (Result)
    }
  ],
  "failedRequests": {
    integer: {
      object (Status)
    },
    ...
  },
  "saveToMapsUrl": string
}
फ़ील्ड
results[]

object (Result)

सिर्फ़ आउटपुट के लिए. जगह की जानकारी से जुड़ी क्वेरी से हल की गई इकाइयों की सूची. इस बात की गारंटी है कि यह अनुरोध queries इंडेक्स के साथ 1:1 मैप करेगा. इंडेक्स i पर मौजूद खाली स्ट्रिंग से पता चलता है कि उस क्वेरी के लिए रिज़ॉल्यूशन पूरा नहीं हुआ. अगर रिज़ॉल्यूशन फ़ेल हो जाता है, तो कृपया गड़बड़ी की स्थिति के लिए failed_requests फ़ील्ड देखें.
failedRequests

map (key: integer, value: object (Status))

सिर्फ़ आउटपुट के लिए. इस मैप में, कुछ फ़ाइलों का फ़ॉर्मैट नहीं बदले जाने की जानकारी दी गई है. कुंजी, queries फ़ील्ड में मौजूद उस अनुरोध का इंडेक्स है जिसे पूरा नहीं किया जा सका. यह वैल्यू, गड़बड़ी की स्थिति के बारे में बताती है. इससे पता चलता है कि समस्या हल क्यों नहीं हुई.

एक ऑब्जेक्ट, जिसमें "key": value जोड़े की सूची शामिल होती है. उदाहरण: { "name": "wrench", "mass": "1.3kg", "count": "3" }.
saveToMapsUrl

string

सिर्फ़ आउटपुट के लिए. Google Maps में, ठीक की गई सभी इकाइयों को सेव करने का लिंक.

नतीजा

JSON के काेड में दिखाना 
{
  "entity": {
    object (Entity)
  },
  "confidence": enum (Confidence)
}
फ़ील्ड
entity

object (Entity)

सिर्फ़ आउटपुट के लिए. जगह की जानकारी से जुड़ी क्वेरी से मिली इकाई.
confidence

enum (Confidence)

सिर्फ़ आउटपुट के लिए. रिज़ॉल्यूशन के लिए कॉन्फ़िडेंस लेवल.

इकाई

JSON के काेड में दिखाना 
{

  // Union field entity can be only one of the following:
  "place": string
  // End of list of possible types for union field entity.
}
फ़ील्ड
यूनियन फ़ील्ड entity. हल की गई इकाई का टाइप. entity इनमें से सिर्फ़ एक हो सकता है:
place

string

हल की गई जगह का संसाधन नाम.

FailedRequestsEntry

JSON के काेड में दिखाना 
{
  "key": integer,
  "value": {
    object (Status)
  }
}
फ़ील्ड
key

integer
value

object (Status)

स्थिति

JSON के काेड में दिखाना 
{
  "code": integer,
  "message": string,
  "details": [
    {
      "@type": string,
      field1: ...,
      ...
    }
  ]
}
फ़ील्ड
code

integer

स्टेटस कोड, जो google.rpc.Code की enum वैल्यू होनी चाहिए.
message

string

डेवलपर को दिखने वाला गड़बड़ी का मैसेज, जो अंग्रेज़ी में होना चाहिए. उपयोगकर्ता को दिखने वाली गड़बड़ी के किसी भी मैसेज को स्थानीय भाषा में होना चाहिए. साथ ही, उसे google.rpc.Status.details फ़ील्ड में भेजा जाना चाहिए या क्लाइंट की ओर से स्थानीय भाषा में होना चाहिए.
details[]

object

मैसेज की सूची, जिसमें गड़बड़ी की जानकारी होती है. एपीआई के इस्तेमाल के लिए, मैसेज टाइप का एक सामान्य सेट होता है.

एक ऑब्जेक्ट, जिसमें आर्बिट्ररी टाइप के अलग-अलग फ़ील्ड शामिल हों. एक ऐसा अतिरिक्त फ़ील्ड "@type" जिसमें टाइप की पहचान करने वाला यूआरआई हो. उदाहरण: { "id": 1234, "@type": "types.example.com/standard/id" }.

कोई भी

JSON के काेड में दिखाना 
{
  "typeUrl": string,
  "value": string
}
फ़ील्ड
typeUrl

string

यह फ़ील्ड, क्रम से लगाए गए Protobuf मैसेज के टाइप की पहचान करता है. इसमें यूआरआई रेफ़रंस होता है. इसमें स्लैश पर खत्म होने वाला प्रीफ़िक्स और पूरी तरह से क्वालिफ़ाइड टाइप का नाम होता है.

उदाहरण: type.googleapis.com/google.protobuf.StringValue

इस स्ट्रिंग में कम से कम एक / वर्ण होना चाहिए. साथ ही, आखिरी / के बाद का कॉन्टेंट, कैननिकल फ़ॉर्म में टाइप का पूरा नाम होना चाहिए. इसमें शुरुआती बिंदु नहीं होना चाहिए. इन यूआरआई रेफ़रंस पर कोई स्कीम न लिखें, ताकि क्लाइंट उनसे संपर्क न कर पाएं.

प्रीफ़िक्स कोई भी हो सकता है. Protobuf लागू करने वाले लोगों से उम्मीद की जाती है कि वे टाइप की पहचान करने के लिए, आखिरी / तक के सभी वर्ण हटा दें. type.googleapis.com/ एक सामान्य डिफ़ॉल्ट प्रीफ़िक्स है, जिसकी ज़रूरत कुछ लेगसी वर्शन को होती है. इस प्रीफ़िक्स से टाइप के ऑरिजिन का पता नहीं चलता. साथ ही, इसमें शामिल यूआरआई से किसी भी अनुरोध का जवाब नहीं मिलता.

सभी टाइप यूआरएल स्ट्रिंग, मान्य यूआरआई रेफ़रंस होने चाहिए. साथ ही, टेक्स्ट फ़ॉर्मैट के लिए यह ज़रूरी है कि रेफ़रंस के कॉन्टेंट में सिर्फ़ अक्षर, अंक, प्रतिशत के तौर पर कोड किए गए एस्केप, और यहां दिए गए सेट के वर्ण शामिल हों (बाहरी बैकटिक शामिल नहीं हैं): /-.~_!$&()*+,;=. हम प्रतिशत के हिसाब से एन्कोडिंग की अनुमति देते हैं. हालांकि, लागू करने के दौरान उन्हें अनएस्केप नहीं किया जाना चाहिए, ताकि मौजूदा पार्सर के साथ कोई भ्रम न हो. उदाहरण के लिए, type.googleapis.com%2FFoo को अस्वीकार कर दिया जाना चाहिए.

Any के ओरिजनल डिज़ाइन में, इन टाइप यूआरएल पर टाइप रिज़ॉल्यूशन सेवा लॉन्च करने की संभावना पर विचार किया गया था. हालांकि, Protobuf ने कभी भी इसे लागू नहीं किया. साथ ही, इन यूआरएल से संपर्क करने को समस्या और सुरक्षा से जुड़ी संभावित समस्या माना जाता है. टाइप यूआरएल से संपर्क करने की कोशिश न करें.
value

string (bytes format)

इसमें type_url में बताए गए टाइप का Protobuf सीरियलाइज़ेशन होता है.

base64 कोड में बदली गई स्ट्रिंग.

आत्मविश्वास

रिज़ॉल्यूशन के लिए कॉन्फ़िडेंस लेवल.

Enums
CONFIDENCE_UNSPECIFIED डिफ़ॉल्ट मान. इस वैल्यू का इस्तेमाल नहीं किया गया है.
MEDIUM मीडियम कॉन्फ़िडेंस का मतलब है कि समस्या का समाधान सही हो सकता है, लेकिन अन्य समाधान भी उपलब्ध हो सकते हैं.
HIGH ज़्यादा कॉन्फ़िडेंस का मतलब है कि रिज़ॉल्यूशन सही है और यह किसी खास जियोस्पेशल इकाई (जैसे, कोई खास जगह) को दिखाता है.

टूल एनोटेशन

टूल के एनोटेशन, एमसीपी क्लाइंट को भेजे जाते हैं. इनसे किसी टूल से जुड़े बुनियादी जोखिम के बारे में जानकारी मिलती है. ज़्यादातर क्लाइंट, इन संकेतों को भरोसेमंद नहीं मानते. हालांकि, इनका इस्तेमाल यह तय करने के लिए किया जा सकता है कि उपयोगकर्ता को पुष्टि करने का प्रॉम्प्ट कब भेजा जाए.

टाइटल स्ट्रिंग के साथ-साथ, यहां दिए गए बूलियन हिंट भी तय किए गए हैं:

  • readOnlyHint: अगर यह सही है, तो टूल अपने एनवायरमेंट में बदलाव नहीं करता है. डिफ़ॉल्ट: गलत.
  • destructiveHint: अगर यह वैल्यू 'सही है' पर सेट है, तो टूल, डेटा को मिटाने जैसी कार्रवाइयां कर सकता है. अगर यह वैल्यू 'गलत है' पर सेट है, तो टूल सिर्फ़ जोड़ने वाली कार्रवाइयां कर सकता है. डिफ़ॉल्ट: सही.
  • idempotentHint: अगर यह वैल्यू सही है, तो एक ही आर्ग्युमेंट के साथ टूल को बार-बार कॉल करने से, इसके एनवायरमेंट पर कोई अतिरिक्त असर नहीं पड़ेगा. डिफ़ॉल्ट: गलत.
  • openWorldHint: अगर यह वैल्यू सही है, तो टूल बाहरी इकाइयों के 'ओपन वर्ल्ड' के साथ इंटरैक्ट कर सकता है. अगर यह वैल्यू 'गलत है' पर सेट है, तो टूल सिर्फ़ इंटरनल इकाइयों के साथ इंटरैक्ट कर सकता है. उदाहरण के लिए, वेब पर खोज करने वाला टूल ओपन वर्ल्ड होगा, जबकि मेमोरी टूल ओपन वर्ल्ड नहीं होगा.

बदलाव करने वाला सुराग: ❌ | एक ही बार इस्तेमाल किया जा सकने वाला सुराग: ❌ | सिर्फ़ पढ़ने वाला सुराग: ✅ | ओपन वर्ल्ड सुराग: ❌