यह प्रॉडक्ट या सुविधा, प्री-जीए के तहत प्रीव्यू लॉन्च के चरण में है (प्री-जीए). ऐसा हो सकता है कि Pre-GA के तहत आने वाले प्रॉडक्ट और सुविधाओं के लिए, आपको पूरी सहायता न मिले. साथ ही, ऐसा हो सकता है कि Pre-GA के तहत आने वाले प्रॉडक्ट और सुविधाओं में किए गए बदलाव, Pre-GA के अन्य वर्शन के साथ काम न करें. Pre-GA ऑफ़र पर, Google Maps Platform की सेवा से जुड़ी खास शर्तें लागू होती हैं. ज़्यादा जानकारी के लिए, लॉन्च के चरणों की जानकारी देखें.

Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

Map Management API वेब सेवाओं का इस्तेमाल करने के सबसे सही तरीके

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

इस गाइड में, वेब सेवा के अनुरोध सेट अप करने और सेवा के जवाबों को प्रोसेस करने के कुछ सामान्य तरीकों के बारे में बताया गया है. Map Management API के पूरे दस्तावेज़ के लिए, डेवलपर की गाइड देखें.

वेब सेवा क्या है?

Google Maps Platform की वेब सेवाएं, बाहरी सेवाओं से Maps API का डेटा पाने और Maps ऐप्लिकेशन में उस डेटा का इस्तेमाल करने के लिए एक इंटरफ़ेस हैं. Google Maps Platform की सेवा की शर्तों में दिए गए लाइसेंस से जुड़ी पाबंदियों के मुताबिक, इन सेवाओं को मैप के साथ इस्तेमाल किया जाता है.

Maps API की वेब सेवाएं, खास यूआरएल के लिए एचटीटीपी(एस) अनुरोधों का इस्तेमाल करती हैं. साथ ही, सेवाओं के लिए आर्ग्युमेंट के तौर पर, यूआरएल पैरामीटर और/या JSON फ़ॉर्मैट में POST डेटा पास करती हैं. आम तौर पर, ये सेवाएं रिस्पॉन्स बॉडी में JSON के तौर पर डेटा दिखाती हैं, ताकि आपका ऐप्लिकेशन इसे पार्स और/या प्रोसेस कर सके.

यहां दिए गए उदाहरण में, list Map Configs तरीके के लिए REST GET अनुरोध दिखाया गया है:

https://mapmanagement.googleapis.com/v2beta/projects/PROJECT_NUMBER_OR_ID/mapConfigs

अपने अनुरोध में, OAuth टोकन को अनुरोध के Authorization header में शामिल करें.

एसएसएल/टीएलएस ऐक्सेस

Google Maps Platform के उन सभी अनुरोधों के लिए HTTPS ज़रूरी है जिनमें एपीआई पासकोड का इस्तेमाल किया जाता है या जिनमें उपयोगकर्ता का डेटा शामिल होता है. संवेदनशील डेटा वाले एचटीटीपी अनुरोधों को अस्वीकार किया जा सकता है.

मान्य यूआरएल बनाना

आपको लग सकता है कि "मान्य" यूआरएल की पहचान करना आसान है, लेकिन ऐसा नहीं है. उदाहरण के लिए, ब्राउज़र के पता बार में डाला गया कोई यूआरएल, खास वर्णों (जैसे, "上海+中國") वाला हो सकता है. ऐसे में, ब्राउज़र को इन वर्णों को ट्रांसमिशन से पहले, किसी दूसरी एन्कोडिंग में बदलना पड़ता है. इसी तरह, UTF-8 इनपुट जनरेट करने या स्वीकार करने वाला कोई भी कोड, UTF-8 वर्णों वाले यूआरएल को "मान्य" मान सकता है. हालांकि, उसे वेब सर्वर पर भेजने से पहले, इन वर्णों को बदलना होगा. इस प्रोसेस को यूआरएल-एन्कोडिंग या पर्सेंट-एन्कोडिंग कहा जाता है.

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

विशेष वर्ण

हमें विशेष वर्णों को बदलना होगा, क्योंकि सभी यूआरएल को यूनिफ़ॉर्म रिसोर्स आइडेंटिफ़ायर (यूआरआई) की खास जानकारी में बताई गई सिंटैक्स के मुताबिक होना चाहिए. इसका मतलब है कि यूआरएल में सिर्फ़ ASCII वर्णों का खास सबसेट होना चाहिए. इसमें अंग्रेज़ी (रोमन स्क्रिप्ट) के अक्षर और अंक, और यूआरएल में कंट्रोल वर्ण के तौर पर इस्तेमाल किए जाने वाले कुछ रिज़र्व वर्ण शामिल हैं. इस टेबल में इन वर्णों के बारे में बताया गया है:

