Maps Datasets API ওয়েব পরিষেবা ব্যবহার করার পেশাদার পদ্ধতি

Google Maps Platform ওয়েব পরিষেবা হল Google পরিষেবার HTTP ইন্টারফেসের একটি সংগ্রহ যা আপনার ম্যাপ অ্যাপ্লিকেশনের জন্য ভৌগোলিক ডেটা প্রদান করে।

এই নির্দেশিকায় আপনার ওয়েব পরিষেবা অনুরোধ সেট-আপ করা এবং পরিষেবার উত্তর প্রসেস করার জন্য উপযোগী কিছু সাধারণ পদ্ধতি বর্ণনা করা হয়েছে। Maps Datasets API-এর সম্পূর্ণ ডকুমেন্টেশনের জন্য ডেভেলপারের নির্দেশিকা দেখুন।

ওয়েব পরিষেবা কী?

Google Maps Platform ওয়েব পরিষেবা হল এক্সটার্নাল পরিষেবা থেকে Maps API ডেটার অনুরোধ করা এবং আপনার Maps অ্যাপ্লিকেশনের মধ্যে ডেটা ব্যবহার করার জন্য একটি ইন্টারফেস। এইসব পরিষেবা Google Maps Platform পরিষেবার শর্তাবলীতে উল্লিখিত লাইসেন্স সংক্রান্ত বিধিনিষেধ অনুযায়ী ম্যাপের সাথে একসাথে ব্যবহার করার জন্য ডিজাইন করা হয়েছে।

Maps API ওয়েব পরিষেবা নির্দিষ্ট URL-এ HTTP(S) অনুরোধ ব্যবহার করে, URL প্যারামিটার এবং/অথবা JSON-ফর্ম্যাট POST ডেটা পরিষেবায় আর্গুমেন্ট হিসেবে পাস করে। সাধারণত, এইসব পরিষেবা আপনার অ্যাপ্লিকেশনের মাধ্যমে পার্সিং এবং/অথবা প্রসেসিংয়ের জন্য JSON হিসেবে রেসপন্স বডিতে ডেটা ফেরত দেয়।

নিম্নলিখিত উদাহরণে তালিকা ডেটাসেট পদ্ধতিতে REST GET অনুরোধের URL দেখানো হয়েছে:

https://mapsplatformdatasets.googleapis.com/v1/projects/PROJECT_NUMBER_OR_ID/datasets

আপনার অনুরোধে একটি OAuth টোকেন অন্তর্ভুক্ত করুন অনুরোধের Authorization header-এ।

মনে রাখবেন: সব Maps Datasets API অ্যাপ্লিকেশনের জন্য যাচাইকরণ প্রয়োজন। যাচাইকরণ সংক্রান্ত ক্রেডেনশিয়াল সম্পর্কে আরও তথ্য পান।

SSL/TLS অ্যাক্সেস

API কী ব্যবহার করে বা ব্যবহারকারীর ডেটা আছে এমন সব Google Maps Platform অনুরোধের জন্য HTTPS প্রয়োজন। HTTP-এর মাধ্যমে করা অনুরোধে সংবেদনশীল ডেটা থাকলে তা বাতিল করা হতে পারে।

সঠিক URL তৈরি করা

আপনি হয়ত মনে করতে পারেন যে "সঠিক" URL বলতে কী বোঝায় তা সহজেই বোঝা যায়, কিন্তু বিষয়টি তা নয়। ব্রাউজারের অ্যাড্রেস বারে লেখা URL-এ বিশেষ অক্ষর (যেমন, "上海+中國") থাকতে পারে; ব্রাউজারকে ট্রান্সমিশনের আগে ইন্টার্নালি সেইসব অক্ষরকে অন্য এনকোডিংয়ে ট্রান্সলেট করতে হয়। একইভাবে, UTF-8 ইনপুট তৈরি বা গ্রহণ করে এমন যেকোনও কোড UTF-8 অক্ষর সহ URL-কে "সঠিক" হিসেবে বিবেচনা করতে পারে, তবে সেগুলি কোনও ওয়েব সার্ভারে পাঠানোর আগে সেই অক্ষরগুলি অনুবাদ করতে হবে। এই প্রক্রিয়াকে URL-এনকোডিং বা শতাংশ-এনকোডিং বলা হয়।

