পরামিতি অনুরোধ

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

প্লেসেস অ্যাগ্রিগেট এপিআই আপনাকে বেশ কিছু গুরুত্বপূর্ণ কাজ সম্পাদন করতে দেয়:

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

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

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

• এক ধরনের অন্তর্দৃষ্টি।
• অবস্থান ফিল্টার এবং প্রকার ফিল্টার।

অন্তর্দৃষ্টির ধরণ

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

• INSIGHT_COUNT : ফিল্টার শর্তের সাথে মেলে এমন স্থানগুলির সংখ্যা ফেরত দেয়।
• INSIGHT_PLACES : ফিল্টার শর্তের সাথে মেলে এমন স্থান আইডিগুলো ফেরত দেয়।

দ্রষ্টব্য: আপনি যদি INSIGHT_PLACES নির্বাচন করেন, তাহলে Places Aggregate API শুধুমাত্র তখনই স্থানের আইডিগুলো ফেরত দেবে, যখন count ১০০ বা তার কম হবে।

ফিল্টার

স্থান ফিল্টার করার মানদণ্ড নির্দিষ্ট করে। ন্যূনতমপক্ষে, আপনাকে অবশ্যই LocationFilter এবং TypeFilter নির্দিষ্ট করতে হবে।

অবস্থান ফিল্টার

একটি অবস্থান ফিল্টার নিম্নলিখিত প্রকারগুলির মধ্যে একটি হতে পারে:

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

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

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

বৃত্ত

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

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

অঞ্চল

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

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

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

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

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

কোনো প্লেস আইডি একটি অসমর্থিত প্লেস টাইপের প্রতিনিধিত্ব করে কিনা তা নির্ধারণ করতে, একটি জিওকোডিং এপিআই অনুরোধে প্লেস আইডিটি পাস করুন। প্রতিক্রিয়াটিতে একটি 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
   }
]

টাইপ ফিল্টার

কোন ধরনের স্থান অন্তর্ভুক্ত বা বাদ দেওয়া হবে তা নির্দিষ্ট করে। প্লেসেস অ্যাগ্রিগেট এপিআই যে সকল প্রাথমিক ও মাধ্যমিক স্থানের ধরন সমর্থন করে, তার তালিকার জন্য প্লেসেস এপিআই (নতুন)-এর অধীনে থাকা ‘প্লেস টাইপস’- এর টেবিল এ দেখুন। আপনাকে অবশ্যই অন্তত একটি 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) উপর ভিত্তি করে ফিল্টার করতে পারেন। বৈধ মূল্য স্তরের মানগুলো হলো: 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 ত্রুটি ফেরত দেওয়া হয়।