API চালু করতে REST ব্যবহার করুন

Custom Search JSON API কীভাবে ব্যবহার করতে হয় তা এই ডকুমেন্ট বর্ণনা করে।

একটি অনুরোধ জানান

Custom Search JSON API-তে REST বা Representational State Transfer, সাধারণ RESTful API-এর থেকে কিছুটা আলাদা। রিসোর্সে অ্যাক্সেস দেওয়ার পরিবর্তে, API কোনও পরিষেবায় অ্যাক্সেস দেয়। এর ফলে, API একটি একক URI প্রদান করে যা পরিষেবার এন্ডপয়েন্ট হিসেবে কাজ করে।

আপনি নির্দিষ্ট সার্চের জন্য ফলাফল পেতে, HTTP GET অনুরোধ এর URI-তে পাঠাতে পারেন। আপনি সার্চ অনুরোধের বিবরণ কোয়েরি প্যারামিটার হিসেবে পাস করেন। Custom Search JSON API URI-এর ফর্ম্যাট হল:

https://www.googleapis.com/customsearch/v1?[parameters]

প্রতিটি সার্চ অনুরোধের সাথে তিনটি কোয়েরি [parameters] থাকতে হবে:

  • API key - আপনার অ্যাপ্লিকেশন শনাক্ত করতে key কোয়েরি প্যারামিটার ব্যবহার করুন।

    • Programmable Search Engine আইডি - এই সার্চ করার জন্য আপনি যে Programmable Search Engine ব্যবহার করতে চান, সেটি নির্দিষ্ট করতে cx ব্যবহার করুন। সার্চ ইঞ্জিন কন্ট্রোল প্যানেল ব্যবহার করে তৈরি করতে হবে মনে রাখবেন: সার্চ ইঞ্জিন আইডি (cx) অন্য ফর্ম্যাটের হতে পারে (যেমন 8ac1ab64606d234f1)
  • সার্চ কোয়েরি - আপনার সার্চ এক্সপ্রেশন নির্দিষ্ট করতে q কোয়েরি প্যারামিটার ব্যবহার করুন।

অন্যান্য সব কোয়েরি প্যারামিটার হল ঐচ্ছিক।

এখানে একটি অনুরোধের উদাহরণ দেওয়া হল যা লেকচার-এর জন্য একটি টেস্ট Programmable Search Engine সার্চ করে:

GET https://www.googleapis.com/customsearch/v1?key=INSERT_YOUR_API_KEY&cx=017576662512468239146:omuauf_lfve&q=lectures

কোয়েরি প্যারামিটার

আপনার অনুরোধে দুই ধরনের প্যারামিটার পাস করতে পারবেন:

  • API-নির্দিষ্ট প্যারামিটার - আপনার সার্চের প্রপার্টি নির্ধারণ করে, যেমন সার্চ এক্সপ্রেশন, ফলাফলের সংখ্যা, ভাষা ইত্যাদি।
  • স্ট্যান্ডার্ড কোয়েরি প্যারামিটার - আপনার অনুরোধের প্রযুক্তিগত দিকগুলি সংজ্ঞায়িত করে, যেমন API কী।

সব প্যারামিটারের ভ্যালু URL এনকোড করা হতে হবে।

API-নির্দিষ্ট কোয়েরি প্যারামিটার

অনুরোধের প্যারামিটার যা বিশেষভাবে Custom Search JSON API-এর ক্ষেত্রে প্রযোজ্য এবং আপনার সার্চ অনুরোধকে সংজ্ঞায়িত করে, সেগুলি রেফারেন্স-এ সংক্ষিপ্ত করা হয়েছে।

স্ট্যান্ডার্ড কোয়েরি প্যারামিটার

সব Custom Search JSON API অপারেশনের ক্ষেত্রে প্রযোজ্য কোয়েরি প্যারামিটার সিস্টেম প্যারামিটার-এ ডকুমেন্ট করা আছে।

উত্তরের ডেটা

অনুরোধ সফল হলে, সার্ভার 200 OK HTTP স্ট্যাটাস কোড এবং JSON ফর্ম্যাটে রেসপন্স ডেটা সহ উত্তর দেয়। আপনি রেফারেন্স-এ রেসপন্স ডেটা স্ট্রাকচার খুঁজতে পারেন।

রেসপন্স ডেটা হল একটি JSON অবজেক্ট যাতে তিন ধরনের প্রপার্টি থাকে:

  • অনুরোধ করা সার্চ (এবং, সম্ভবত, সম্পর্কিত সার্চের অনুরোধ) বর্ণনা করে এমন মেটাডেটা
  • Programmable Search Engine-এর বিবরণ সহ মেটাডেটা
  • সার্চ ফলাফল

প্রতিটি প্রপার্টির বিস্তারিত বিবরণের জন্য, রেফারেন্স দেখুন।