বিশেষ অক্ষর

আমাদের বিশেষ অক্ষরগুলি অনুবাদ করতে হবে কারণ সব URL-কে ইউনিফর্ম রিসোর্স আইডেন্টিফায়ার (URI) স্পেসিফিকেশন দ্বারা নির্দিষ্ট সিনট্যাক্স মেনে চলতে হবে। এর অর্থ হল, URL-এ শুধুমাত্র ASCII অক্ষরের বিশেষ সাবসেট থাকতে হবে: পরিচিত অ্যালফানিউমেরিক চিহ্ন এবং URL-এর মধ্যে কন্ট্রোল অক্ষর হিসেবে ব্যবহার করার জন্য কিছু সংরক্ষিত অক্ষর। এই সারণীতে এইসব অক্ষরের সারসংক্ষেপ দেওয়া হল:

সঠিক URL অক্ষরের সারাংশ
সেট করুনঅক্ষরURL ব্যবহার
বর্ণসাংখ্যিক 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) ইত্যাদি।
রিজার্ভ করা নেই - _ . ~ টেক্সট স্ট্রিং
রিজার্ভ করা ! * ' ( ) ; : @ & = + $ , / ? % # [ ] কন্ট্রোল অক্ষর এবং/অথবা টেক্সট স্ট্রিং

সঠিক URL তৈরি করার সময়, আপনাকে নিশ্চিত করতে হবে যে এতে শুধুমাত্র টেবিলে দেখানো অক্ষরগুলিই রয়েছে। এই অক্ষর সেট ব্যবহার করার জন্য কোনও URL কনফার্ম করলে সাধারণত দুটি সমস্যা হয়, একটি হল বাদ দেওয়া এবং অন্যটি হল প্রতিস্থাপন করা:

  • আপনি যেসব অক্ষর হ্যান্ডেল করতে চান সেগুলি উপরের সেটের বাইরে আছে। যেমন, বিদেশি ভাষার অক্ষর যেমন 上海+中國-কে উপরের অক্ষর ব্যবহার করে এনকোড করতে হবে। জনপ্রিয় প্রথা অনুযায়ী, স্পেস (যা URL-এর মধ্যে অনুমোদিত নয়) প্রায়ই প্লাস '+' অক্ষর ব্যবহার করেও দেখানো হয়।
  • উপরে উল্লিখিত সেটে সংরক্ষিত অক্ষর হিসেবে অক্ষরগুলি রয়েছে, তবে এগুলি আক্ষরিক অর্থে ব্যবহার করতে হবে। যেমন, কোয়েরি স্ট্রিংয়ের শুরু বোঝাতে URL-এর মধ্যে ? ব্যবহার করা হয়; আপনি যদি "? and the Mysterions" স্ট্রিং ব্যবহার করতে চান, তাহলে আপনাকে '?' অক্ষরটি এনকোড করতে হবে।

URL-এনকোড করা সমস্ত অক্ষর '%' অক্ষর এবং তাদের UTF-8 অক্ষরের সাথে সম্পর্কিত দুই-অক্ষরের হেক্স মান ব্যবহার করে এনকোড করা হয়। যেমন, 上海+中國 UTF-8-এ URL-এনকোড করা হবে এইভাবে %E4%B8%8A%E6%B5%B7%2B%E4%B8%AD%E5%9C%8B. ? and the Mysterians স্ট্রিংটি URL-এনকোড করা হলে %3F+and+the+Mysterians বা %3F%20and%20the%20Mysterians হিসেবে দেখানো হবে।

সাধারণ অক্ষর যেগুলি এনকোড করতে হবে

কিছু সাধারণ অক্ষর যা অবশ্যই এনকোড করতে হবে:

অসুরক্ষিত ক্যারেক্টার এনকোড করা ভ্যালু
স্পেস %20
" %22
< %3C
> %3E
# %23
% %25
| %7C

