অনুরোধের প্যারামিটার

এই ডকুমেন্টে Places Aggregate API-এর অনুরোধ প্যারামিটার বর্ণনা করা হয়েছে এবং এতে এই পরিষেবা ব্যবহারের জন্য ইনসাইট ও পেশাদার পদ্ধতি অন্তর্ভুক্ত রয়েছে।

Places Aggregate API আপনাকে বেশ কিছু গুরুত্বপূর্ণ ফাংশন পারফর্ম করতে দেয়:

• জায়গা গণনা করা: নির্দিষ্ট মাপকাঠি পূরণ করে এমন জায়গার সংখ্যা নির্ধারণ করুন, যেমন লোকেশনের ধরন, অপারেটিং স্ট্যাটাস, প্রাইস লেভেল ও রেটিং।
• জায়গার বিবরণ ফিরিয়ে আনা: নির্দিষ্ট ফিল্টার পূরণ করে এমন জায়গার নাম পান, তারপর Places API ব্যবহার করে আরও বিস্তারিত তথ্য পান।
• ফ্লেক্সিবল ফিল্টারিং: সঠিক এগ্রিগেট পেতে বিস্তারিত ফিল্টার প্রয়োগ করুন। উপলভ্য ফিল্টারের মধ্যে এগুলি অন্তর্ভুক্ত:
  • ভৌগোলিক অঞ্চল (বৃত্ত, অঞ্চল বা কাস্টম বহুভুজ)
  • জায়গার ধরন
  • অপারেটিং স্ট্যাটাস
  • দামের লেভেল
  • রেটিংয়ের রেঞ্জ

প্রয়োজনীয় প্যারামিটার

এই বিভাগে Places Aggregate API-তে অনুরোধ করার সময় প্রয়োজনীয় প্যারামিটারগুলি সম্পর্কে বলা হয়েছে। প্রতিটি অনুরোধে নিম্নলিখিত তথ্য থাকতে হবে:

• এক ধরনের ইনসাইট।
• লোকেশন ফিল্টার ও ধরন ফিল্টার।

ইনসাইটের ধরন

আপনি যে ধরনের ইনসাইট গণনা করতে চান তা নির্দিষ্ট করে। নিম্নলিখিত ইনসাইট এর ধরন কাজ করে:

• INSIGHT_COUNT: ফিল্টার সংক্রান্ত মাপকাঠি ম্যাচ করে এমন জায়গার সংখ্যা রিটার্ন করে।
• INSIGHT_PLACES: ফিল্টার সংক্রান্ত মানদণ্ড অনুযায়ী ম্যাচ করা প্লেস আইডি রিটার্ন করে।

মনে রাখবেন: আপনি INSIGHT_PLACES বেছে নিলে, Places Aggregate API শুধুমাত্র তখনই প্লেস আইডি রিটার্ন করে, যখন count-এর মান ১০০ বা তার কম হয়।

ফিল্টার

জায়গা ফিল্টার করার জন্য মানদণ্ড নির্দিষ্ট করে। আপনাকে কমপক্ষে LocationFilter ও TypeFilter উল্লেখ করতে হবে।

লোকেশন ফিল্টার

লোকেশন ফিল্টারে নিম্নলিখিত ধরনের মধ্যে যেকোনও একটি থাকতে পারে:

• circle: কেন্দ্র ও ব্যাসার্ধ সহ বৃত্ত হিসেবে কোনও এলাকা নির্ধারণ করে।
• region: কোনও এলাকাকে অঞ্চল হিসেবে সংজ্ঞায়িত করে।
• customArea: কাস্টম পলিগন হিসেবে কোনও এলাকাকে সংজ্ঞায়িত করে।

গুরুত্বপূর্ণ: যেকোনও লোকেশন ফিল্টারের ক্ষেত্রফল অবশ্যই ১৫৫৬.৮৬ বর্গ মিটার (ছোট শহরের ব্লকের আনুমানিক সাইজ) থেকে ২ ট্রিলিয়ন বর্গ মিটারের (আলাস্কার আনুমানিক সাইজ) মধ্যে হতে হবে। এই রেঞ্জের বাইরের এরিয়া সহ অনুরোধ করলে INVALID_ARGUMENT এরর

