एपीआई शुरू करने के लिए REST का इस्तेमाल करना

इस दस्तावेज़ में, Custom Search JSON API के इस्तेमाल का तरीका बताया गया है.

अनुरोध करना

Custom Search JSON एपीआई में मौजूद REST या रिप्रज़ेंटेशनल स्टेट ट्रांसफ़र, आम तौर पर इस्तेमाल होने वाले REST से कुछ अलग होता है. यह एपीआई, संसाधनों का ऐक्सेस देने के बजाय किसी सेवा का ऐक्सेस देता है. इस वजह से, एपीआई एक ऐसा यूआरआई उपलब्ध कराता है जो सर्विस एंडपॉइंट के तौर पर काम करता है.

किसी खास खोज के नतीजे पाने के लिए, उसके यूआरआई पर एचटीटीपी GET अनुरोध भेजा जा सकता है. आप खोज अनुरोध का विवरण क्वेरी पैरामीटर के रूप में पास करते हैं. Custom Search JSON API यूआरआई का फ़ॉर्मैट यह है:

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

हर खोज अनुरोध के लिए, तीन क्वेरी [parameters] ज़रूरी हैं:

  • एपीआई पासकोड - अपने ऐप्लिकेशन की पहचान करने के लिए, 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

क्वेरी पैरामीटर

अनुरोध में, दो तरह के पैरामीटर इस्तेमाल किए जा सकते हैं:

  • एपीआई के हिसाब से खास पैरामीटर - अपनी खोज की प्रॉपर्टी तय करें, जैसे सर्च एक्सप्रेशन, नतीजों की संख्या, भाषा वगैरह.
  • स्टैंडर्ड क्वेरी पैरामीटर - अपने अनुरोध के तकनीकी पहलुओं को तय करें, जैसे कि एपीआई पासकोड.

सभी पैरामीटर वैल्यू, यूआरएल के कोड में बदली जानी चाहिए.

एपीआई के लिए खास क्वेरी पैरामीटर

ऐसे अनुरोध पैरामीटर जो खास तौर पर Custom Search JSON API पर लागू होते हैं और आपके खोज अनुरोध की जानकारी देते हैं, उनकी खास जानकारी रेफ़रंस में दी गई है.

स्टैंडर्ड क्वेरी पैरामीटर

सभी Custom Search JSON एपीआई की कार्रवाइयों पर लागू होने वाले क्वेरी पैरामीटर, सिस्टम पैरामीटर में दर्ज किए गए हैं.

जवाब का डेटा

अनुरोध पूरा होने पर, सर्वर 200 OK एचटीटीपी स्टेटस कोड और रिस्पॉन्स डेटा को JSON फ़ॉर्मैट में दिखाता है. रिस्पॉन्स डेटा स्ट्रक्चर को रेफ़रंस में देखा जा सकता है.

रिस्पॉन्स डेटा एक JSON ऑब्जेक्ट है, जिसमें तीन तरह की प्रॉपर्टी शामिल होती हैं:

  • अनुरोध की गई खोज की जानकारी देने वाला मेटाडेटा (और शायद मिलती-जुलती खोज के अनुरोध)
  • Programmable Search Engine के बारे में जानकारी देने वाला मेटाडेटा
  • खोज के नतीजे

हर प्रॉपर्टी की पूरी जानकारी के लिए, रेफ़रंस देखें.

खोज के अनुरोध का मेटाडेटा

खोज के मेटाडेटा में ये चीज़ें शामिल होती हैं:

  • url प्रॉपर्टी, जिसमें इस अनुरोध से मिले नतीजों के लिए इस्तेमाल किए गए OpenSearch टेंप्लेट के बारे में जानकारी है.
  • queries प्रॉपर्टी, जिसमें कई चीज़ों की जानकारी होती है. यह प्रॉपर्टी, संभावित खोजों की विशेषताओं के बारे में बताती है. अरे में हर ऑब्जेक्ट का नाम OpenSearch क्वेरी की भूमिका या इस एपीआई की ओर से तय की गई दो कस्टम भूमिकाओं में से किसी एक का नाम होता है: previousPage और nextPage. क्वेरी में दिए जा सकने वाले भूमिका ऑब्जेक्ट में, ये चीज़ें शामिल हो सकती हैं:
    • request: नतीजों के मौजूदा सेट की क्वेरी की जानकारी देने वाला मेटाडेटा.
      • यह भूमिका, रिस्पॉन्स में हमेशा मौजूद होती है.
      • यह हमेशा सिर्फ़ एक एलिमेंट वाली कलेक्शन होती है.
      • nextPage: नतीजों के अगले पेज पर इस्तेमाल करने के लिए क्वेरी के बारे में जानकारी देने वाला मेटाडेटा.
        • अगर मौजूदा नतीजे आखिरी पेज हैं, तो यह भूमिका मौजूद नहीं होती है. ध्यान दें: यह एपीआई सिर्फ़ पहले 100 नतीजों तक दिखाता है.
        • मौजूद होने पर, यह हमेशा सिर्फ़ एक एलिमेंट वाली अरे होती है.
    • previousPage: नतीजों के पिछले पेज पर इस्तेमाल करने के लिए क्वेरी के बारे में बताने वाला मेटाडेटा.
      • अगर मौजूदा नतीजे पहला पेज हैं, तो यह मौजूद नहीं होता है.
      • मौजूद होने पर, यह हमेशा सिर्फ़ एक एलिमेंट वाली अरे होती है.

सर्च इंजन का मेटाडेटा

context प्रॉपर्टी में, खोज क्वेरी करने वाले सर्च इंजन की जानकारी देने वाला मेटाडेटा मौजूद है. इसमें सर्च इंजन का नाम और खोज को बेहतर बनाने के लिए, इसके ज़रिए उपलब्ध होने वाले सभी फ़ेस्ट ऑब्जेक्ट शामिल होते हैं.

खोज के नतीजे

items कलेक्शन में, खोज के असल नतीजे शामिल होते हैं. खोज के नतीजों में, नतीजे की जानकारी देने वाले यूआरएल, टाइटल, और टेक्स्ट स्निपेट शामिल होते हैं. इसके अलावा, लागू होने पर, उनमें रिच स्निपेट की जानकारी भी शामिल हो सकती है.

अगर खोज के नतीजों में कोई promotions प्रॉपर्टी है, तो उसमें प्रमोशन का सेट भी शामिल होगा.

JavaScript से REST

JavaScript से REST का इस्तेमाल करके, Custom Search JSON एपीआई को शुरू किया जा सकता है. इसके लिए, callback क्वेरी पैरामीटर और कॉलबैक फ़ंक्शन का इस्तेमाल करें. इससे, आपको ऐसे शानदार ऐप्लिकेशन लिखने की सुविधा मिलती है जो सर्वर साइड कोड लिखे बिना ही Programmable Search Engine का डेटा दिखाते हैं.

नीचे दिए गए उदाहरण में, कार क्वेरी के लिए खोज नतीजों का पहला पेज दिखाने के लिए इस तरीके का इस्तेमाल किया गया है:

<html>
  <head>
    <title>Custom Search JSON API Example</title>
  </head>
  <body>
    <div id="content"></div>
    <script>
      function hndlr(response) {
      for (var i = 0; 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=cars&callback=hndlr">
    </script>
  </body>
</html>