CLOSE ✕
Get in Touch
Thank you for your interest! Please fill out the form below if you would like to work together.

Thank you! Your submission has been received!

Oops! Something went wrong while submitting the form

National Library of Israel for Developers

Image API

Image API הוא ממשק RESTFul שמאפשר שליפת העתקים דיגיטליים מסוג תמונה וכן מידע אודותם.
תיעוד הממשק המלא נמצא כאן: http://iiif.io/api/image/2.1

למעשה, בכל פנייה מיוצרת עבורכם, tailor-made and on-the-fly, תמונה שעונה על בקשתכם!

תוכן העניינים

בעמוד זה תמצאו תיאור של שני השירותים הבאים:

הקדמה

לפני בקשת התמונה עליכם לבקש metadata אודות התמונה, באמצעות השירות Image Information (שירות המפורט בחלק השני של עמוד זה). שירות זה מספק מידע חשוב כמו גודל התמונה המקורית וכן מפרט מה ניתן לבקש מה-Image API ומה לא ניתן. לדוגמה, האם ניתן לבקש סיבוב (rotation) ואם כן איזה סוג (רק בכפולות של 90 או כל ערך), מה הגודל המקסימלי של תמונה שניתן לבקש וכו'.

אחר כך, כל שנותר לכם הוא לבקש את התמונה עצמה באמצעות השירות Image Request.
שימו לב! ישנן מגבלה גלובלית לגודל תמונה (פרמטר size) של 576 פיקסלים.
כדי להציג תמונה גדולה יותר, עליכם לבקש אותה ב-tiles. למעשה, אנו מעודדים אתכם להשתמש ב-tiles תמיד.
מה הרעיון של tiles? לפרוס אתהבקשה של התמונה ל-9 tiles (לדוגמה), כאשר כל tile זו בקשת נפרדת מה-Image API. גודל tile אידאלי הוא 256x256 פיקסלים. בקשת חיתוך התמונה ל-tile מתבצעת באמצעות שימוש בפרמטר region (ראו להלן).
משיכת תמונה גדולה באמצעות חלוקתה לתמונות קטנות (tiles) מאפשרת חוויית משתמש טובה יותר.

Image Request Service

קלט

הפנייה אליו נעשית באופן הבא:

http://iiif.nli.org.il/IIIFv21/{identifier}/{region}/{size}/{rotation}/{quality}.{format}

identifier

מזהה ההעתק הדיגיטלי שרוצים לגשת אליו.
בפועל, אתם תקבלו את ה-URL המלא של הגישה ל-Image API מוטמע בתול ה-Manifest כאשר פרמטר זה יהיה מצויין מראש.

region

האיזור של התמונה שאתם רוצים לקבל.
בדרך כלל תרצו לבקש אחד מהשניים:

  • full - לקבל בפלט את כל התמונה
  • x,y,w,h - ציון נקודה עפ"י פיקסלים (x,y) וממנה שטח נבחר בפיקסלים (w,h). דבר זה שימושי כאשר מבקשים tile התמונה.
    דוגמה: 0,0,250,250
  • pct:x,y,w,h - ציון נקודה (x,y) תוך שימוש באחוזים ולא בפיקסלים וממנה שטח נבחר באחוזים.
    דוגמה: pct:50,0,50,50 - משמעו להתחיל בנקודה שהיא באמצע רוחב התמונה (50%) אך בחלק העליון ביותר (0%), ומשם לקחת חצי מרוחב התמונה המקורי(50%) וחצי מאורך התמונה המקורי (50%)

size

מימדי התמונה שאתם רוצים לקבל (width,height).

אפשרויות נפוצות:

  • ,w - ציון רוחב התמונה המבוקש בלבד. המערכת תשמר את הפרופורציה של התמונה ותחליט מה הגובה באופן אוטומטי.
  • h, - ציון גובה התמונה המבוקש בלבד. המערכת תשמר את הפרופורציה של התמונה ותחליט מה הרוחב באופן אוטומטי.
  • w,h! - ציון גובה ורוחב התמונה תוך בקשה לשמור על פרופורציה (תו סימן קריאה). בפועל, תוחזר התמונה הגדולה ביותר שמימדיה קטנים או שווים למצויין בבקשה.

שימו לב! לא ניתן לבקש גדלים שחורגים מ-576 פיקסלים. לכן, יש לרנדר את הבקשה שלכם ע"י tiles באמצעות שימוש בפרמטר region (ראו הסבר כללי בתחילת עמוד זה)

rotation

סיבוב התמונה (במעלות) עם כיוון השעון
שימו לב! ניתן לבצע "מראה" ע"י הוספת ! לפני הערך של הסיבוב

  • 0 - ללא סיבוב
  • 90
  • 180
  • 270
  • 0! - ללא סיבוב תוך ביצוע "מראה"
  • 90! - סיבוב ב-90 מעלות + "מראה"

