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

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

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

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

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

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

आम तौर पर, Roads API वेब सेवा का अनुरोध इस तरह का होता है:

https://roads.googleapis.com/v1/snapToRoads?parameters&key=YOUR_API_KEY

इसमें snapToRoads, अनुरोध की गई सेवा के बारे में बताता है. सड़क से जुड़ी अन्य सेवाओं में nearestRoads और speedLimits शामिल हैं.

ध्यान दें: सभी Roads 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 का सही तरीके से इस्तेमाल करना

खराब तरीके से डिज़ाइन किए गए एपीआई क्लाइंट, इंटरनेट और 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 में ही इन्हें प्रोसेस किया जा सकता है.