ব্যবহারকারীর ইনপুট থেকে পাওয়া URL কনভার্ট করা কখনও কখনও কঠিন হয়। যেমন, কোনও ব্যবহারকারী "5th&Main St." হিসেবে ঠিকানা লিখতে পারেন। সাধারণত, আপনাকে URL-এর অংশগুলি থেকে URL তৈরি করতে হবে এবং ব্যবহারকারীর দেওয়া যেকোনও ইনপুটকে আক্ষরিক অক্ষর হিসেবে বিবেচনা করতে হবে।

এছাড়াও, সব Google Maps Platform ওয়েব পরিষেবা ও স্ট্যাটিক ওয়েব API-এর জন্য URL-এর দৈর্ঘ্য ১৬৩৮৪ অক্ষরের মধ্যে সীমিত। অধিকাংশ পরিষেবার ক্ষেত্রে, এই অক্ষর সীমা খুব কমই ব্যবহার করা হবে। তবে, মনে রাখবেন, নির্দিষ্ট কিছু পরিষেবায় একাধিক প্যারামিটার থাকে যার ফলে URL অনেক বড় হতে পারে।

Google API-এর ভদ্র ব্যবহার

খারাপভাবে ডিজাইন করা API ক্লায়েন্ট, ইন্টারনেট ও Google-এর সার্ভারে প্রয়োজনের চেয়ে বেশি লোড দিতে পারে। এই বিভাগে API-এর ক্লায়েন্টদের জন্য কিছু পেশাদার পদ্ধতি উল্লেখ করা হয়েছে। এইসব পেশাদার পদ্ধতি অনুসরণ করলে, অনিচ্ছাকৃতভাবে API-এর অপব্যবহারের কারণে আপনার অ্যাপ্লিকেশন ব্লক হওয়া এড়াতে পারবেন।

এক্সপোনেনশিয়াল ব্যাকঅফ

খুব কম ক্ষেত্রে, আপনার অনুরোধ পূরণ করার সময় কোনও সমস্যা হতে পারে; আপনি 4XX বা 5XX HTTP রেসপন্স কোড পেতে পারেন অথবা আপনার ক্লায়েন্ট ও Google-এর সার্ভারের মধ্যে TCP কানেকশন কোনও কারণে কাজ নাও করতে পারে। প্রায়ই অনুরোধটি আবার করার চেষ্টা করলে কাজ হয়, কারণ আসল অনুরোধটি ব্যর্থ হলেও ফলো-আপ অনুরোধটি সফল হতে পারে। তবে, Google-এর সার্ভারে বারবার অনুরোধ লুপ করা গুরুত্বপূর্ণ নয়। এই লুপ করার আচরণ আপনার ক্লায়েন্ট ও Google-এর মধ্যে নেটওয়ার্কে ওভারলোড করতে পারে, যার ফলে অনেক পার্টি সমস্যায় পড়তে পারে।

আরও ভালো উপায় হল, প্রতিটি প্রচেষ্টার মধ্যে সময়ের ব্যবধান বাড়িয়ে আবার চেষ্টা করা। সাধারণত, প্রতিটি প্রচেষ্টার সাথে বিলম্বের সময় গুণিতক ফ্যাক্টর দ্বারা বৃদ্ধি করা হয়, এই পদ্ধতিটি এক্সপোনেনশিয়াল ব্যাকঅফ নামে পরিচিত।

যেমন, ধরুন কোনও অ্যাপ্লিকেশন টাইম জোন 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-এর API-তে বিপুল সংখ্যক সিঙ্ক্রোনাইজ করা অনুরোধ Google-এর পরিকাঠামোতে ডিস্ট্রিবিউটেড ডিনায়েল অফ সার্ভিস (DDoS) অ্যাটাকের মতো মনে হতে পারে এবং সেই অনুযায়ী ব্যবস্থা নেওয়া হতে পারে। এটি এড়াতে, আপনাকে নিশ্চিত করতে হবে যে API অনুরোধগুলি ক্লায়েন্টদের মধ্যে সিঙ্ক করা হয়নি।

