Search API

ה-Search API אינו מבוסס IIIF, אלא מבוסס על ה-API של מוצר הגילוי והחיפוש שהספרייה הלאומית משתמשת - Primo מבית חברת Exlibris.

להלן נסקור את מתודת Brief Search, המתודה הפופולארית ביותר ב-API. התיעוד המלא של המתודה נמצא באתר המפתחים של Exlibris.

קלט

זהו הקלט למתודת ה-brief search:

http://primo.nli.org.il/PrimoWebServices/xservice/search/brief?institution={institutioncode}&loc=local,scope:({scopename})&query={query}&indx={startindex}&bulkSize={pagesize}&json={true/false}

institutioncode, scopename

הגדרת מרחב החיפוש שבו רוצים לחפש.

לדוגמה, ערך ברירת המחדל - "NNL" בשני השדות - יאפשר לכם לחפש במרחב שכולל את מרבית פריטי הספרייה הלאומית.
אבל, אם ברצונכם לחפש רק על מפות, לדוגמה, עליכם לציין NNL ב-institutioncode ו-NNL_MAPS_JER ב-scopename.

שימו לב! אין בהכרח הדבר כי מידע שקיים במרחב חיפוש פרטי (לדוגמה, NNL_MAPS_JER) יהיה כלול במרחב ברירת המחדל.
על כן, במידה ואתם עובדים על אוסף ספציפי, יש להשתמש בפרטי מרחב החיפוש שלו.

בפרסום של כל אוסף בספרייה הלאומית מפורטים גם ערכי ה-institutioncode,scopename הנדרשים כדי להגיע אליו.

query

הגדרת שאילתא.

שדה זה הינו שדה חוזר, כלומר ניתן לציין אותו מספר פעמים, מה שיגרום להרצת כל אחת מהשאילתות (כל query הוא שאילתא) עם AND ביניהן.

שדה זה מקבל שלישיית ערכים, המופרדת בפסיק:

field,precision_operator,value

field

קוד השדה עליו רוצים לבצע שאילתא.
ניתן לציין any - כדי לחפש על כל השדות המאונדקסים.

קודי שדות אפשריים לחיפוש:

• any - חיפוש בכל השדות המאונדקסים
• title - כותר/שם הפריט
• desc- תיאור הפריט
• creator- יוצר הפריט
• sub- נושא הפריט
• שדה תאריך - קיים שדה תאריך לרשומה  אך כמובן אין טעם לחפש עליו תאריך ספציפי, אלא טווח תאריכים. לכן, ישנם שני שדות חיפוש "מיוחדים" בשם dr_s ו-dr_e (שהם date_range_start ו-date_range_end בהתאמה) עליהם יש לחפש עם קירוב exact. ראו דוגמה בהמשך.

precision operator

סוג הקירוב שרוצים לבצע בשאילתא:

• contains - חיפוש שדה שמכיל את הערך שאתם מספקים בפרמטר value (מילה שלמה מוכלת בשדה)
• exact - חיפוש שדה ששווה בדיוק לערך שאתם מספקים בפרמטר value

value

הערך אותו מחפשים. לדוגמה, Jerusalem.

ניתן להשתמש ב-operators כאן, לדוגמה: Jerusalem OR Tel Aviv

דוגמה לשאילתות

דוגמה לשימושים רגילים בשאילתות:

query=any,contains,Jerusalem
query=title,contains,Jerusalem OR Tel Aviv
query=title,contains,Jerusalem OR Tel Aviv&query=creator,contains,Ben Gurion OR Sharet

דוגמה לשאילתא של טווח תאריכים (בין 1.1.2017 ל-31.12.2017):

query=dr_s,exact,20170101&query=dr_e,exact,20171231

indx, bulksize

פרמטרים לדפדוף בתוצאות.
indx - פרמטר שמציין אינדקס הרשומה הראשונה שתחזור. כעקרון מתחילים עם 1.
bulksize - פרמטר שמציין את מספר הרשומות שיחזרו בחיפוש, לדוגמה 50.

כדי לדפדף לדף הבא, נחזור על אותה השאילתא עם indx=51 ו-bulksize=50, כדי לקבל את התוצאה ה-51 עד ה-100.

ה-Search API מוגן בבקרת הצפה על-ידי ה-Firewall שלנו, אנא הימנעו מדפדוף רציף על כל התוצאות.

json

הגדרת פורמט הפלט:

• TRUE - הפלט יהיה בפורמט JSON
• FALSE - הפלט יהיה בפורמט XML

שדה זה הינו רשות. במידה ולא מציינים אותו, ברירת המחדל היא XML.

סינון על השאילתות

ניתן לבצע סינון על השאילתות באמצעות סט המסננים הרלוונטי לאותה השאילתא.
כלומר, התהליך הוא כלהלן:

• יש לבצע חיפוש ראשון
• יש לנתח את תוצאות החיפוש וכן את רשימת המסננים והערכים שלהם (FACETSLIST)
• יש לבצע חיפוש נוסף עם ציון המסנן וערך לסינון בו כפרמטר שאילתא.
  יש לנתח את תוצאות החיפוש וכן את רשימת המסננים והערכים שלהם מחדש
  (וחוזר חלילה)

פלט

מבנה הפלט הוא:

• FACETLIST - רשימת המסננים הקיימים עבור תוצאות החיפוש של שאילתא זו לרבות הערכים האפשריים לסינון בהם
• DOCSET - רשימת כל הפריטים (DOCs) העונים על תוצאות החיפוש

FACETLIST

בדוגמה זו, ל-3300 פריטים מתוצאות החיפוש יש סיווג של שפה (lang), כאשר 2000 פריטים הם עם סיווג עברית ו-1300 הם עם סיווג צרפתית (יתכן כי לפריט יש סיווג של שתי השפות ואז הוא יכלל בספירה בשני ה-values).
כדי להפעיל מסנן, יש לשרשר הגדרת שאילתא ל-URL באופן הבא (לדוגמה, נבחר בסינון על פריטים בשפה העברית):

query=facet_lang,exact,heb

• קוד המסנן תמיד מקבל את הקידומת _facet
• לעולם חובה להשתמש ב-precision_operator = exact 
• לא ניתן לסנן אם לא עשינו שאילתא רגילה (השתמשנו ב-query על קוד שדה רגיל)

DOCSET

אלמנט זה מכיל את תוצאות החיפוש.

ב-attribute בשם TOTALHITS תוכלו לראות כמה תוצאות חיפוש חזרו.
בתוך האלמנט יש מערך של DOC המסודרים לפי ranking, אשר כל אחד מהם מכיל פריט אחד.
כדי לשלוף את ה-DOC באמצעות Presentation API, יש לקחת את המזהה שלו (הנקרא DOCID או recordid)

ה-DOCID נמצא בנתיב הבא:

DOC => PrimoNMBib => record => control =>recordid

יש לספק ערך זה בפרמטר identifier ב-Presentation API.

דוגמאות שימוש

חיפוש פריטים המכילים את הכותרת "ירושלים" בעברית:

IIIF Collections

אנו מספקים נקודת גישה נוספת למאגרים שלנו - IIIF Collections המקיפים את כל הקישורים ל-Presentation API לפריטים במאגרים שלנו, בחתך אוסף.
לחצו כאן כדי להגיע ל-Root IIIF Collection שלנו.