Street View Static API ব্যবহার করার পেশাদার পদ্ধতি

HTTP ইন্টারফেসের একটি সংগ্রহ, Google Maps Platform স্ট্যাটিক ওয়েব API আপনার ওয়েবপেজে সরাসরি এম্বেড করার জন্য ছবি তৈরি করে।

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

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

Street View Static API একটি স্ট্যাটিক ওয়েব API-এর মতো কাজ করে, অন্যদিকে মেটাডেটা পরিষেবা একটি ওয়েব পরিষেবা হিসেবে কাজ করে। মেটাডেটা পরিষেবা সম্পর্কে আরও তথ্যের জন্য, Street View ছবির মেটাডেটা দেখুন।

স্ট্যাটিক ওয়েব API কী?

Google Maps Platform-এর স্ট্যাটিক ওয়েব API আপনাকে জাভাস্ক্রিপ্ট বা কোনও ডাইনামিক পেজ লোডিংয়ের প্রয়োজন ছাড়াই আপনার ওয়েবপেজে Google Maps-এর ছবি এম্বেড করতে দেয়। স্ট্যাটিক ওয়েব API, URL প্যারামিটারের উপর ভিত্তি করে ছবি তৈরি করে যা স্ট্যান্ডার্ড HTTPS অনুরোধ ব্যবহার করে পাঠানো হয়।

একটি সাধারণ Street View Static API অনুরোধের ফর্ম্যাট নিচে দেওয়া হল:

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

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

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

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

Street View Static API মেটাডেটা অনুরোধ নিম্নলিখিত ফর্মের হয়:

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

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

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

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

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

বিশেষ অক্ষর

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

সঠিক URL অক্ষরের সারসংক্ষেপ
সেট করুনঅক্ষরURL ব্যবহার
বর্ণসাংখ্যিক ক খ গ ঘ ঙ চ ছ জ ঝ ঞ ট ঠ ড ঢ ণ ত থ দ ধ ন প ফ ব ভ ম য র ল শ ষ স হ ড় ঢ় য় ং ঃ ঁ অ আ ই ঈ উ ঊ ঋ এ ঐ ও ঔ ক খ গ ঘ ঙ চ ছ জ ঝ ঞ ট ঠ ড ঢ ণ ত থ দ ধ ন প ফ ব ভ ম য র ল শ ষ স হ ড় ঢ় য় ং ঃ ঁ ০ ১ ২ ৩ ৪ ৫ ৬ ৭ ৮ ৯ টেক্সট স্ট্রিং, স্কিম ব্যবহার (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 ক্লায়েন্ট ইন্টারনেটে এবং সার্ভারে অনেক বেশি লোড দিতে পারে। এই বিভাগে API ক্লায়েন্টের জন্য পেশাদার পদ্ধতি রয়েছে। এইসব পেশাদার পদ্ধতি অনুসরণ করলে, API-এর অনিচ্ছাকৃত অপব্যবহারের কারণে আপনার অ্যাপ্লিকেশন ব্লক হওয়া এড়াতে সাহায্য করতে পারে।

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

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

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

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

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

মিনিটের শুরু ছাড়া, অন্যান্য সাধারণ সিঙ্ক্রোনাইজেশন টাইমকে টার্গেট করবেন না, যেমন ঘণ্টার শুরু এবং মধ্যরাতে প্রতিটি দিনের শুরু।

উত্তর প্রসেস করা হচ্ছে

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

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

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

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