Maps Tools Resolution API

Maps Tools Resolution API, Maps Experience agent tools (पहले Maps Grounding Lite) का हिस्सा है. यह बैच एंडपॉइंट उपलब्ध कराता है. ये एंडपॉइंट, जगहों के नाम और Google Maps के यूआरएल को Google Maps पर मौजूद जगहों के आईडी में बदल देते हैं. नतीजे में मिले जगह के आईडी को Google Maps Platform के अन्य एपीआई के साथ इस्तेमाल किया जा सकता है. हर जवाब में एक लिंक भी शामिल होता है. इस लिंक की मदद से, सुझाई गई जगहों को Google Maps में एक सूची के तौर पर सेव किया जा सकता है.

Resolution API, REST मेथड और Maps Experience एजेंट टूल के एमसीपी सर्वर पर टूल, दोनों के तौर पर उपलब्ध है:

शुरू करने से पहले

Resolution API का इस्तेमाल करने के लिए, आपके पास एक ऐसा Google Cloud प्रोजेक्ट होना चाहिए जिसमें बिलिंग की सुविधा चालू हो. साथ ही, Maps Experience agent tools एपीआई सेवा चालू हो. निर्देशों के लिए, अपने Google Cloud प्रोजेक्ट पर Maps Experience एजेंट टूल चालू करना लेख पढ़ें.

एपीआई का ऐक्सेस और पुष्टि करना

Resolution API, एपीआई पासकोड और OAuth 2.0 क्रेडेंशियल, दोनों के साथ काम करता है.

एपीआई पासकोड

X-Goog-Api-Key हेडर में Google Maps Platform का मान्य एपीआई पासकोड डालकर या उसे अनुरोध के यूआरएल में जोड़कर, अनुरोधों की पुष्टि की जा सकती है:

https://mapstools.googleapis.com/v1:resolveNames?key=API_KEY

इस पेज पर दिए गए उदाहरणों में, API_KEY को अपने एपीआई पासकोड से बदलें.

OAuth 2.0 के दायरे

OAuth की अनुमति का इस्तेमाल करने पर, यह स्कोप काम करता है:

• https://www.googleapis.com/auth/maps-platform.mapstools

इस्तेमाल करने की सीमाएं

Resolution API के लिए, ये डिफ़ॉल्ट कोटा लागू होते हैं:

• ResolveNames: हर प्रोजेक्ट के लिए, हर मिनट 600 क्वेरी.
• ResolveMapsUrls: हर प्रोजेक्ट के लिए, हर मिनट 600 क्वेरी.
• बैच का साइज़: हर अनुरोध में ज़्यादा से ज़्यादा 20 क्वेरी या यूआरएल शामिल किए जा सकते हैं.

हर अनुरोध को एक क्वेरी के तौर पर गिना जाता है. इससे कोई फ़र्क़ नहीं पड़ता कि उसमें कितने आइटम शामिल हैं.

कीमत

ResolveNames और ResolveMapsUrls के अनुरोधों के लिए, Places API Text Search Essentials (IDs Only) SKU के तहत कोई शुल्क नहीं लिया जाता. Maps Experience एजेंट के अन्य टूल की तरह ही, आपके प्रोजेक्ट के लिए बिलिंग खाता होना ज़रूरी है.

अनुरोध की पुष्टि और पाबंदियां

बैच अनुरोधों की पुष्टि इन नियमों के आधार पर की जाती है, ताकि ज़्यादा लोड न पड़े और तेज़ी से जवाब मिल सके:

• बैच साइज़ की सीमा: दोनों तरीकों में, हर अनुरोध में ज़्यादा से ज़्यादा 20 आइटम शामिल किए जा सकते हैं.
• ResolveNames के लिए ज़रूरी शर्तें:
  • queries में मौजूद हर आइटम के लिए, text पैरामीटर की वैल्यू देना ज़रूरी है. यह वैल्यू खाली नहीं होनी चाहिए.
  • क्वेरी में किसी जगह का नाम या पता होना चाहिए. जैसे, "Googleplex, Mountain View, CA" या "Eiffel Tower, Paris".
  • कैटगरी के हिसाब से की जाने वाली सामान्य खोजें, जैसे कि "restaurants in New York" या जगह की जानकारी के बिना चेन के सामान्य नाम, जैसे कि "Starbucks", इस्तेमाल नहीं किए जा सकते. साथ ही, हो सकता है कि इनसे सही नतीजे न मिलें.