मान्य यूआरएल वर्णों की खास जानकारी

सेट करें	वर्ण	यूआरएल का इस्तेमाल
अक्षर और अंक दोनों शामिल हो सकते हैं	a b c d e f g h i j k l m n o p q r s t u v w x y z A B C D E F G H I J K L M N O P Q R S T U V W X Y Z 0 1 2 3 4 5 6 7 8 9	टेक्स्ट स्ट्रिंग, स्कीम का इस्तेमाल (`http`), पोर्ट (`8080`) वगैरह.
गैर-आरक्षित	- _ . ~	टेक्स्ट स्ट्रिंग
बुकिंग की गई	! * ' ( ) ; : @ & = + $ , / ? % # [ ]	कंट्रोल वर्ण और/या टेक्स्ट स्ट्रिंग

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

जिन वर्णों को आपको मैनेज करना है वे ऊपर दिए गए सेट से बाहर हैं. उदाहरण के लिए, `上海+中國` जैसी विदेशी भाषाओं के वर्णों को ऊपर दिए गए वर्णों का इस्तेमाल करके एनकोड करना होगा. आम तौर पर, स्पेस (जिन्हें यूआरएल में शामिल नहीं किया जा सकता) को प्लस '+' वर्ण का इस्तेमाल करके भी दिखाया जाता है.
वर्ण, ऊपर दिए गए सेट में रिज़र्व वर्ण के तौर पर मौजूद हैं, लेकिन उन्हें लिटरल तौर पर इस्तेमाल करना होगा. उदाहरण के लिए, यूआरएल में ? का इस्तेमाल, क्वेरी स्ट्रिंग की शुरुआत दिखाने के लिए किया जाता है. अगर आपको "? and the Mysterions" स्ट्रिंग का इस्तेमाल करना है, तो आपको '?' वर्ण को एनकोड करना होगा.

यूआरएल-एनकोड किए जाने वाले सभी वर्णों को '%' वर्ण और उनके UTF-8 वर्ण के लिए दो वर्णों वाली हेक्स वैल्यू का इस्तेमाल करके एनकोड किया जाता है. उदाहरण के लिए, UTF-8 में 上海+中國 को यूआरएल-एनकोड करके %E4%B8%8A%E6%B5%B7%2B%E4%B8%AD%E5%9C%8B लिखा जाएगा. ? and the Mysterians स्ट्रिंग को यूआरएल-एनकोड करके %3F+and+the+Mysterians या %3F%20and%20the%20Mysterians लिखा जाएगा.

एनकोड किए जाने वाले सामान्य वर्ण

कुछ सामान्य वर्ण जिन्हें एनकोड करना ज़रूरी है:

असुरक्षित वर्ण	एनकोड की गई वैल्यू
स्पेस	`%20`
"	`%22`
<	`%3C`
>	`%3E`
#	`%23`
%	`%25`
\|	`%7C`

कभी-कभी, उपयोगकर्ता के इनपुट से मिले यूआरएल को बदलना मुश्किल होता है. उदाहरण के लिए, कोई उपयोगकर्ता "5th&Main St." के तौर पर पता डाल सकता है. आम तौर पर, आपको यूआरएल को उसके हिस्सों से बनाना चाहिए. साथ ही, उपयोगकर्ता के किसी भी इनपुट को लिटरल वर्ण के तौर पर इस्तेमाल करना चाहिए.

इसके अलावा, Google Maps Platform की सभी वेब सेवाओं और स्टैटिक वेब एपीआई के लिए, यूआरएल में ज़्यादा से ज़्यादा 16,384 वर्ण शामिल किए जा सकते हैं. ज़्यादातर सेवाओं के लिए, वर्णों की इस सीमा तक पहुंचने की ज़रूरत नहीं पड़ती. हालांकि, ध्यान दें कि कुछ सेवाओं में कई पैरामीटर होते हैं. इस वजह से, यूआरएल लंबे हो सकते हैं.

Google के एपीआई का सही तरीके से इस्तेमाल करना

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

एक्स्पोनेंशियल बैकऑफ़

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

इसका बेहतर तरीका यह है कि अनुरोध को फिर से भेजते समय, हर बार अनुरोध भेजने के बीच का समय बढ़ाया जाए. आम तौर पर, हर बार अनुरोध भेजने के बीच का समय, मल्टीप्लिकेटिव फ़ैक्टर से बढ़ाया जाता है. इस तरीके को एक्स्पोनेंशियल बैकऑफ़कहा जाता है.

