Maps Tools Resolution API (एक्सपेरिमेंट के तौर पर उपलब्ध)

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

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

पुष्टि करने के तरीके

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

1. एपीआई पासकोड

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

https://mapstools.googleapis.com/v1alpha:resolveNames?key=YOUR_API_KEY

2. OAuth 2.0 के दायरे

OAuth ऑथराइज़ेशन का इस्तेमाल करने पर, ये दायरे काम करते हैं:

• https://www.googleapis.com/auth/maps-platform.mapstools (सुझाया गया)

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

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

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

कुछ गड़बड़ियों को मैनेज करना

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

जवाब को समझने का तरीका

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

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

टॉप-लेवल की एचटीटीपी गड़बड़ी (जैसे, 400 Bad Request) तब दिखती है, जब अनुरोध की पुष्टि नहीं हो पाती. जैसे, 20 से ज़्यादा आइटम पास करने पर या ज़रूरी फ़ील्ड मौजूद न होने पर.

एपीआई की खास जानकारी और कर्ल के उदाहरण

1. ResolveNames API

तरीका: POST

https://mapstools.googleapis.com/v1alpha: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".

कर्ल का उदाहरण: क्वेरी को हल करना

इस क्वेरी से "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/v1alpha:resolveNames?key=KEY"

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

{
  "results": [
    {
      "entity": {
        "place": "places/ChIJj61dQgK6j4AR4GeTYWZsKWw"
      },
      "confidence": "HIGH"
    },
    {
      "entity": {
        "place": "places/ChIJLU7jZClu5kcR4PcOOO6p3I0"
      },
      "confidence": "HIGH"
    }
  ]
}

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

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

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/v1alpha:resolveNames?key=KEY"

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

{
  "results": [
    {},
    {
      "entity": {
        "place": "places/ChIJLU7jZClu5kcR4PcOOO6p3I0"
      },
      "confidence": "HIGH"
    }
  ],
  "failedRequests": {
    "0": {
      "code": 5,
      "message": "Place not found."
    }
  }
}

2. ResolveMapsUrls API

तरीका: POST

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

अनुरोध के मुख्य भाग का फ़ॉर्मैट

{
  "urls": [
    "string"
  ]
}

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

कर्ल का उदाहरण: क्वेरी को हल करना

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!1s0x808fba024255ad8f:0x6ca26666619367e0!8m2!3d37.4219998!4d-122.0840575!16s%2Fg%2F11c8b0ssp6"
]
}' \
"https://mapstools.googleapis.com/v1alpha:resolveMapsUrls?key=KEY"

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

{
  "entities": [
    {
      "place": "places/ChIJj61VQgK6j4AR4GeTYWZmomw"
    }
  ]
}

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

किसी मान्य जगह के यूआरएल और किसी गलत फ़ॉर्मैट वाले/काम न करने वाले यूआरएल को हल करना.

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!1s0x808fba024255ad8f:0x6ca26666619367e0!8m2!3d37.4219998!4d-122.0840575!16s%2Fg%2F11c8b0ssp6",
    "https://www.google.com/not-a-place"
  ]
}' \
"https://mapstools.googleapis.com/v1alpha:resolveMapsUrls?key=KEY"

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

{
  "entities": [
    {
      "place": "places/ChIJj61VQgK6j4AR4GeTYWZmomw"
    },
    {}
  ],
  "failedRequests": {
    "1": {
      "code": 3,
      "message": "Invalid URL."
    }
  }
}

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

एक ही अनुरोध में 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/v1alpha:resolveMapsUrls?key=KEY"

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

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