মনে রাখবেন: পার্ক বা এয়ারপোর্টের মতো আগে থেকে নির্ধারিত বহুভুজাকার সীমানা সহ এন্টিটির ক্ষেত্রে, এন্টিটিকে সার্চ এরিয়ার মধ্যে আছে বলে বিবেচনা করা হয় যদি এর বহুভুজের কোনও অংশ আগে থেকে নির্ধারিত সার্চ এরিয়ার (বৃত্ত, অঞ্চল বা কাস্টম বহুভুজ) সাথে ইন্টারসেক্ট করে। The এনটিটির সেন্টার পয়েন্ট সার্চ এরিয়ার মধ্যে থাকার প্রয়োজন নেই।

সার্কেল করুন

আপনি নিজের ভৌগোলিক এলাকা বৃত্ত হিসেবে বেছে নিলে, আপনাকে center ও radius দিতে হবে। center অক্ষাংশ ও দ্রাঘিমাংশ অথবা বৃত্তের কেন্দ্রস্থলের প্লেস আইডি হতে পারে। এই পদ্ধতি আপনার নির্ধারিত বৃত্তাকার অঞ্চলের উপর ভিত্তি করে সুনির্দিষ্ট এবং সঠিক ফিল্টারিংয়ের সুবিধা দেয়।

• center:
  • latLng: বৃত্তের কেন্দ্রের অক্ষাংশ ও দ্রাঘিমাংশ। অক্ষাংশ অবশ্যই -৯০ থেকে ৯০-এর মধ্যে কোনও সংখ্যা হতে হবে, যার মধ্যে এই সংখ্যাগুলিও অন্তর্ভুক্ত। দ্রাঘিমাংশ অবশ্যই -১৮০ থেকে ১৮০-এর মধ্যে কোনও সংখ্যা হতে হবে।
  • place: বৃত্তের কেন্দ্রের প্লেস আইডি। মনে রাখবেন, শুধুমাত্র point places কাজ করে। এই স্ট্রিংটি অবশ্যই places/ প্রিফিক্স দিয়ে শুরু হতে হবে।
• radius: মিটারে বৃত্তের ব্যাসার্ধ। এই সংখ্যাটি অবশ্যই পজিটিভ হতে হবে।

অঞ্চল

place প্যারামিটারে একটি প্লেস আইডি পাস করে আপনার এলাকাকে একটি অঞ্চল হিসেবে সংজ্ঞায়িত করুন। প্লেস আইডি একটি ভৌগোলিক অঞ্চলকে (যেমন, একটি বহুভুজ দ্বারা উপস্থাপিত অঞ্চল) উপস্থাপন করে। যেমন, ট্যাম্পা, ফ্লোরিডার প্লেস আইডি হল places/ChIJ4dG5s4K3wogRY7SWr4kTX6c। মনে রাখবেন যে সব জায়গার আইডিতে সুনির্দিষ্ট জ্যামিতি থাকে না এবং এইসব ক্ষেত্রে Places Aggregate API একটি 400 ত্রুটি কোড সহ একটি মেসেজ দেখায় যা নির্দেশ করে যে অঞ্চলটি কাজ করে না। এছাড়াও, জটিল ভৌগোলিক অঞ্চলের ক্ষেত্রে, ইন্টার্নাল প্রসেসিং অপ্টিমাইজেশনের ফলে অঞ্চলের (২-৩% পর্যন্ত) সামান্য বেশি আনুমানিক পরিমাপ হতে পারে যা অঞ্চলটিকে উপস্থাপন করে।

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

বিতর্কিত অঞ্চল কীভাবে শনাক্ত করা হয় সেই সম্পর্কে আরও তথ্য পেতে, দেশের সীমান্ত ও নাম বোঝা দেখুন।

গুরুত্বপূর্ণ: Google নিম্নলিখিত ধরনের অঞ্চলের অন্তর্গত নির্দিষ্ট কিছু প্লেস আইডি সাপোর্ট করে না:

• অঞ্চলের ধরনগুলি এত বড় যে এর ফলে উচ্চ লেটেন্সি হয়।
• অঞ্চলের ধরন যা এতটাই ছোট যে তা গোপনীয়তা সংক্রান্ত সম্মতিকে লঙ্ঘন করে।

কোনও প্লেস আইডি কাজ করে না এমন প্লেসের ধরনকে প্রতিনিধিত্ব করে কিনা তা নির্ধারণ করতে, জিওকোডিং API অনুরোধে প্লেস ID পাস করুন। উত্তরে type অ্যারে অন্তর্ভুক্ত থাকে যা প্লেস আইডির সাথে সম্পর্কিত জায়গার ধরন তালিকাভুক্ত করে, যেমন locality, neighborhood বা country। কোনও জায়গার ধরন এই তালিকার সাথে ম্যাচ করলে, সেটি অঞ্চল ফিল্টারিংয়ের জন্য বাতিল করা হবে। এর যেকোনও ধরন এই তালিকার সাথে ম্যাচ করলে, সেটি অঞ্চল ফিল্টারিংয়ের জন্য বাতিল করা হবে।

