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 API की वेब सेवाएं, खास यूआरएल के लिए एचटीटीपी या एचटीटीपीएस अनुरोधों का इस्तेमाल करती हैं. ये सेवाओं के लिए आर्ग्युमेंट के तौर पर, यूआरएल पैरामीटर या JSON फ़ॉर्मैट में पोस्ट डेटा पास करती हैं. आम तौर पर, ये सेवाएं आपके ऐप्लिकेशन से पार्स या प्रोसेस करने के लिए, रिस्पॉन्स बॉडी में JSON के तौर पर डेटा दिखाती हैं.

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

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

ध्यान दें: Street View Static API के सभी ऐप्लिकेशन के लिए, पुष्टि करना ज़रूरी है. ज़्यादा जानकारी के लिए, पुष्टि करने वाले क्रेडेंशियल देखें.

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

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

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

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