जियोलोकेशन एपीआई की वेब सेवाओं को इस्तेमाल करने के सबसे सही तरीके

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

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

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

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

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

जियोलोकेशन के अनुरोध POST का इस्तेमाल करके नीचे दिए गए यूआरएल पर भेजे जाते हैं:

https://www.googleapis.com/geolocation/v1/geolocate?key=YOUR_API_KEY

ध्यान दें: सभी जियोलोकेशन एपीआई ऐप्लिकेशन के लिए पुष्टि करना ज़रूरी है. पुष्टि करने के क्रेडेंशियल के बारे में ज़्यादा जानकारी पाएं.

एसएसएल/TLS ऐक्सेस

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

Google API का विनम्र उपयोग

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

घातांकीय बैकऑफ़

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

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

उदाहरण के लिए, एक ऐसा ऐप्लिकेशन चुनें जो टाइम ज़ोन एपीआई से यह अनुरोध करना चाहता है:

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 के इन्फ़्रास्ट्रक्चर पर डिस्ट्रिब्यूटेड डिनायल ऑफ़ सर्विस (डीडीओएस) हमले की तरह लग सकती है. इसी तरह, इन अनुरोधों पर कार्रवाई की जाती है. इससे बचने के लिए आपको यह पक्का करना चाहिए कि क्लाइंट के बीच एपीआई अनुरोध सिंक न किए गए हों.

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

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

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

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

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

इस सेक्शन में बताया गया है कि वेब सर्विस रिस्पॉन्स से डाइनैमिक तौर पर इन वैल्यू को कैसे एक्सट्रैक्ट किया जा सकता है.

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

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