• ResolveMapsUrls के लिए ज़रूरी शर्तें:
  • हर यूआरएल, Google Maps का मान्य यूआरएल होना चाहिए.
  • इन फ़ॉर्मैट में फ़ाइलें अपलोड की जा सकती हैं:
    • जगह का स्टैंडर्ड यूआरएल: https://www.google.com/maps/place/...
    • छोटा किया गया यूआरएल: https://maps.app.goo.gl/...
  • क्वेरी पर आधारित सामान्य Maps यूआरएल, जैसे कि https://maps.google.com/?q=restaurant और किसी एक यूनीक जगह पर न ले जाने वाले यूआरएल का इस्तेमाल नहीं किया जा सकता.

पहचानी गई जगहों की जानकारी को Google Maps में सेव करना

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

एपीआई से मिले लिंक का ही इस्तेमाल करें. लिंक खुद न बनाएं. अगर बैच में मौजूद किसी भी आइटम की समस्या हल नहीं होती है, तो जवाब में saveToMapsUrl शामिल नहीं होता है.

कुछ गड़बड़ियों को ठीक करना

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

जवाब को समझना

1. 1:1 अलाइनमेंट की गारंटी: लौटाई गई results सूची (ResolveNames के लिए) या entities सूची (ResolveMapsUrls के लिए), इंडेक्स के हिसाब से इनपुट सूची के साथ 1:1 मैप करती है.
2. फ़ेलियर के लिए खाली एलिमेंट: अगर इंडेक्स i पर मौजूद आइटम को रिज़ॉल्व नहीं किया जा सका, तो नतीजे की सूची में इंडेक्स i पर एक खाली ऑब्जेक्ट {} शामिल होता है.
3. failedRequests मैप: जवाब में failedRequests मैप शामिल है.
   • कुंजी, उस आइटम का 0-आधारित इंडेक्स है जो अपलोड नहीं हो पाया. इसे JSON में स्ट्रिंग के तौर पर दिखाया जाता है.
   • वैल्यू एक google.rpc.Status ऑब्जेक्ट है, जिसमें गड़बड़ी का कोड और आइटम के फ़ेल होने की वजह बताने वाला मैसेज शामिल होता है.
4. saveToMapsUrl में सिर्फ़ सफल कार्रवाइयां शामिल हैं: saveToMapsUrl लिंक में सिर्फ़ वे आइटम शामिल हैं जिनकी समस्या हल हो गई है. इसमें वे आइटम शामिल नहीं होते हैं जिन्हें इंपोर्ट नहीं किया जा सका.

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

हर आइटम से जुड़ी गड़बड़ियां

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

सिर्फ़ उन आइटम को फिर से इंपोर्ट करें जो INTERNAL की वजह से इंपोर्ट नहीं हो पाए.

टॉप-लेवल की गड़बड़ियां

इन मामलों में, एपीआई अधूरे जवाब के बजाय टॉप-लेवल की गड़बड़ी दिखाता है:

• अमान्य अनुरोध (400 INVALID_ARGUMENT): अनुरोध में 20 से ज़्यादा आइटम हैं, ResolveNames अनुरोध में कोई क्वेरी नहीं है या किसी क्वेरी में text वैल्यू खाली है या ResolveMapsUrls अनुरोध में कोई ऐसा यूआरएल है जो खाली है या सिंटैक्स के हिसाब से मान्य यूआरएल नहीं है. एक अमान्य आइटम की वजह से, पूरा अनुरोध अस्वीकार हो जाता है.
• पुष्टि करने, अनुमति देने या कोटा से जुड़ी गड़बड़ियां: उदाहरण के लिए, एपीआई पासकोड मौजूद नहीं है या अमान्य है या अनुरोध, इस्तेमाल करने की सीमाओं से ज़्यादा है.
• सर्वर की गड़बड़ियां (500 INTERNAL): अनुरोध फिर से करें.

एमसीपी के साथ रिज़ॉल्यूशन एपीआई का इस्तेमाल करना

https://mapstools.googleapis.com/mcp पर मौजूद Maps Experience एजेंट टूल का एमसीपी सर्वर, Resolution API को दो टूल के तौर पर दिखाता है:

• resolve_names: यह जगह के नाम या पतों के बैच को जगह के आईडी में बदलता है.
• resolve_maps_urls: यह Google Maps के यूआरएल के बैच को जगह के आईडी में बदलता है.

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

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

इस उदाहरण में, resolve_names टूल को सीधे कॉल करने के लिए curl का इस्तेमाल किया गया है:

curl --location 'https://mapstools.googleapis.com/mcp' \
--header 'content-type: application/json' \
--header 'accept: application/json, text/event-stream' \
--header 'X-Goog-Api-Key: API_KEY' \
--data '{
  "method": "tools/call",
  "params": {
    "name": "resolve_names",
    "arguments": {
      "queries": [
        { "text": "Googleplex, Mountain View, CA" },
        { "text": "Eiffel Tower, Paris" }
      ]
    }
  },
  "jsonrpc": "2.0",
  "id": 1
}'

resolve_maps_urls को कॉल करने के लिए, name को resolve_maps_urls पर सेट करें और arguments में urls कलेक्शन पास करें.

REST API की खास जानकारी और curl के उदाहरण

ResolveNames

तरीका: POST

https://mapstools.googleapis.com/v1:resolveNames

अनुरोध के मुख्य हिस्से का फ़ॉर्मैट

{
  "queries": [
    { "text": "string" }
  ],
  "locationBias": {
    "viewport": {
      "low": { "latitude": number, "longitude": number },
      "high": { "latitude": number, "longitude": number }
    }
  },
  "regionCode": "string"
}

• queries (ज़रूरी है): हल की जाने वाली क्वेरी की सूची (ज़्यादा से ज़्यादा 20).
• locationBias (ज़रूरी नहीं): व्यूपोर्ट बाउंडिंग बॉक्स, ताकि नतीजों को स्थानीय इलाके के हिसाब से दिखाया जा सके.
• regionCode (ज़रूरी नहीं): नतीजों को बायस करने के लिए, देश का CLDR कोड (उदाहरण के लिए, "US" या "FR").

Curl का उदाहरण: समस्या हल हो गई

इस क्वेरी से "Googleplex" और "आइफ़िल टावर" के बारे में जानकारी मिलती है.

curl -X POST \
-H "Content-Type: application/json" \
-d '{
  "queries": [
    { "text": "Googleplex, Mountain View, CA" },
    { "text": "Eiffel Tower, Paris" }
  ]
}' \
"https://mapstools.googleapis.com/v1:resolveNames?key=API_KEY"

JSON का रिस्पॉन्स

{
  "results": [
    {
      "entity": {
        "place": "places/ChIJj61dQgK6j4AR4GeTYWZsKWw"
      },
      "confidence": "HIGH"
    },
    {
      "entity": {
        "place": "places/ChIJLU7jZClu5kcR4PcOOO6p3I0"
      },
      "confidence": "HIGH"
    }
  ],
  "saveToMapsUrl": "https://www.google.com/maps/@?api=1&map_action=shortlist&place_ids=ChIJj61dQgK6j4AR4GeTYWZsKWw,ChIJLU7jZClu5kcR4PcOOO6p3I0"
}

Curl का उदाहरण: मिले-जुले नतीजे (कुछ हद तक गड़बड़ी)

इस उदाहरण में, पहला आइटम ऐसा टेक्स्ट है जिसे रिज़ॉल्व नहीं किया जा सकता. वहीं, दूसरा आइटम एक मान्य जगह है.

curl -X POST \
-H "Content-Type: application/json" \
-d '{
  "queries": [
    { "text": "This is not a real place name at all 123456789" },
    { "text": "Eiffel Tower, Paris" }
  ]
}' \
"https://mapstools.googleapis.com/v1:resolveNames?key=API_KEY"

JSON का रिस्पॉन्स

{
  "results": [
    {},
    {
      "entity": {
        "place": "places/ChIJLU7jZClu5kcR4PcOOO6p3I0"
      },
      "confidence": "HIGH"
    }
  ],
  "failedRequests": {
    "0": {
      "code": 5,
      "message": "Place not found."
    }
  },
  "saveToMapsUrl": "https://www.google.com/maps/@?api=1&map_action=shortlist&place_ids=ChIJLU7jZClu5kcR4PcOOO6p3I0"
}