যেমন, এমন একটি অ্যাপ্লিকেশনের কথা ভাবুন যা বর্তমান টাইম জোনে সময় দেখায়। এই অ্যাপ্লিকেশনটি সম্ভবত ক্লায়েন্ট অপারেটিং সিস্টেমে একটি অ্যালার্ম সেট করবে যা এটিকে মিনিটের শুরুতে জাগিয়ে তুলবে যাতে প্রদর্শিত সময় আপডেট করা যায়। অ্যাপ্লিকেশনটি যেন সেই অ্যালার্মের সাথে সম্পর্কিত প্রসেসিংয়ের অংশ হিসেবে কোনও API কল না করে।

একটি নির্দিষ্ট অ্যালার্মের উত্তরে API কল করা খারাপ কারণ এর ফলে API কলগুলি মিনিটের শুরুতে সিঙ্ক্রোনাইজ করা হয়, এমনকি বিভিন্ন ডিভাইসের মধ্যেও, সময়ের সাথে সমানভাবে বিতরণ করার পরিবর্তে। খারাপভাবে ডিজাইন করা অ্যাপ্লিকেশন এটি করলে, প্রতি মিনিটের শুরুতে ট্রাফিক স্বাভাবিক লেভেলের থেকে ষাট গুণ বেশি হয়ে যাবে।

পরিবর্তে, একটি সম্ভাব্য ভালো ডিজাইন হল, র‍্যান্ডমভাবে বেছে নেওয়া সময়ে দ্বিতীয় অ্যালার্ম সেট করা। দ্বিতীয় অ্যালার্মটি চালু হলে, অ্যাপ্লিকেশনটি প্রয়োজনীয় API কল করে এবং ফলাফল সেভ করে। মিনিটের শুরুতে অ্যাপ্লিকেশনটি তার ডিসপ্লে আপডেট করতে চাইলে, এটি আবার API কল করার পরিবর্তে আগে থেকে স্টোর করা ফলাফল ব্যবহার করে। এই পদ্ধতিতে, API কলগুলি সময়ের সাথে সমানভাবে ছড়িয়ে পড়ে। এছাড়াও, ডিসপ্লে আপডেট করার সময় API কল রেন্ডারিংয়ে দেরি করে না।

মিনিটের শুরু ছাড়াও, অন্যান্য সাধারণ সিঙ্ক করার সময় যেগুলি টার্গেট করার ব্যাপারে আপনাকে সতর্ক থাকতে হবে না, সেগুলি হল ঘণ্টার শুরু এবং প্রতিদিন মধ্যরাতে দিনের শুরু।

প্রতিক্রিয়া প্রসেস করা হচ্ছে

এই বিভাগে, কীভাবে ওয়েব পরিষেবা থেকে পাওয়া উত্তর থেকে এই ভ্যালুগুলি ডাইনামিক উপায়ে এক্সট্র্যাক্ট করা যায় তা আলোচনা করা হয়েছে।

Google Maps ওয়েব পরিষেবা এমন উত্তর দেয় যা সহজে বোঝা যায়, কিন্তু তা ঠিক ব্যবহারকারী-বান্ধব নয়। কোয়েরি করার সময়, ডেটার সেট দেখানোর পরিবর্তে, আপনি সম্ভবত কয়েকটি নির্দিষ্ট ভ্যালু এক্সট্র্যাক্ট করতে চান। সাধারণত, আপনি ওয়েব পরিষেবা থেকে পাওয়া উত্তর পার্স করতে এবং শুধুমাত্র আপনার আগ্রহের ভ্যালু এক্সট্র্যাক্ট করতে চাইবেন।

আপনি যে পার্সিং স্কিম ব্যবহার করেন তা নির্ভর করে আপনি JSON-এ আউটপুট ফেরত দিচ্ছেন কিনা তার উপর। JSON রেসপন্স, আগে থেকেই Javascript অবজেক্টের ফর্মে থাকার কারণে, ক্লায়েন্টের Javascript-এর মধ্যেই প্রসেস করা যেতে পারে।