מדריך שליפה ממאגר סדרות
מבוא
מאגר סדרות – מאגר של סדרות עתיות (time series). לכל סדרה במאגר סדרות יש קוד סדרה (SERIES_CODE), שהוא מזהה ייחודי של אותה סדרה מסוג string.
סדרה עתית אף פעם לא באה "לבד" בפני עצמה, אלא תמיד באה יחד עם מטה דטה שמתאר אותה ועוזר לנו להבין מה הנתון מייצג. לדוגמה, הסדרה של שער החליפין היציג שקל-דולר:
| קוד/שם הסדרה | RER_USD_ILS | שער יציג דולר ארה"ב - שקל | |
| תדירות | D | יומי | |
| מטבע בסיס | USD | דולר ארה"ב | |
| מטבע נגדי | ILS | ש"ח | |
| יחידות מידה | ILS | ש"ח | |
| סוג נתון | OF00 | שער יציג | |
לערך של מאפיין מטה-דטה יש קוד מזהה, שבנוי מתווים מסוימים (אותיות גדולות באנגלית, מספרים וקו תחתון בלבד), ולצידו שם שמתאר את המשמעות שלו, שיכול להיות מוצג בעברית או באנגלית.
הסדרות במאגר מחולקות לעולמות תוכן שונים, כאשר לכל עולם תוכן יש מבנה שונה – אוסף מאפייני מטה דטה שרלוונטיים לאותו נושא כלכלי. למשל, בעולם התוכן של שערי חליפין (משם מגיעה סדרת שער החליפין היציג) קיימים המאפיינים "מטבע בסיס" ו-"מטבע נגדי", אך מאפיינים אלו לא בהכרח יהיו רלוונטיים לכל עולם תוכן. בעולם התוכן "שוק העבודה" אין את המאפיינים האלו, אבל כן יש מאפיינים אחרים כמו "קבוצת גיל", "מגדר" ו-"מספר שנות לימוד", שאינם רלוונטיים לשערי חליפין.
קיימים כמה מאפיינים כלליים שרלוונטיים לכל הסדרות, ולכן נמצא אותם בכל עולמות התוכן. המרכזיים שבהם: קוד ושם הסדרה, תדירות, סוג נתון ויחידות מידה.
שליפה של סדרה לא מתבצעת אף פעם "בפני עצמה" לפי הקוד המזהה בלבד. כל שליפה היא תמיד מתוך עולם תוכן מסוים, והנתונים מוחזרים יחד עם המטה דטה שמאפיין את הסדרה, בהתאם למבנה עולם התוכן (מאפייני המטה דטה הקיימים בו).
שליפת נתונים באמצעות API
שליפת הנתונים באמצעות REST API:
דוגמה לשליפה בסיסית:
חלק א': קידומת
חלק ב': מזהה עולם התוכן
חלק ג': פרמטרים נוספים לשליפה כגון סינונים (לפי קוד סדרה או לפי מאפייני מטה דטה נוספים), פורמט output רצוי, שפה וכיו"ב.
לעיתים קרובות, ניסיון שליפה של כל עולם התוכן ללא סינונים, יהיה כבד וגדול מדי – כתלות בעולם התוכן (בחלקם יש כמות גדולה מאוד של סדרות). לכן חשוב לדעת איך לעשות סינון ממוקד לסדרות שאנחנו רוצים, כפי שיפורט להלן.
בשלב ראשון, נניח שידוע לנו מזהה עולם התוכן שממנו אנחנו רוצים לשלוף, וידוע לנו המבנה שלו (כלומר ידוע לנו אילו מאפייני מטה דטה קיימים ומהי רשימת הערכים האפשריים לכל אחד מהם).
בהמשך, נראה כיצד ניתן לברר את הפרטים הנ"ל בפעם הראשונה אם אנחנו עדיין לא יודעים אותם, דרך ה-UI (ממשק סדרות).
ניתן להוסיף פרמטר GET בעל המבנה הבא:C[METADATA_COLUMN]=VAL1,VAL2,VAL3
כאשר:
-
METADATA_COLUMN – קוד מאפיין המטה דטה שאותו רוצים לסנן.
-
במקרה של קוד סדרה המאפיין נקרא SERIES_CODE, ונשים לב שלמרות שהוא מזהה ייחודי הסינון שלו מתבצע באותו תחביר כמו שאר המאפיינים.
-
-
VAL1,VAL2,VAL3 – רשימת ערכים שאותם נרצה לכלול. ניתן לכתוב ערך אחד או יותר מופרדים בפסיק. יש להשתמש בקודים באנגלית של הערכים (ולא בשמות שלהם בעברית או באנגלית).
-
את התווים "[" ו-"]" צריך לקודד ל-URL, כלומר לכתוב "%5B" או "%5D" בהתאמה.
ניתן להוסיף כמה פרמטרים כאלו (מופרדים ב-"&") וכך לסנן יותר ממאפיין אחד.
לדוגמה, כך נשלוף את כל הסדרות מעולם התוכן שערי חליפין (BOI.STATISTICS/EXR/1.0/) שבהן מטבע הבסיס (BASE_CURRENCY) הוא דולר או אירו (USD או EUR) וגם המטבע הנגדי הוא ש"ח (ILS):
| GET https://edge.boi.gov.il/FusionEdgeServer/sdmx/v2/data/dataflow/BOI.STATISTICS/EXR/1.0/?c%5BBASE_CURRENCY%5D=USD,EUR&c%5BCOUNTER_CURRENCY%5D=ILS&format=csv |
סינון תאריכים
כדי לסנן תאריכים, נשתמש בפרמטרים startPeriod או endPeriod לסינון תאריך התחלה או תאריך סיום בהתאמה. ניתן להשתמש בשניהם, או רק באחד מהם, או לא להשתמש באף אחד מהם (ואז יוחזרו כל התאריכים הקיימים).
את התאריכים ניתן להכניס בפורמט שנתי (YYYY), רבעוני (YYYY-QQ), חודשי (YYYY-MM) או יומי (YYYY-MM-DD).
לדוגמה, כך נסנן את השליפה הקודמת כך שתציג נתונים רק עד סוף רבעון 2 של 2020:
|
GET |
סינון מספר תצפיות
ניתן להגביל את מספר התצפיות שישלפו פר סדרה, באמצעות הפרמטרים lastNObservations ו/או firstNObservations, שמאפשרים לשלוף N תצפיות אחרונות או ראשונות לכל סדרה.
לדוגמה, כך ניתן לשלוף תצפית אחת אחרונה של כל אחת מהסדרות בעולם התוכן שע"ח:
| GET https://edge.boi.gov.il/FusionEdgeServer/sdmx/v2/data/dataflow/BOI.STATISTICS/EXR/1.0/?format=csv&lastNObservations=1 |
שפה
ניתן להשתמש בפרמטר labels כדי לבחור באיזה פורמט נקבל את מאפייני המטה דטה: רק קודים באנגלית (id), רק שמות (names), או גם וגם (both). ברירת המחדל היא id.
במקרה שבהם בחרנו לכלול שמות (כלומר באחת האופציות names או both), נשתמש בפרמטר locale לבחירת השפה – עברית (he) או אנגלית (en).
אם בוחרים בשפה העברית, יש להוסיף גם bom=include כדי שהעברית לא תצא משובשת.
לדוגמה, כך נשלוף תצפית אחרונה של כל אחת מהסדרות בעולם התוכן שער חליפין, בצירוף מטה דטה מלא בעברית (קוד + שם):
| GET https://edge.boi.gov.il/FusionEdgeServer/sdmx/v2/data/dataflow/BOI.STATISTICS/EXR/1.0/?format=csv&lastNObservations=1&labels=both&locale=he&bom=include |
פורמט output
ניתן לבחור פורמט לפלט שנקבל באמצעות הפרמטר format.
האופציה הכי מיידית וקלה לשימוש היא csv, כמו בכל הדוגמאות הקודמות. בפורמט זה הנתונים יוחזרו בצורת טבלה פשוטה עם עמודה של תאריך, עמודה של ערך, ועמודה נוספת לכל מאפיין מטה דטה (כולל קוד ו/או שם הסדרה) כאשר מאפייני המטה דטה למעשה חוזרים על עצמם לצד כל אחת מהתצפיות של הסדרה.
בשליפת כמות גדולה של נתונים, csv יכול להיות קצת כבד מדי, בגלל החזרתיות; במקרה כזה, פורמט פשוט נוסף שניתן להשתמש בו להקטנת הנפח הוא csv-ts. בפורמט זה, כל סדרה תופיע בשורה אחת (וכך המטה דטה שלה יופיע פעם אחת בלבד), כאשר התצפיות השונות יופיעו בעמודות. קודם יופיעו כל עמודות המטה דטה, ואחריהן תהיה עמודה לכל תצפית. מומלץ להשתמש בפורמט זה רק על קבוצת סדרות שהן באותה תדירות, כדי שהעמודות של התאריכים בתדירויות השונות לא יתערבבו אחד בשני, מכיוון שהתאריך מגיע בפורמט בהתאם לתדירות הסדרה (YYYY שנתי, YYYY-QQ רבעוני, YYYY-MM חודשי, YYYY-MM-DD יומי) והעמודות של התאריך, בהתאמה, יהיו נפרדות.
פורמטים נוספים שקיימים:
excel, sdmx-edi, sdmx-json, sdmx-compact-2.1, sdmx-generic-2.1
ממשק סדרות
ניתן להשתמש בממשק הסדרות על מנת לדעת מהם עולמות התוכן הקיימים, מהו המבנה של כל אחד מהם (עמודות מטה דטה קיימות), ואילו סדרות יש בכל עולם תוכן.
מידע נוסף
תקן SDMX (ראשי תיבות של Statistical Data and Metadata Exchange) הוא תקן בינלאומי שנועד להקל על החלפה ושיתוף של נתונים סטטיסטיים ומטה-דטה בין ארגונים שונים. התקן פותח בשיתוף פעולה בין מספר ארגונים בינלאומיים, כולל קרן המטבע הבינלאומית (IMF), הבנק העולמי, הארגון לשיתוף פעולה ולפיתוח כלכלי (OECD), והאיחוד האירופי, בין היתר.
ה-API המשמש לשליפת סדרות ממאגר הסדרות מיישם את תקן SDMX, ולפיכך קיימות בו אפשרויות (וגם מורכבויות) נוספות שלא תוארו במדריך זה. בקישור הבא ניתן למצוא מידע טכני נוסף על התקן כולל REST API specification מלא, format specifications לפורמטים השונים של ה-output, ועוד:
בקישור הבא ניתן למצוא הפניות למקורות למידה בנושא SDMX: קורסים מקוונים, הרצאות מוקלטות וכיו"ב