YouTube Analytics API - Data Model

ה-API של YouTube Analytics מאפשר לכם ליצור דוחות בהתאמה אישית שמכילים נתונים מ-YouTube Analytics. ה-API תומך בדוחות לגבי ערוצים ובעלי תוכן. השדות בדוחות מסווגים כמאפיינים או כמדדים:

• מאפיינים הם קריטריונים נפוצים שמשמשים לצבירת נתונים, כמו התאריך שבו התרחשה פעולה או המדינה שבה נמצאים המשתמשים.

  בדוח, לכל שורת נתונים יש שילוב ייחודי של ערכי מאפיינים. לכן, המאפיינים שבוחרים לדוח קובעים איך מערכת YouTube מחשבת את הערכים של המדדים בדוח הזה.

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

ה-API של Analytics מספק פרמטרים של סינון ומיון, כך שהאפליקציה שמבצעת את הקריאה לא צריכה לתמוך בפונקציות האלה באופן מובנה. בנוסף, ה-API מאפשר לאחזר נתונים של קבוצות ב-YouTube Analytics. קבוצה היא אוסף מותאם אישית של עד 500 סרטונים, פלייליסטים, ערוצים או נכסים.

בחירת פרמטרים של דוחות

כשמבקשים דוח באמצעות השיטה reports.query של ה-API, בקשת ה-API מכילה חמישה פרמטרים שקובעים איך יחושבו ערכי הדוח:

• הפרמטרים startDate ו-endDate מציינים את התקופה שבה הדוח יכיל נתונים. התשובה של ה-API מכילה נתונים עד היום האחרון שצוין, שכל המדדים בשילתא זמינים לגביו בזמן השאילתא.

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

• הפרמטר dimensions מסביר איך המדדים יקובצו.

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

  הערה: ה-API מאפשר לציין כמה ערכים למסננים video,‏ playlist ו-channel. אם תעשו את זה, תוכלו גם לכלול את המסנן הזה ברשימת המימדים, כדי שהמדדים שיוחזרו יקובצו גם לפי סרטון, פלייליסט או ערוץ.

אפשרויות דיווח לדוגמה

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

• בעלי הערוץ מגדירים את הפרמטר startDate לערך 2015-06-01 ואת הפרמטר endDate לערך 2015-07-31. על סמך הערכים האלה, הדוח יכיל נתונים לתקופה של חודשיים.

• דוח סוגי המכשירים תומך במדדים views ו-estimatedMinutesWatched, ולכן בעל הערוץ מגדיר את הפרמטר metrics לערך views,estimatedMinutesWatched.

• לבעלי הערוץ יש כמה אפשרויות לפרמטר dimensions. שניים מהם מוצגים ברשימה הבאה, והשלישי מוסבר בהמשך הקטע הזה, בהסבר על ערך הפרמטר filters.

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

    • כמה פעמים צפו בסרטונים של הערוץ במכשירים ניידים בין 1 ביוני 2015 ל-31 ביולי 2015?
    • כמה פעמים צפו בסרטונים בערוץ בקונסולות משחקים בין 1 ביוני 2015 ל-31 ביולי 2015?

    הדוח יכלול למעשה ספירה של מספר הצפיות וזמן הצפייה הכולל לכל סוג מכשיר.

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

    • כמה צפיות היו בסרטונים של הערוץ במכשירים ניידים ב-1 ביוני 2015?
    • כמה פעמים אנשים צפו בסרטונים של הערוץ בטלוויזיות ב-14 ביולי 2015?

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

  • בעל הערוץ יכול לסנן את הבקשה כדי לקבל ערכים רק למערכת ההפעלה Android. (כמה צפיות התרחשו במכשירי Android ניידים במהלך תקופת הדיווח?)

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

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

    בנוסף, אם המסנן video מציין כמה ערכים, אפשר לציין את video גם כמאפיין. כלומר, הפרמטר dimensions תומך גם בערכים deviceType,video ו-day,deviceType,video.

    • אם בעל הערוץ כולל את המאפיין video ברשימת המאפיינים, המדדים יציינו ערכים נפרדים לכל סרטון. (כמה פעמים צפו בסרטון XYZ בקונסולת משחקים ב-1 ביוני 2015?)
    • אם בעל הערוץ לא כולל את הסרטון ברשימת המאפיינים, המדדים מציינים ערכים כוללים שמתייחסים לכל הסרטונים שצוינו. (כמה פעמים צפו בסרטונים ABC,‏ DEF ו-XYZ בקונסולת משחקים ב-1 ביוני 2015?)

