Menggunakan REST untuk Memanggil API

Dokumen ini menjelaskan cara menggunakan Custom Search JSON API.

Buat permintaan

REST, atau Representational State Transfer, di Custom Search JSON API agak berbeda dengan RESTful API biasa. API menyediakan akses ke layanan, bukan memberikan akses ke resource. Akibatnya, API menyediakan satu URI yang berfungsi sebagai endpoint layanan.

Anda dapat mengambil hasil untuk penelusuran tertentu dengan mengirim permintaan GET HTTP ke URI-nya. Anda meneruskan detail permintaan penelusuran sebagai parameter kueri. Format untuk URI Custom Search JSON API adalah:

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

Tiga [parameters] kueri diperlukan dengan setiap permintaan penelusuran:

  • Kunci API - Gunakan parameter kueri key untuk mengidentifikasi aplikasi Anda.

    • ID Programmable Search Engine - Gunakan cx untuk menentukan Programmable Search Engine yang ingin Anda gunakan untuk melakukan penelusuran ini. Mesin telusur harus dibuat dengan Panel Kontrol Catatan: ID Mesin Telusur (cx) dapat memiliki format yang berbeda (misalnya, 8ac1ab64606d234f1)

  • Kueri penelusuran - Gunakan parameter kueri q untuk menentukan ekspresi penelusuran Anda.

Semua parameter kueri lainnya bersifat opsional.

Berikut adalah contoh permintaan yang menelusuri Programmable Search Engine pengujian untuk kuliah:

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

Parameter kueri

Ada dua jenis parameter yang dapat Anda teruskan dalam permintaan:

  • Parameter khusus API - menentukan properti penelusuran Anda, seperti ekspresi penelusuran, jumlah hasil, bahasa, dll.
  • Parameter kueri standar - menentukan aspek teknis permintaan Anda, seperti kunci API.

Semua nilai parameter harus dienkode ke URL.

Parameter kueri khusus API

Parameter permintaan yang berlaku khusus untuk Custom Search JSON API dan menentukan permintaan penelusuran Anda dirangkum dalam referensi.

Parameter kueri standar

Parameter kueri yang berlaku untuk semua operasi Custom Search JSON API didokumentasikan di Parameter Sistem.

Data respons

Jika permintaan berhasil, server akan merespons dengan kode status HTTP 200 OK dan data respons dalam format JSON. Anda dapat mencari struktur data respons di referensi.

Data respons adalah objek JSON yang mencakup tiga jenis properti:

  • Metadata yang mendeskripsikan penelusuran yang diminta (dan, mungkin, permintaan penelusuran terkait)
  • Metadata yang menjelaskan Programmable Search Engine
  • Hasil penelusuran

Untuk deskripsi mendetail dari setiap properti, lihat referensi.

Metadata permintaan penelusuran

Metadata penelusuran mencakup:

  • Properti url, yang memiliki informasi tentang template OpenSearch yang digunakan untuk hasil yang ditampilkan dalam permintaan ini.
  • Properti queries, yang merupakan array objek yang menjelaskan karakteristik kemungkinan penelusuran. Nama setiap objek dalam array adalah nama peran kueri OpenSearch atau salah satu dari dua peran kustom yang ditentukan oleh API ini: previousPage dan nextPage. Objek peran kueri yang memungkinkan mencakup:
    • request: Metadata yang mendeskripsikan kueri untuk kumpulan hasil saat ini.
    • Peran ini selalu ada dalam respons.
      • Ini selalu berupa array dengan hanya satu elemen.
      • nextPage: Metadata yang menjelaskan kueri yang akan digunakan untuk halaman hasil berikutnya.
        • Peran ini tidak ada jika hasil saat ini adalah halaman terakhir. Catatan: API ini hanya menampilkan maksimal 100 hasil pertama.
        • Jika ada, array ini selalu berupa array dengan hanya satu elemen.
    • previousPage: Metadata yang menjelaskan kueri yang akan digunakan untuk halaman hasil sebelumnya.
      • Tidak ada jika hasil saat ini adalah halaman pertama.
      • Jika ada, array ini selalu berupa array dengan hanya satu elemen.

Metadata mesin telusur

Properti context memiliki metadata yang mendeskripsikan mesin telusur yang melakukan kueri penelusuran. Ini mencakup nama mesin telusur, dan objek facet apa pun yang disediakan untuk menyaring penelusuran.

Hasil penelusuran

Array items berisi hasil penelusuran yang sebenarnya. Hasil penelusuran mencakup URL, judul, dan cuplikan teks yang menjelaskan hasil. Selain itu, halaman tersebut dapat berisi informasi rich snippet, jika berlaku.

Jika menyertakan properti promotions, hasil penelusuran akan berisi kumpulan promosi.

REST dari JavaScript

Anda dapat memanggil Custom Search JSON API menggunakan REST dari JavaScript, menggunakan parameter kueri callback dan fungsi callback. Hal ini memungkinkan Anda menulis aplikasi lengkap yang menampilkan data Programmable Search Engine tanpa menulis kode sisi server.

Contoh berikut menggunakan pendekatan ini untuk menampilkan halaman pertama hasil penelusuran untuk kueri lecture:

<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>