במסמך הזה מוסבר איך להשתמש ב-Custom Search API בפורמט JSON.
שליחת בקשה
REST, או Representational State Transfer, ב-Custom Search API בפורמט JSON שונה קצת מממשקי ה-API בארכיטקטורת REST הרגילים. במקום לספק גישה למשאבים, ה-API מספק גישה לשירות. לכן, ה-API מספק URI יחיד שפועל כנקודת הקצה של השירות.
כדי לאחזר תוצאות של חיפוש מסוים, שולחים בקשת HTTP GET ל-URI שלו. אתם מעבירים את פרטי בקשת החיפוש כפרמטרים של שאילתה. הפורמט של ה-URI של Custom Search API בפורמט JSON הוא:
https://www.googleapis.com/customsearch/v1?[parameters]
בכל בקשת חיפוש צריך לכלול שלושה פרמטרים של שאילתה ([parameters]):
מפתח API – משתמשים בפרמטר השאילתה
keyכדי לזהות את האפליקציה.- מזהה של Programmable Search Engine – משתמשים ב-
cxכדי לציין את Programmable Search Engine שבו רוצים להשתמש כדי לבצע את החיפוש הזה. צריך ליצור את מנוע החיפוש באמצעות לוח הבקרה. הערה: מזהה מנוע החיפוש (cx) יכול להיות בפורמט שונה (למשל, 8ac1ab64606d234f1).
- מזהה של Programmable Search Engine – משתמשים ב-
שאילתת חיפוש – משתמשים בפרמטר השאילתה
qכדי לציין את ביטוי החיפוש.
כל שאר הפרמטרים של השאילתה הם אופציונליים.
הנה דוגמה לבקשה שמחפשת הרצאות ב-Programmable Search Engine לבדיקה:
GET https://www.googleapis.com/customsearch/v1?key=INSERT_YOUR_API_KEY&cx=017576662512468239146:omuauf_lfve&q=lecturesפרמטרים של שאילתה
יש שני סוגים של פרמטרים שאפשר להעביר בבקשה:
- פרמטרים ספציפיים ל-API – מגדירים את מאפייני החיפוש, כמו ביטוי החיפוש, מספר התוצאות, השפה וכו'.
- פרמטרים של שאילתה רגילים – מגדירים היבטים טכניים של הבקשה, כמו מפתח ה-API.
כל ערכי הפרמטרים צריכים להיות מקודדים בכתובת ה-URL.
פרמטרים של שאילתות ספציפיות ל-API
פרמטרים של בקשות שחלים ספציפית על Custom Search API בפורמט JSON ומגדירים את בקשת החיפוש מסוכמים בחומר העזר.
פרמטרים רגילים של שאילתות
הפרמטרים של שאילתות שרלוונטיים לכל הפעולות של Custom Search API בפורמט JSON מפורטים ברשימת הפרמטרים של המערכת.
נתוני התגובה
אם הבקשה מצליחה, השרת משיב עם קוד סטטוס 200 OK של HTTP ונתוני התשובה בפורמט JSON. אפשר לחפש את מבנה הנתונים של התגובה בחומר העזר.
נתוני התגובה הם אובייקט JSON שכולל שלושה סוגים של מאפיינים:
- מטא-נתונים שמתארים את החיפוש המבוקש (ואולי גם בקשות חיפוש קשורות)
- מטא-נתונים שמתארים את Programmable Search Engine
- תוצאות חיפוש
לתיאור מפורט של כל מאפיין, עיינו בחומר העזר.
מטא-נתונים של בקשת החיפוש
המטא-נתונים של החיפוש כוללים:
- המאפיין
url, שמכיל מידע על תבנית OpenSearch ששימשה לתוצאות שהוחזרו בבקשה הזו. - המאפיין
queries, שהוא מערך של אובייקטים שמתארים את המאפיינים של חיפושים אפשריים. השם של כל אובייקט במערך הוא השם של תפקיד שאילתה ב-OpenSearch או אחד משני התפקידים בהתאמה אישית שמוגדרים על ידי ה-API הזה:previousPageו-nextPage. אובייקטים אפשריים של תפקידי שאילתה כוללים:-
request: מטא-נתונים שמתארים את השאילתה של קבוצת התוצאות הנוכחית. - התפקיד הזה תמיד מופיע בתשובה.
- זה תמיד מערך עם רכיב אחד בלבד.
-
nextPage: מטא-נתונים שמתארים את השאילתה שצריך להשתמש בה בדף התוצאות הבא.- התפקיד הזה לא קיים אם התוצאות הנוכחיות הן הדף האחרון. הערה: ה-API הזה מחזיר רק עד 100 התוצאות הראשונות.
- כשהוא קיים, הוא תמיד מערך עם רכיב אחד בלבד.
-
previousPage: מטא-נתונים שמתארים את השאילתה שצריך להשתמש בה כדי לקבל את דף התוצאות הקודם.- לא מופיע אם התוצאות הנוכחיות הן הדף הראשון.
- כשהוא קיים, הוא תמיד מערך עם רכיב אחד בלבד.
-
מטא-נתונים של מנוע החיפוש
המאפיין context מכיל מטא-נתונים שמתארים את מנוע החיפוש שבו בוצעה שאילתת החיפוש. הוא כולל את שם מנוע החיפוש וכל אובייקט של היבט שהוא מספק כדי לצמצם את החיפוש.
תוצאות חיפוש
המערך items מכיל את תוצאות החיפוש בפועל. תוצאות החיפוש כוללות את כתובת ה-URL, הכותרת וקטעי הטקסט שמתארים את התוצאה. בנוסף, הם יכולים להכיל מידע על תקציר תוצאת חיפוש מתקדם (rich snippet), אם רלוונטי.
אם תוצאות החיפוש כוללות נכס promotions, הוא מכיל קבוצה של מבצעים.
REST מ-JavaScript
אפשר להפעיל את Custom Search API בפורמט JSON באמצעות REST מ-JavaScript, באמצעות הפרמטר של השאילתה callback ופונקציית קריאה חוזרת. כך אפשר לכתוב אפליקציות מפותחות שמציגות נתונים של Programmable Search Engine בלי לכתוב קוד בצד השרת.
בדוגמה הבאה נעשה שימוש בגישה הזו כדי להציג את הדף הראשון של תוצאות החיפוש לשאילתה 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>