ResolveMapsUrls

तरीका: POST

https://mapstools.googleapis.com/v1:resolveMapsUrls

अनुरोध के मुख्य हिस्से का फ़ॉर्मैट

{
  "urls": [
    "string"
  ]
}

• urls (ज़रूरी है): Google Maps के यूआरएल स्ट्रिंग की सूची, जिसे रिज़ॉल्व करना है. इसमें ज़्यादा से ज़्यादा 20 यूआरएल शामिल किए जा सकते हैं.

Curl का उदाहरण: समस्या हल हो गई

यहां दिए गए उदाहरण में, Google Maps पर मौजूद किसी जगह के स्टैंडर्ड यूआरएल को रिज़ॉल्व किया गया है:

curl -X POST \
-H "Content-Type: application/json" \
-d '{
"urls": [
"https://www.google.com/maps/place/Googleplex/@37.4220041,-122.0862515,17z/data=!3m1!4b1!4m6!3m5!1s0x808fba02425dad8f:0x6c296c66619367e0!8m2!3d37.4219998!4d-122.0840575!16s%2Fg%2F11c8b0ssp6"
]
}' \
"https://mapstools.googleapis.com/v1:resolveMapsUrls?key=API_KEY"

JSON का रिस्पॉन्स

{
  "entities": [
    {
      "place": "places/ChIJj61dQgK6j4AR4GeTYWZsKWw"
    }
  ],
  "saveToMapsUrl": "https://www.google.com/maps/@?api=1&map_action=shortlist&place_ids=ChIJj61dQgK6j4AR4GeTYWZsKWw"
}

Curl का उदाहरण: मिले-जुले नतीजे (कुछ हद तक गड़बड़ी)

यहां दिए गए उदाहरण में, एक मान्य जगह का यूआरएल और एक ऐसा यूआरएल शामिल है जिसे किसी जगह के लिए रिज़ॉल्व नहीं किया जा सकता:

curl -X POST \
-H "Content-Type: application/json" \
-d '{
  "urls": [
    "https://www.google.com/maps/place/Googleplex/@37.4220041,-122.0862515,17z/data=!3m1!4b1!4m6!3m5!1s0x808fba02425dad8f:0x6c296c66619367e0!8m2!3d37.4219998!4d-122.0840575!16s%2Fg%2F11c8b0ssp6",
    "https://www.google.com/not-a-place"
  ]
}' \
"https://mapstools.googleapis.com/v1:resolveMapsUrls?key=API_KEY"

JSON का रिस्पॉन्स

{
  "entities": [
    {
      "place": "places/ChIJj61dQgK6j4AR4GeTYWZsKWw"
    },
    {}
  ],
  "failedRequests": {
    "1": {
      "code": 3,
      "message": "Failed to resolve Maps URL to a place."
    }
  },
  "saveToMapsUrl": "https://www.google.com/maps/@?api=1&map_action=shortlist&place_ids=ChIJj61dQgK6j4AR4GeTYWZsKWw"
}

Curl का उदाहरण: पुष्टि नहीं हो सकी

नीचे दिए गए उदाहरण में, एक ही अनुरोध में 20 से ज़्यादा यूआरएल पास किए गए हैं:

python3 -c 'import json; print(json.dumps({"urls": ["https://www.google.com/maps/place/Googleplex"] * 21}))' | \
curl -X POST \
-H "Content-Type: application/json" \
-d @- \
"https://mapstools.googleapis.com/v1:resolveMapsUrls?key=API_KEY"

JSON का रिस्पॉन्स

{
  "error": {
    "code": 400,
    "message": "Request contains more than 20 URLs.",
    "status": "INVALID_ARGUMENT"
  }
}

सुझाव भेजें

Resolution API से जुड़ी किसी समस्या की शिकायत करने या इसके बारे में सुझाव/राय देने या शिकायत करने के लिए, Maps एक्सपीरियंस एजेंट टूल के सार्वजनिक समस्या ट्रैकर कॉम्पोनेंट का इस्तेमाल करें:

• किसी गड़बड़ी की शिकायत करना
• सुविधा का अनुरोध सबमिट करना
• सुझाव/राय दें या शिकायत करें