Bu belgede, Custom Search JSON API'nin nasıl kullanılacağı açıklanmaktadır.
İstekte bulunun
Custom Search JSON API'deki REST veya Representational State Transfer (Temsili Durum Aktarımı), normal RESTful API'lerden biraz farklıdır. API, kaynaklara erişim sağlamak yerine bir hizmete erişim sağlar. Bu nedenle API, hizmet uç noktası görevi gören tek bir URI sağlar.
Belirli bir aramanın sonuçlarını, URI'sine bir HTTP GET isteği göndererek alabilirsiniz. Arama isteğinin ayrıntılarını sorgu parametreleri olarak iletirsiniz. Custom Search JSON API URI'sinin biçimi şöyledir:
https://www.googleapis.com/customsearch/v1?[parameters]
Her arama isteğinde üç sorgu [parameters] gereklidir:
API anahtarı: Uygulamanızı tanımlamak için
keysorgu parametresini kullanın.- Programlanabilir Arama Motoru Kimliği: Bu aramayı gerçekleştirmek için kullanmak istediğiniz Programlanabilir Arama Motoru'nu belirtmek üzere
cxkullanın. Arama motoru, Denetim Masası ile oluşturulmalıdır. Not: Arama Motoru Kimliği (cx) farklı biçimde olabilir (ör. 8ac1ab64606d234f1).
- Programlanabilir Arama Motoru Kimliği: Bu aramayı gerçekleştirmek için kullanmak istediğiniz Programlanabilir Arama Motoru'nu belirtmek üzere
Arama sorgusu: Arama ifadenizi belirtmek için
qsorgu parametresini kullanın.
Diğer tüm sorgu parametreleri isteğe bağlıdır.
Aşağıda, test amaçlı bir Programlanabilir Arama Motoru'nda dersler için arama yapan bir istek örneği verilmiştir:
GET https://www.googleapis.com/customsearch/v1?key=INSERT_YOUR_API_KEY&cx=017576662512468239146:omuauf_lfve&q=lecturesSorgu parametreleri
İsteğinizde iletebileceğiniz iki tür parametre vardır:
- API'ye özgü parametreler: Arama ifadesi, sonuç sayısı, dil vb. gibi aramanızın özelliklerini tanımlar.
- Standart sorgu parametreleri: İsteğinizin teknik yönlerini (ör. API anahtarı) tanımlar.
Tüm parametre değerlerinin URL olarak kodlanması gerekir.
API'ye özgü sorgu parametreleri
Özellikle Custom Search JSON API için geçerli olan ve arama isteğinizi tanımlayan istek parametreleri, referans bölümünde özetlenmiştir.
Standart sorgu parametreleri
Tüm Custom Search JSON API işlemleri için geçerli olan sorgu parametreleri, Sistem Parametreleri bölümünde açıklanmıştır.
Yanıt verileri
İstek başarılı olursa sunucu, 200 OK HTTP durum kodu ve JSON biçimindeki yanıt verileriyle yanıt verir. Yanıt veri yapısını referans bölümünde bulabilirsiniz.
Yanıt verileri, üç tür özellik içeren bir JSON nesnesidir:
- İstenen aramayı (ve muhtemelen ilgili arama isteklerini) açıklayan meta veriler
- Programlanabilir Arama Motoru'nu açıklayan meta veriler
- Arama sonuçları
Her bir özelliğin ayrıntılı açıklaması için referans bölümüne bakın.
Arama isteği meta verileri
Arama meta verileri şunları içerir:
- Bu istekte döndürülen sonuçlar için kullanılan OpenSearch şablonu hakkında bilgi içeren
urlmülkü. queriesözelliği, olası aramaların özelliklerini açıklayan bir nesne dizisidir. Dizideki her nesnenin adı, bir OpenSearch sorgu rolünün adı veya bu API tarafından tanımlanan iki özel rolden biridir:previousPagevenextPage. Olası sorgu rolü nesneleri şunlardır:request: Mevcut sonuç kümesi için sorguyu açıklayan meta veriler.- Bu rol, yanıtta her zaman bulunur.
- Her zaman yalnızca bir öğe içeren bir dizidir.
nextPage: Sonraki sonuç sayfasında kullanılacak sorguyu açıklayan meta veriler.- Mevcut sonuçlar son sayfaysa bu rol mevcut değildir. Not: Bu API yalnızca ilk 100 sonucu döndürür.
- Mevcut olduğunda her zaman yalnızca bir öğe içeren bir dizidir.
previousPage: Önceki sonuç sayfası için kullanılacak sorguyu açıklayan meta veriler.- Mevcut sonuçlar ilk sayfaysa gösterilmez.
- Mevcut olduğunda her zaman yalnızca bir öğe içeren bir dizidir.
Arama motoru meta verileri
context mülkü, arama sorgusunu gerçekleştiren arama motorunu açıklayan meta verilere sahiptir. Arama motorunun adını ve aramayı hassaslaştırmak için sağladığı yönlü nesneleri içerir.
Arama sonuçları
items dizisi, gerçek arama sonuçlarını içerir. Arama sonuçlarında URL, başlık ve sonucu açıklayan metin snippet'leri yer alır. Ayrıca, uygunsa zengin snippet
bilgileri de içerebilirler.
Arama sonuçlarında promotions özelliği varsa bu özellik bir dizi promosyon içerir.
JavaScript'ten REST
callback sorgu parametresini ve bir geri çağırma işlevini kullanarak JavaScript'ten REST aracılığıyla Custom Search JSON API'yi çağırabilirsiniz. Bu sayede, sunucu tarafı kodu yazmadan Programlanabilir Arama Motoru verilerini gösteren zengin uygulamalar yazabilirsiniz.
Aşağıdaki örnekte, lecture sorgusu için arama sonuçlarının ilk sayfasını görüntülemek üzere bu yaklaşım kullanılmaktadır:
<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>