MCP Tools Reference: mapstools.googleapis.com

टूल: resolve_names

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

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

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

    • हर क्वेरी ऑब्जेक्ट में ये चीज़ें होनी चाहिए:
      • text (स्ट्रिंग - ज़रूरी है): टेक्स्ट क्वेरी, जिसमें किसी जगह का नाम या पता शामिल होता है.
        • उदाहरण: '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) का इस्तेमाल करके, नतीजों को बायस किया जा सकता है.

टूल कॉल के लिए निर्देश:

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

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

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

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

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

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

Curl अनुरोध 
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, दोनों की वैल्यू दी गई हैं, तो location_bias को region_code से ज़्यादा प्राथमिकता दी जाती है.
regionCode

string

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

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

LocationQuery

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

string

ज़रूरी है. Google Maps पर किसी खास जियोस्पेशल इकाई, जैसे कि कोई जगह या पता ढूंढने के लिए टेक्स्ट क्वेरी. क्वेरी जितनी सटीक होगी, समस्या का समाधान उतना ही सटीक होगा. उदाहरण के लिए, "San Francisco", "Googleplex, Mountain View, CA", "1600 Amphitheatre Parkway, Mountain View, CA" या "Eiffel Tower, Paris". क्वेरी में किसी खास पते या जगह का नाम होना चाहिए. किसी चेन के नाम (जैसे, 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: अगर इसकी वैल्यू true है, तो टूल अपने एनवायरमेंट में बदलाव नहीं करता. डिफ़ॉल्ट: false.
  • destructiveHint: अगर इसकी वैल्यू true है, तो टूल नुकसान पहुंचाने वाली कार्रवाइयां कर सकता है. अगर यह वैल्यू false पर सेट है, तो टूल सिर्फ़ जोड़ने वाली कार्रवाइयां कर सकता है. डिफ़ॉल्ट: true.
  • idempotentHint: अगर इसकी वैल्यू true है, तो टूल को एक ही आर्ग्युमेंट के साथ बार-बार कॉल करने पर, उसके एनवायरमेंट पर कोई और असर नहीं पड़ेगा. डिफ़ॉल्ट: false.
  • openWorldHint: सही होने पर, टूल बाहरी इकाइयों की 'विशाल दुनिया' के साथ इंटरैक्ट कर सकता है. अगर यह वैल्यू false है, तो टूल सिर्फ़ इंटरनल इकाइयों के साथ इंटरैक्ट कर सकता है. उदाहरण के लिए, वेब सर्च टूल ओपन वर्ल्ड होगा, जबकि मेमोरी टूल ओपन वर्ल्ड नहीं होगा.

Destructive Hint: ❌ | Idempotent Hint: ❌ | Read Only Hint: ✅ | Open World Hint: ❌