quality

האם רוצים לקבל את התמונה בצבעים המקוריים (default) או בצבעי אפור (gray).לרוב כמובן שתשתמשו ב-default.

format

פורמט התמונה שברצונכם לקבל. כיום אנחנו תומכים רק ב-JPG.

פלט

Stream של תמונה, כבקשתכם.

במקרה של שגיאה, תקבלו חיווי שגיאה (לדוגמה, HTTP Code 404 אם הפריט לא קיים או HTTP Code 403 אם אסורה הגישה לפריט בשל מגבלת זכויות יוצרים וכו') ובגוף התשובה יהיה XML בפורמט הבא:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<error>
<parameter>default_message</parameter>
<text>The referenced record does not exist in our database</text>
</error>

בדוגמה זו, שגיאה עבור גישה למזהה דף שאינו קיים במערכת.

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

שימוש ב-tiles

גודל tile מקובל הוא 256X256 פיקסלים תוך שמירה על פרופורציה (כלומר, אחת הפאות תהיה 256 והשנייה 256 או קטנה יותר, בהתאמה).
דוגמה לבקשה של תמונה גדולה בחלוקה ל-4 tiles (בדרך כלל תחלקו את הפריט שלכם ליותר tiles, זוהי רק דוגמה בסיסית):

http://iiif.nli.org.il/IIIFv21/FL7070748/pct:0,0,50,50/256,/0/default.jpg
http://iiif.nli.org.il/IIIFv21/FL7070748/pct:0,50,50,50/256,/0/default.jpg
http://iiif.nli.org.il/IIIFv21/FL7070748/pct:50,0,50,50/256,/0/default.jpg
http://iiif.nli.org.il/IIIFv21/FL7070748/pct:50,50,50/256,/0/default.jpg

דוגמאות נוספות

שימושים נוספים:

בקשת העתק דיגיטלי של פריט ברוחב 300 פיקסלים (גובה התמונה מחושב אוטומטית כדי לשמור על פרופורציה)

http://iiif.nli.org.il/IIIFv21/FL7070748/full/300,/0/default.jpg


בקשת העתק דיגיטלי של פריט בגודל מסגרת של 300x100 פיקסלים, תוך שמירה על פרופורציה (תו סימן קריאה). המשמעות היא, המערכת תחזיר את הפריט הגדול ביותר שניתן שלא עובר את הגודל 300x100 תוך שמירה על פרופורציה.

http://iiif.nli.org.il/IIIFv21/FL7070748/full/!300,100/0/default.jpg


בקשת העתק דיגיטלי של פריט בגודל מסגרת של 300x100 בדיוק (אין שמירה על פרופורציה).

http://iiif.nli.org.il/IIIFv21/FL7070748/full/300,100/0/default.jpg

Image Information Service

בקשה לקבלת מידע אודות התמונה.
התיעוד המלא לממשק נמצא ב: http://iiif.io/api/image/2.1/#image-information-request-uri-syntax.

קלט

http://iiif.nli.org.il/IIIFv21/{identifier}/info.json

עליכם לשאוב את המזהה של ההעתק הדיגיטלי מה-Manifest ולפנות באופן יזום אל שירות זה.

פלט

הפלט הוא JSON המפרט את כל המידע אודות התמונה, עפ"י התקן.
כאן נתעכב רק על השדות החשובים:

width, height

הבקשה שלכם לפרמטר region נשענת על הגודל המקורי של התמונה, שמצויין בשדות אלו.

profile

תחת מערך זה תמצאו כמה הגדרות חשובות, כמו:

שדות זכויות יוצרים

השדות הבאים הם שדות זכויות יוצרים, ומפורטים בתקן תחת: http://iiif.io/api/image/2.1/#rights-and-licensing-properties

license

שדה זה מתייחס למגבלות זכויות יוצרים ומגבלות חוזיות נוספות. השדה מכיל קישור לעמוד אודות תנאי השימוש בתמונה. שימו לב כי תנאי השימוש אינם זהים ביחס לכל התמונות. למשל: השימוש בתמונה עשוי להיות מוגבל לשימוש למטרות לא מסחריות בלבד או שימוש לצרכי הוראה ומחקר בלבד. במקרים אחרים ייתכן כי לא תחול מגבלה כלשהי על השימוש בתמונה. על המשתמש לבדוק שהשימוש המבוקש על ידו בתמונה תואם את תנאי השימוש. כמו כן יש להציג את הקישור לתנאי השימוש למשתמשי הקצה כך שיהיה לחיץ לגלישה.

logo

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

attribution

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

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

http://iiif.nli.org.il/IIIFv21/FL7070748/info.json