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. Alih-alih memberikan akses ke resource, API memberikan akses ke layanan. Hasilnya, API menyediakan satu URI yang bertindak sebagai endpoint layanan.

Anda dapat mengambil hasil untuk penelusuran tertentu dengan mengirimkan permintaan HTTP GET 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 untuk 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 lectures:

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

Parameter kueri khusus API

Parameter permintaan yang berlaku khusus untuk Custom Search JSON API dan menentukan permintaan penelusuran Anda diringkas 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 mengetahui deskripsi mendetail 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 mungkin mencakup:
    • request: Metadata yang mendeskripsikan kueri untuk kumpulan hasil saat ini.
    • Peran ini selalu ada dalam respons.
      • Nilai 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 hingga 100 hasil pertama.
        • Jika ada, array ini selalu berupa array dengan hanya satu elemen.
    • previousPage: Metadata yang mendeskripsikan 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 menjelaskan mesin telusur yang menjalankan kueri penelusuran. Objek ini mencakup nama mesin telusur, dan objek faset yang disediakan untuk menyaring penelusuran.

Hasil penelusuran

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

Jika hasil penelusuran menyertakan properti promotions, properti tersebut 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. Dengan begitu, Anda dapat menulis aplikasi lengkap yang menampilkan data Programmable Search Engine tanpa menulis kode sisi server apa pun.

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>