Google आपकी पसंदीदा भाषा में कॉन्टेंट का अनुवाद करने के लिए, एआई टेक्नोलॉजी का इस्तेमाल करता है. एआई से मिले अनुवादों में गलतियां हो सकती हैं.

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 MCP सर्वर पर टूल के तौर पर उपलब्ध है:

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

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

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

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

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

एपीआई पासकोड

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

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 शामिल नहीं होता है.

आंशिक गड़बड़ियों को ठीक करना

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

जवाब को समझना

एक-एक करके अलाइन करने की गारंटी: इंडेक्स के हिसाब से, जवाब के तौर पर मिली results सूची (ResolveNames के लिए) या entities सूची (ResolveMapsUrls के लिए) में मौजूद हर आइटम, इनपुट सूची में मौजूद किसी आइटम से एक-एक करके अलाइन होता है.
गड़बड़ियों के लिए खाली एलिमेंट: अगर इंडेक्स i पर मौजूद आइटम को हल नहीं किया जा सका, तो नतीजों की सूची में इंडेक्स i पर एक खाली ऑब्जेक्ट {} मौजूद होता है.
failedRequests मैप: जवाब में failedRequests मैप मौजूद है.
- कुंजी, फ़ेल हुए आइटम का 0 पर आधारित इंडेक्स है. इसे JSON में स्ट्रिंग के तौर पर दिखाया जाता है.
- वैल्यू, google.rpc.Status ऑब्जेक्ट है. इसमें गड़बड़ी का कोड और यह जानकारी शामिल होती है कि आइटम क्यों अस्वीकार किया गया.
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): अनुरोध को फिर से भेजें.

MCP के साथ Resolution API का इस्तेमाल करना

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

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

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

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" और "Eiffel Tower" के बारे में जानकारी मिलती है.

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 के सार्वजनिक समस्या ट्रैकर कॉम्पोनेंट का इस्तेमाल करें:

Maps Tools Resolution API संग्रह की मदद से व्यवस्थित रहें अपनी प्राथमिकताओं के आधार पर, कॉन्टेंट को सेव करें और कैटगरी में बांटें.

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

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

एपीआई पासकोड

OAuth 2.0 के स्कोप

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

कीमत

पुष्टि करने का अनुरोध और सीमाएं

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

आंशिक गड़बड़ियों को ठीक करना

जवाब को समझना

हर आइटम के लिए गड़बड़ियां

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

MCP के साथ Resolution API का इस्तेमाल करना

REST API की खास बातें और curl के उदाहरण

ResolveNames

तरीका: POST

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

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

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

Curl का उदाहरण: मिले-जुले नतीजे (कुछ अनुरोध पूरे नहीं हुए)

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

ResolveMapsUrls

तरीका: POST

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

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

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

Curl का उदाहरण: मिले-जुले नतीजे (कुछ अनुरोध पूरे नहीं हुए)

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

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

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

सुझाव भेजें

Maps Tools Resolution API