Street View Static API इस्तेमाल करने के सबसे सही तरीके

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

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

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

Street View Static API, स्टैटिक वेब एपीआई की तरह काम करता है. वहीं, मेटाडेटा सेवा, वेब सेवा की तरह काम करती है. मेटाडेटा सेवा के बारे में ज़्यादा जानने के लिए, Street View इमेज का मेटाडेटा देखें.

स्टैटिक वेब एपीआई क्या है?

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

Street View Static API का सामान्य अनुरोध इस तरह का होता है:

  https://www.googleapis.com/streetview/z/x/y?parameters

वेब सेवा क्या होती है?

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

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

Street View Static API के मेटाडेटा का अनुरोध, इस तरह का होता है:

https://maps.googleapis.com/maps/api/streetview/parameters

एसएसएल और टीएलएस का ऐक्सेस

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

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

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

विशेष वर्ण

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

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

• आपको जिन वर्णों को हैंडल करना है वे ऊपर दिए गए सेट से बाहर हैं. उदाहरण के लिए, विदेशी भाषाओं के वर्णों, जैसे कि 上海+中國 को ऊपर दिए गए वर्णों का इस्तेमाल करके एन्कोड करना होगा. आम तौर पर, स्पेस (जिन्हें यूआरएल में इस्तेमाल करने की अनुमति नहीं है) को प्लस '+' वर्ण का इस्तेमाल करके भी दिखाया जाता है.
• ऊपर दिए गए सेट में वर्ण, रिज़र्व किए गए वर्णों के तौर पर मौजूद होते हैं. हालांकि, इनका इस्तेमाल लिटरल तौर पर किया जाना चाहिए. उदाहरण के लिए, यूआरएल में ? का इस्तेमाल क्वेरी स्ट्रिंग की शुरुआत दिखाने के लिए किया जाता है. अगर आपको "? 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 लिखा जाएगा.

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

कुछ सामान्य वर्णों को कोड में बदलना ज़रूरी है. जैसे:

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

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

Google API का सही तरीके से इस्तेमाल करना

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

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

कुछ मामलों में, आपके अनुरोध में कोई गड़बड़ी हो सकती है. आपको 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 in the following code 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 the request didn't produce an IOError, parse the result.
            result = json.load(response)

            if result["status"] == "OK":
                return result["timeZoneId"]
            elif result["status"] != "UNKNOWN_ERROR":
                # Many API errors can't be fixed by a retry, such as
                # INVALID_REQUEST or ZERO_RESULTS. Don't retry 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 on each retry.


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

पक्का करें कि ऐप्लिकेशन कॉल चेन में, फिर से कोशिश करने वाला कोई ऐसा कोड न हो जिसकी वजह से, एक के बाद एक अनुरोध किए जा रहे हों.

सिंक किए गए अनुरोध

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

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

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

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

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

जवाबों को प्रोसेस किया जा रहा है

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

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

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

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