Menggunakan REST untuk Memanggil API

Dokumen ini menjelaskan cara menggunakan API JSON Penelusuran Khusus.

Membuat permintaan

REST, atau Representational State Transfer, di Custom Search JSON API agak berbeda dengan REST tradisional. Alih-alih memberikan akses ke resource, API menyediakan akses ke layanan. Akibatnya, API tersebut menyediakan URI tunggal 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 kueri [parameters] 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 Control Panel 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

Catatan: Batas panjang permintaan penelusuran harus dalam 2.048 karakter.

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 JSON API Penelusuran Khusus didokumentasikan di Parameter Sistem.

Data respons

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

Data respons adalah objek JSON yang menyertakan tiga jenis properti:

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

Untuk deskripsi terperinci dari setiap properti, lihat referensi.

Telusuri metadata permintaan

Metadata penelusuran mencakup:

• Properti url, yang memiliki informasi tentang template OpenSearch yang digunakan untuk hasil yang ditampilkan dalam permintaan ini.
• queries, yang merupakan array objek yang menjelaskan karakteristik kemungkinan penelusuran. Nama setiap objek dalam array adalah nama dari 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.
    • Data ini selalu berupa array yang hanya berisi satu elemen.
    • nextPage: Metadata yang mendeskripsikan 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, kolom ini selalu berupa array yang hanya berisi 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, kolom ini selalu berupa array yang hanya berisi satu elemen.

Metadata mesin telusur

Properti context memiliki metadata yang mendeskripsikan mesin telusur yang melakukan kueri penelusuran. Objek ini mencakup nama mesin telusur, dan objek facet yang disediakannya untuk menyaring penelusuran.

Hasil penelusuran

Array items berisi hasil penelusuran sebenarnya. Hasil penelusuran mencakup URL, judul, dan cuplikan teks yang mendeskripsikan hasil tersebut. Selain itu, cuplikan dapat berisi informasi cuplikan kaya, 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, dengan menggunakan parameter kueri callback dan fungsi callback. Dengan begitu, Anda dapat menulis aplikasi lengkap yang menampilkan data Programmable Search Engine tanpa perlu menulis kode sisi server apa pun.

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

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