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