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 ব্যবহার
বর্ণসাংখ্যিক 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 ৯ টেক্সট স্ট্রিং, স্কিম ব্যবহার (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 রেসপন্স, আগে থেকেই JavaScript অবজেক্টের ফর্মে থাকার কারণে, ক্লায়েন্টে JavaScript-এর মধ্যেই প্রসেস করা যেতে পারে।