עדכניות הנתונים וזמן אחזור

ה-API של YouTube Analytics תומך בשאילתות ממוקדות, אבל נתוני הניתוח הבסיסיים לא מתעדכנים בזמן אמת. בדרך כלל, עיבוד הנתונים יוצר השהיה של 48 עד 72 שעות. לכן, התשובות של ה-API לא מכילות נתונים מהימים האחרונים, והתאריך endDate בדוח כולל רק נתונים עד היום האחרון שבו כל המדדים המבוקשים עברו עיבוד מלא.

בגלל זמן האחזור של הנתונים, יכול להיות שתראו הבדלים בין הנתונים שמוחזרים על ידי ה-API לבין המדדים בזמן אמת שמוצגים ב-YouTube Studio. אם האפליקציה שלכם דורשת נתונים סטטיסטיים בזמן אמת לגבי סרטונים ספציפיים, כמו מספר הצפיות, הלייקים או התגובות הנוכחי, אתם צריכים להשתמש בשיטה videos.list של YouTube Data API במקום ב-YouTube Analytics API.

אחזור דוחות

כדי לאחזר דוח, שולחים בקשת GET מורשית ל-method ‏ reports.query של ה-API, ומציינים את הפרמטרים שמגדירים את הדוח שרוצים לאחזר.

רשימת הדוחות שנתמכים על ידי ה-API מופיעה במסמכי התיעוד בנושא דוחות על ערוצים ודוחות על בעלי תוכן. בכל הגדרת דוח מפורטים הערכים שהדוח מאפשר לפרמטרים metrics, dimensions ו-filters.

שיטות מומלצות

אפליקציות שמשתמשות ב-YouTube Analytics API צריכות תמיד לפעול לפי השיטות המומלצות הבאות:

• אפשר להשתמש בשורת הכותרת של התגובה כדי לקבוע את הסדר של העמודות בדוח. לדוגמה, אל תניחו שviews יהיה המדד הראשון שיוחזר בתגובה רק בגלל שהוא המדד הראשון שמופיע בתיאור הדוח. במקום זאת, צריך להשתמש בשורת הכותרת של התגובה כדי לקבוע באיזו עמודה נמצאים הנתונים האלה.
• אפשר להשתמש ב-YouTube Data API כדי לאחזר מטא-נתונים נוספים של מקורות שמזוהים בתגובות של YouTube Analytics API. כפי שמצוין בכללי המדיניות למפתחים של שירותי ה-API של YouTube (סעיפים III.E.4.b עד III.E.4.d), לקוחות API צריכים למחוק או לרענן מטא-נתונים של משאבים מאוחסנים מ-API מסוים אחרי 30 יום.

מדדים נצברים ופריטים שנמחקו

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

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

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

אנונימיזציה של נתונים

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

1. היקף התנועה לסרטון או לערוץ היה מוגבל בפרק זמן מסוים,

   או

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

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

לדוגמה, נניח שבעלים של ערוץ מאחזר שני דוחות. בדוח הראשון מופיע מספר הצפיות הכולל בסרטון מסוים, ובדוח השני מופיע מספר הצפיות הכולל בסרטון הזה לפי מדינה. נניח שהיו 1, 000 צפיות בסרטון בטווח זמן מסוים, שמתוכן 500 צפיות היו בארצות הברית, 498 צפיות בקנדה, ו-2 צפיות בצרפת.

בדוגמה הזו, בדוח הראשון יצוין שהסרטון נצפה 1,000 פעמים. בדוח השני יופיע רק שהסרטון נצפה 500 פעמים בארצות הברית ו-498 פעמים בקנדה. לכן יהיה הבדל בין הסכום הכולל של הצפיות בשני הדוחות. שימו לב: בדוח השני לא תהיה שום אינדיקציה לכך שהיו עוד 2 צפיות (או שהיו צפיות בצרפת).

לא מתפרסמים ערכי הסף שלפיהם נקבע אילו נתונים יכולים להיות חסרים, והם עשויים להשתנות לפי שיקול הדעת של YouTube.

סוגי נתונים מסוימים

יכול להיות שהיקף הנתונים הבאים יהיה מוגבל בדוחות של YouTube Analytics:

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

מידע נוסף על נתונים מוגבלים בדוחות של YouTube Analytics זמין במרכז העזרה של YouTube.

ניצול המכסה

כל בקשה ל-API שאתם שולחים נחשבת כיחידה אחת במכסת השימוש שלכם ב-API. מגבלות המכסה מוצגות בחלונית Quotas ב-Google API Console.