उदाहरण के लिए, मान लें कि कोई ऐप्लिकेशन, Time Zone API को यह अनुरोध भेजना चाहता है:

https://maps.googleapis.com/maps/api/timezone/json?location=39.6034810,-119.6822510&timestamp=1331161200&key=YOUR_API_KEY

यहां दिए गए Python के उदाहरण में, एक्स्पोनेंशियल बैकऑफ़ के साथ अनुरोध भेजने का तरीका बताया गया है:

import json
import time
import urllib.error
import urllib.parse
import urllib.request

# The maps_key defined below isn't a valid Google Maps API key.
# You need to get your own API key.
# See https://developers.google.com/maps/documentation/timezone/get-api-key
API_KEY = "YOUR_KEY_HERE"
TIMEZONE_BASE_URL = "https://maps.googleapis.com/maps/api/timezone/json"


def timezone(lat, lng, timestamp):

    # Join the parts of the URL together into one string.
    params = urllib.parse.urlencode(
        {"location": f"{lat},{lng}", "timestamp": timestamp, "key": API_KEY,}
    )
    url = f"{TIMEZONE_BASE_URL}?{params}"

    current_delay = 0.1  # Set the initial retry delay to 100ms.
    max_delay = 5  # Set the maximum retry delay to 5 seconds.

    while True:
        try:
            # Get the API response.
            response = urllib.request.urlopen(url)
        except urllib.error.URLError:
            pass  # Fall through to the retry loop.
        else:
            # If we didn't get an IOError then parse the result.
            result = json.load(response)

            if result["status"] == "OK":
                return result["timeZoneId"]
            elif result["status"] != "UNKNOWN_ERROR":
                # Many API errors cannot be fixed by a retry, e.g. INVALID_REQUEST or
                # ZERO_RESULTS. There is no point retrying these requests.
                raise Exception(result["error_message"])

        if current_delay > max_delay:
            raise Exception("Too many retry attempts.")

        print("Waiting", current_delay, "seconds before retrying.")

        time.sleep(current_delay)
        current_delay *= 2  # Increase the delay each time we retry.


if __name__ == "__main__":
    tz = timezone(39.6034810, -119.6822510, 1331161200)
    print(f"Timezone: {tz}")

आपको यह भी ध्यान रखना चाहिए कि ऐप्लिकेशन कॉल चेन में, फिर से अनुरोध भेजने का कोई ऐसा कोड न हो जिसकी वजह से, तेज़ी से बार-बार अनुरोध भेजे जाएं.

सिंक्रोनाइज़ किए गए अनुरोध

Google के एपीआई को सिंक्रोनाइज़ किए गए कई अनुरोध भेजने पर, Google के इन्फ़्रास्ट्रक्चर पर डिस्ट्रिब्यूटेड डिनायल ऑफ़ सर्विस (डीडीओएस) हमला हो सकता है. इसलिए, इन अनुरोधों को उसी तरह से प्रोसेस किया जाता है. इससे बचने के लिए, आपको यह पक्का करना चाहिए कि एपीआई के अनुरोध, क्लाइंट के बीच सिंक्रोनाइज़ न किए जाएं.

उदाहरण के लिए, मान लें कि कोई ऐप्लिकेशन, मौजूदा टाइम ज़ोन में समय दिखाता है. यह ऐप्लिकेशन, क्लाइंट ऑपरेटिंग सिस्टम में अलार्म सेट करेगा, ताकि हर मिनट की शुरुआत में, यह ऐप्लिकेशन को जगा सके. इससे, दिखाए गए समय को अपडेट किया जा सकेगा. ऐप्लिकेशन को उस अलार्म से जुड़ी प्रोसेसिंग के हिस्से के तौर पर, कोई भी एपीआई कॉल नहीं करना चाहिए.

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

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

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

जवाबों को प्रोसेस करना

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

इस सेक्शन में, वेब सेवा के जवाबों से इन वैल्यू को डाइनैमिक तरीके से निकालने का तरीका बताया गया है.

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

पार्सिंग के लिए इस्तेमाल की जाने वाली स्कीम इस बात पर निर्भर करती है कि आउटपुट JSON में दिखाया जा रहा है या नहीं. JSON जवाब, पहले से ही JavaScript ऑब्जेक्ट के फ़ॉर्म में होते हैं. इसलिए, इन्हें क्लाइंट पर JavaScript में ही प्रोसेस किया जा सकता है.