সার্চ অনুরোধের মেটাডেটা

সার্চ মেটাডেটাতে এগুলি অন্তর্ভুক্ত থাকে:

  • url প্রপার্টি, যাতে এই অনুরোধে পাওয়া ফলাফলের জন্য ব্যবহৃত OpenSearch টেমপ্লেট সম্পর্কে তথ্য আছে।
  • queries প্রপার্টি, যা সম্ভাব্য সার্চের বৈশিষ্ট্য বর্ণনা করে এমন অবজেক্টের অ্যারে। অ্যারের প্রতিটি অবজেক্টের নাম হয় OpenSearch কোয়েরি রোলের নাম অথবা এই API দ্বারা সংজ্ঞায়িত দুটি কাস্টম রোলের মধ্যে একটি: previousPage এবং nextPage। সম্ভাব্য কোয়েরি রোল অবজেক্টের মধ্যে অন্তর্ভুক্ত হল:
    • request: বর্তমান ফলাফল সেটের জন্য কোয়েরি বর্ণনা করা মেটাডেটা।
    • এই ভূমিকা সবসময় উত্তরে উপস্থিত থাকে।
      • এটি সবসময় একটি মাত্র এলিমেন্ট সহ অ্যারে হয়।
      • nextPage: ফলাফলের পরবর্তী পৃষ্ঠার জন্য ব্যবহার করার কোয়েরি বর্ণনা করে এমন মেটাডেটা।
        • বর্তমান ফলাফল শেষ পৃষ্ঠায় থাকলে এই ভূমিকাটি উপস্থিত থাকে না। মনে রাখবেন: এই API শুধুমাত্র প্রথম ১০০টি ফলাফল দেখায়।
        • উপস্থিত থাকলে, এটি সবসময় একটি এলিমেন্ট সহ অ্যারে হয়।
    • previousPage: ফলাফলের আগের পৃষ্ঠার জন্য ব্যবহার করার কোয়েরি বর্ণনা করে এমন মেটাডেটা।
      • বর্তমান ফলাফল প্রথম পৃষ্ঠায় থাকলে এটি দেখানো হয় না।
      • উপস্থিত থাকলে, এটি সবসময় একটি এলিমেন্ট সহ অ্যারে হয়।

সার্চ ইঞ্জিন মেটাডেটা

context প্রপার্টিতে মেটাডেটা থাকে যা সার্চ কোয়েরি পারফর্ম করা সার্চ ইঞ্জিনকে বর্ণনা করে। এতে সার্চ ইঞ্জিনের নাম এবং সার্চ রিফাইন করার জন্য এটি প্রদান করে এমন যেকোনও ফেসট অবজেক্ট অন্তর্ভুক্ত থাকে।

সার্চ ফলাফল

items অ্যারেতে আসল সার্চ ফলাফল থাকে। সার্চ ফলাফলে URL, শীর্ষক এবং টেক্সট স্নিপেট থাকে যা ফলাফল বর্ণনা করে। এছাড়াও, প্রযোজ্য হলে, এতে রিচ স্নিপেট তথ্য থাকতে পারে।

সার্চ ফলাফলে promotions প্রপার্টি থাকলে, এতে এক সেট প্রোমোশন থাকে।

JavaScript থেকে REST

আপনি callback কোয়েরি প্যারামিটার এবং কলব্যাক ফাংশন ব্যবহার করে, জাভাস্ক্রিপ্ট থেকে REST ব্যবহার করে Custom Search JSON API কল করতে পারেন। এটি আপনাকে কোনও সার্ভার সাইড কোড না লিখেই Programmable Search Engine ডেটা দেখায় এমন রিচ অ্যাপ্লিকেশন লিখতে দেয়।

নিম্নলিখিত উদাহরণে লেকচার কোয়েরির জন্য সার্চ ফলাফলের প্রথম পৃষ্ঠা দেখাতে এই পদ্ধতি ব্যবহার করা হয়েছে:

<html>
<head>
<title>Custom Search JSON API Example</title>
</head>
<body>
    <div id="content"></div>
    <p id="demo"></p>
    <script>
    function hndlr(response) {
      if (response.items == null) {
        document.getElementById("demo").innerHTML +=`<h3> No Results Found </h3>`;
      } else {
        for (var i = 1; i < response.items.length; i++) {
          var item = response.items[i];
          // Make sure HTML in item.htmlTitle is escaped.
          document.getElementById("content").append(
            document.createElement("br"),
            document.createTextNode(item.htmlTitle)
          );
        }
      }
    }
    </script>
    <script src="https://www.googleapis.com/customsearch/v1?key=YOUR-KEY&cx=017576662512468239146:omuauf_lfve&q=lecture&callback=hndlr">
    </script>
  </body>
</html>