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?)

אחזור דוחות

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

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

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

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

• אפשר להשתמש בשורת הכותרת של התגובה כדי לקבוע את הסדר של העמודות בדוח. לדוגמה, אל תניחו שviews יהיה המדד הראשון שיוחזר בתגובה רק בגלל שהוא המדד הראשון שמופיע בתיאור הדוח. במקום זאת, צריך להשתמש בשורת הכותרת של התשובה כדי לקבוע באיזו עמודה הנתונים האלה מופיעים.
• אפשר להשתמש ב-YouTube Data API כדי לאחזר מטא-נתונים נוספים של מקורות שמזוהים בתגובות של YouTube Analytics API. כפי שמצוין בכללי המדיניות למפתחים של שירותי YouTube API (סעיפים 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.