যেসব জায়গার ধরন কাজ করে না তার মধ্যে রয়েছে:

• establishment: সাধারণত এমন কোনও জায়গাকে বোঝায় যা এখনও শ্রেণীবদ্ধ করা হয়নি।
• intersection: একটি বড় ইন্টারসেকশনকে নির্দেশ করে, সাধারণত দুটি বড় রাস্তার।
• subpremise: প্রাঙ্গণ লেভেলের নিচে কোনও ঠিকানাযোগ্য এন্টিটি নির্দেশ করে, যেমন অ্যাপার্টমেন্ট, ইউনিট বা স্যুট।

মনে রাখবেন: উপরে তালিকাভুক্ত নয় এমন কিছু জায়গাও প্রত্যাখ্যান করা হতে পারে, যদি সেগুলিতে ভালভাবে সংজ্ঞায়িত বহুভুজ জ্যামিতি না থাকে। এটি সাধারণত neighborhood, locality, sublocality এবং এর সংখ্যাযুক্ত ভেরিয়েন্টের (sublocality_level_1, sublocality_level_2, sublocality_level_3, sublocality_level_4) মতো ধরনের ক্ষেত্রে বেশি দেখা যায়। এই ধরনের ক্ষেত্রে ৪০০ ত্রুটি কোড দেখানো হয়।

কাস্টম এরিয়া

অক্ষাংশ ও দ্রাঘিমাংশ স্থানাঙ্ক ব্যবহার করে কাস্টম বহুভুজের ক্ষেত্রফল নির্ধারণ করে।

গুরুত্বপূর্ণ: বহুভুজের শীর্ষবিন্দুকে সংজ্ঞায়িত করা কোঅর্ডিনেটগুলিকে অবশ্যই ঘড়ির কাঁটার বিপরীত ক্রমে তালিকাভুক্ত করতে হবে। এটি পলিগনকে সংজ্ঞায়িত করার জন্য ইন্ডাস্ট্রি স্ট্যান্ডার্ড কনভেনশন মেনে চলে, যেখানে ঘড়ির কাঁটার বিপরীত দিক থেকে ক্রম নির্দেশ করে যে পলিগনের অভ্যন্তরীণ অংশটি সীমানার প্রান্তের বাম দিকে অবস্থিত।

গুরুত্বপূর্ণ: কাস্টম এরিয়াতে অবশ্যই ৭০০০ বা তার কম ভার্টেক্স থাকতে হবে।

কাস্টম বহুভুজ আঁকতে এবং সেইসব কোঅর্ডিনেট অনুরোধে লিখতে, আপনি https://geojson.io/ লিঙ্কে যেতে পারেন। একটি বহুভুজ-এ অবশ্যই কমপক্ষে ৪টি কোঅর্ডিনেট থাকতে হবে, যেখানে প্রথম ও শেষ কোঅর্ডিনেট একই হবে। প্রদান করা কোঅর্ডিনেটগুলির মধ্যে অন্তত ৩টি অনন্য হতে হবে।

পরপর একই কোঅর্ডিনেট থাকলে সেগুলিকে একটি কোঅর্ডিনেট হিসেবে বিবেচনা করা হবে। তবে, পরপর না থাকা ডুপ্লিকেট কোঅর্ডিনেট (প্রয়োজনীয় একই প্রথম ও শেষ কোঅর্ডিনেট ছাড়া) থাকলে সমস্যা হবে।

এছাড়াও, সংলগ্ন নয় এমন প্রান্তগুলি একে অপরের সাথে ছেদ করতে পারবে না এবং ১৮০ ডিগ্রি দৈর্ঘ্যের প্রান্তগুলি অনুমোদিত নয় (অর্থাৎ, সংলগ্ন শীর্ষবিন্দুগুলি অ্যান্টিপোডাল হতে পারবে না)।

যেমন:

"coordinates":[
   {
      "latitude":37.776,
      "longitude":-122.666
   },
   {
      "latitude":37.130,
      "longitude":-121.898
   },
   {
      "latitude":37.326,
      "longitude":-121.598
   },
   {
      "latitude":37.912,
      "longitude":-122.247
   },
   {
      "latitude":37.776,
      "longitude":-122.666
   }
]

টাইপ ফিল্টার

