Maps Tools Resolution API

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

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

अनुमति	REST मेथड	एमसीपी टूल
जगहों के नाम या पतों को जगहों से मैच करना	resolveNames	resolve_names
Google Maps के यूआरएल को जगहों की जानकारी में बदलना	resolveMapsUrls	resolve_maps_urls

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

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

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

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 Grounding Lite की तरह ही, आपके प्रोजेक्ट के लिए एक बिलिंग खाता होना ज़रूरी है.

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

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

• बैच साइज़ की सीमा: दोनों तरीकों से, हर अनुरोध में ज़्यादा से ज़्यादा 20 आइटम शामिल किए जा सकते हैं.
• ResolveNames के लिए ज़रूरी शर्तें:
  • queries में मौजूद हर आइटम के लिए, text पैरामीटर की वैल्यू देना ज़रूरी है. यह वैल्यू खाली नहीं होनी चाहिए.
  • क्वेरी में किसी जगह का नाम या पता साफ़ तौर पर होना चाहिए. उदाहरण के लिए, "Googleplex, Mountain View, CA" या "Eiffel Tower, Paris".
  • कैटगरी के हिसाब से की जाने वाली सामान्य खोजें (उदाहरण के लिए, "दिल्ली में रेस्टोरेंट") या जगह की जानकारी के बिना चेन के सामान्य नाम (उदाहरण के लिए, "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 में दिख सकती हैं:

तरीका	वजह	कोड	मैसेज
ResolveNames	नाम या पते से किसी जगह की जानकारी नहीं मिल पा रही है.	5 (NOT_FOUND)	Place not found.
ResolveMapsUrls	यूआरएल को किसी जगह के लिए इस्तेमाल नहीं किया जा सकता.	3 (INVALID_ARGUMENT)	Failed to resolve Maps URL to a place.
दोनों तरीके	आइटम को ठीक करने के दौरान, सिस्टम में कोई गड़बड़ी हुई.	13 (INTERNAL)	Internal server error. Please retry. If the problem persists, please open a support case. https://goo.gle/maps-platform-support

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

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

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

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

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

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

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

Maps Grounding Lite एमसीपी सर्वर का इस्तेमाल करने के लिए एलएलएम को कॉन्फ़िगर करने पर, ये टूल Maps Grounding Lite के अन्य टूल के साथ उपलब्ध होते हैं. ये टूल, 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 के उदाहरण

ध्यान दें: अगर आपने Resolution API का इस्तेमाल, एक्सपेरिमेंट के तौर पर उपलब्ध होने के दौरान शुरू किया था, तो v1alpha एंडपॉइंट काम करते रहेंगे. हमारा सुझाव है कि आप v1 एंडपॉइंट पर माइग्रेट करें.

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 (ज़रूरी नहीं): सीएलडीआर देश का कोड (उदाहरण के लिए, "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 Grounding Lite के सार्वजनिक समस्या ट्रैकर कॉम्पोनेंट का इस्तेमाल करें:

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