অন্তর্ভুক্ত বা বাদ দেওয়ার জন্য জায়গার ধরন নির্দিষ্ট করে। Places Aggregate API-তে কাজ করে এমন প্রাথমিক ও সেকেন্ডারি জায়গার ধরনের তালিকা দেখতে, Places API (নতুন)-এর জন্য জায়গার ধরন-এর অধীনে সারণী A দেখুন। আপনাকে অন্তত একটি includedTypes বা includedPrimaryTypes টাইপ উল্লেখ করতে হবে।

• includedTypes: অন্তর্ভুক্ত স্থানগুলির ধরনের তালিকা।
• excludedTypes: বাদ দেওয়া জায়গার ধরনের তালিকা।
• includedPrimaryTypes: অন্তর্ভুক্ত প্রাথমিক জায়গার ধরনের তালিকা।
• excludedPrimaryTypes: বাদ দেওয়া প্রাথমিক জায়গার ধরনের তালিকা।

টাইপ ফিল্টার ও জায়গার ধরন কীভাবে কাজ করে সেই সম্পর্কে আরও জানতে, টাইপ ফিল্টার সম্পর্কে আরও জানুন।

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

ঐচ্ছিক প্যারামিটার

এইসব ফিল্টার ঐচ্ছিক:

• operatingStatus: যোগ করা বা বাদ দেওয়া জায়গার স্ট্যাটাস নির্দিষ্ট করে। ডিফল্ট হিসেবে operatingStatus: OPERATING_STATUS_OPERATIONAL (একটি নির্দিষ্ট ভ্যালু) অনুযায়ী ফিল্টার করা হয়।
• priceLevels: অন্তর্ভুক্ত করার জন্য জায়গার দামের লেভেল নির্দিষ্ট করে। ডিফল্ট হিসেবে, কোনও প্রাইস লেভেল ফিল্টারিং প্রয়োগ করা হয় না এবং সব জায়গা (প্রাইস লেভেল সংক্রান্ত তথ্য নেই এমন জায়গা সহ) দেখানো হয়।
• ratingFilter: জায়গাগুলির রেটিংয়ের রেঞ্জ নির্দিষ্ট করে। ডিফল্ট হিসেবে কোনও ফিল্টারিং করা হয় না (ফলাফলে সব রেটিং অন্তর্ভুক্ত করা হয়)।

অপারেটিং স্ট্যাটাস

operatingStatus ফিল্টারের সাহায্যে, আপনি অপারেটিং স্ট্যাটাস যেমন OPERATIONAL বা TEMPORARILY_CLOSED-এর উপর ভিত্তি করে ফিল্টার করতে পারবেন। operatingStatus ফিল্টার এইভাবে কাজ করে:

• কোনও ফিল্টার প্রদান করা না হলে, শুধুমাত্র অপারেটিং স্ট্যাটাস OPERATING_STATUS_OPERATIONAL সহ জায়গাগুলি ফলাফলে অন্তর্ভুক্ত করা হয়।
• এক বা একাধিক ফিল্টার প্রদান করা হলে, আপনাকে অবশ্যই সঠিক অপারেটিং স্ট্যাটাস ভ্যালু (OPERATING_STATUS_OPERATIONAL, OPERATING_STATUS_PERMANENTLY_CLOSED, অথবা OPERATING_STATUS_TEMPORARILY_CLOSED) উল্লেখ করতে হবে।

দামের লেভেল

priceLevels ফিল্টারের সাহায্যে, আপনি মূল্য লেভেল অনুযায়ী জায়গা ফিল্টার করতে পারবেন। সঠিক প্রাইস লেভেল ভ্যালু হল: PRICE_LEVEL_FREE, PRICE_LEVEL_INEXPENSIVE, PRICE_LEVEL_MODERATE, PRICE_LEVEL_EXPENSIVE এবং PRICE_LEVEL_VERY_EXPENSIVE.

priceLevels ফিল্টারের আচরণ নিচে দেওয়া হল:

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

রেটিং ফিল্টার

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

• minRating: ব্যবহারকারীর দেওয়া গড় রেটিংয়ের সর্বনিম্ন মান (১.০ থেকে ৫.০-এর মধ্যে)।
• maxRating: ব্যবহারকারীর দেওয়া সর্বাধিক গড় রেটিং (১.০ থেকে ৫.০-এর মধ্যে)।

এছাড়াও, minRating ভ্যালু সবসময় maxRating ভ্যালুর থেকে কম বা সমান হতে হবে। minRating-এর মান maxRating-এর চেয়ে বেশি হলে, একটি INVALID_ARGUMENT সমস্যা দেখানো হয়।