Introduction

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

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

  • דוחות ערוצים מכילים מדדי פעילות משתמשים לגבי ערוץ מסוים.

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

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

כל הבקשות ל-YouTube Analytics ול-YouTube Reporting API חייבות לקבל אישור מהערוץ או מבעלי התוכן שהנתונים המבוקשים בבעלותם.

דיווח על תוכן

הדוחות שממשקי ה-API מאחזרים מכילים שני סוגי נתונים:

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

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

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

בחירת ה-API המתאים לאפליקציה שלכם

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

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

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

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

דוחות נתמכים

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

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

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

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

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

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

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

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

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

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

הבדלים עיקריים

בטבלה הבאה מפורטים ההבדלים החשובים בין YouTube Analytics לממשק ה-API של הדיווח.

התכונה ממשק API של YouTube Analytics ממשק API לדיווח של YouTube
תהליך לאחזור נתונים בכל בקשת API מצוינים מאפיינים ומדדים שיש להחזיר, וגם את תקופת הזמן שבה הנתונים יוחזרו. משימות דיווח על תזמון אפליקציות. המערכת של YouTube יוצרת דוחות יומיים לכל עבודה שאפשר להוריד באופן אסינכרוני.
טווחי תאריכים בחלק מהדוחות של ממשק ה-API מצוין התאריך שבו התרחשה פעילות המשתמש. חלק מהדוחות האלה תומכים במאפיינים של צבירת מדדי פעילות משתמשים לפי חודש. כל דוחות ה-API מציינים את היום שבו התרחשה פעילות המשתמש. אפליקציות שמשתמשות ב-API יכולות להטמיע תכונות לצבירה של נתונים לפרקי זמן תקופתיים.
סינון נתונים אתם יכולים לסנן דוחות כך שיכללו רק שורות שבהן למאפיין מסוים יש ערך ספציפי. ממשק ה-API תומך גם במאפיינים מסוימים כמו יבשת וsubContinent, שמשמשים רק כמסננים. ה-API תומך בהורדות בכמות גדולה של קבוצות נתונים מלאות. לא ניתן לסנן או להחזיר נתונים לפי מאפיינים שהם מסננים בלבד. אפליקציית הלקוח מאחסנת את הנתונים שהורדו ומטמיעה תכונות משלה לסינון הנתונים.
עוד כלים אפשר למיין דוחות לפי ערכי מדדים שהוחזרו. חלק מהדוחות תומכים רק במספר מוגבל של תוצאות. לדוגמה, הדוח שמציג את הסרטונים הנצפים ביותר בערוץ מחזיר 200 שורות לכל היותר. ה-API הזה תומך בהורדות בכמות גדולה של קבוצות נתונים מלאות. אפליקציות לקוח יכולות להטמיע תכונות משלהן כדי למיין נתונים שהורדו.
ספירות דוחות API מכילים ערכי טקסט, כגון "Android" או "CHANNEL", לזיהוי ערכי מאפיינים. דוחות API מכילים מספרים שלמים שניתן למפות לערכי טקסט.
מכסה שרת ה-API מעריך כל שאילתה כדי לקבוע את עלות המכסה שלה. בקטע שימוש במכסה יש הסבר מפורט על המתודולוגיה. השימוש במכסה לא מהווה בעיה כי הנתונים מאוחזרים פעם אחת ולאחר מכן מסוננים, ממוינים ושולחים שאילתות באפליקציה.
דוחות ייחודיים
  • פעילות משתמשים הקשורה לכתוביות
  • נתונים לגבי שימור קהל של פלייליסטים
  • דוחות של הכנסות משוערות לבעלי התוכן (זמינים 2 דוחות שונים)
  • דוחות נכסים לבעלי תוכן (קיימים 11 דוחות שונים)
מאפיינים ייחודיים group (מאפיין מסנן בלבד)
continent (מאפיין מסנן בלבד)
subContinent (מאפיין מסנן בלבד)
month
isCurated==1 (מאפיין filter-only)
viewsPerPlaylistStart
averageTimeInPlaylist
annotation_id
annotation_type
asset_id
card_id
card_type
live_or_on_demand
subscribed_status
subtitle_language
מדדים ייחודיים ייחודיות
relativeRetentionPerformance
viewsPerPlaylistStart
averageTimeInPlaylist
card_click_rate
card_clicks
card_impressions
card_teaser_click_rate
card_teaser_clicks
card_teaser_impressions
estimated_partner_adsense_revenue
estimated_partner_doubleclick_revenueestimated_partner_doubleclick_revenue

playlist_saves_addedplaylist_saves_removed

הבדלים בשמות בין ממשקי API

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

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

מאפיינים

שם API של YouTube Analytics שם YouTube Reporting API
adType ad_type
ageGroup age_group
נכס asset_id
audienceType audience_retention_type
ערוץ channel_id
claimedStatus claimed_status
contentOwner content_owner_id
country country_code
יום תאריך
deviceType device_type
elapsedVideoTimeRatio elapsed_video_time_percentage
מגדר מגדר
insightPlaybackLocationDetail playback_location_detail
insightPlaybackLocationType playback_location_type
insightTrafficSourceDetail traffic_source_detail
insightTrafficSourceType traffic_source_type
liveOrOnDemand live_or_on_demand
operatingSystem operating_system
פלייליסט playlist_id
province province_code
sharingService sharing_service
subscribedStatus subscribed_status
subtitleLanguage subtitle_language
uploaderType uploader_type
סרטון video_id

מדדים

שם API של YouTube Analytics שם YouTube Reporting API
adEarnings estimated_partner_ad_revenue
annotationImpressions annotation_impressions
annotationClickableImpressions annotation_clickable_impressions
annotationClicks annotation_clicks
annotationClickThroughRate annotation_click_through_rate
annotationClosableImpressions annotation_closable_impressions
annotationCloses annotation_closes
annotationCloseRate annotation_close_rate
audienceWatchRatio audience_retention_percentage
averageViewDuration average_view_duration_seconds
averageViewPercentage average_view_duration_percentage
cardClickRate card_click_rate
cardClicks card_clicks
cardImpressions card_impressions
cardTeaserClickRate card_teaser_click_rate
cardTeaserClicks card_teaser_clicks
cardTeaserImpressions card_teaser_impressions
תגובות תגובות
דיסלייקים דיסלייקים
רווחים estimated_partner_revenue
estimatedMinutesWatched watch_time_minutes
estimatedPartnerAdSenseRevenue estimated_partner_adsense_revenue
estimatedPartnerDoubleClickRevenue estimated_partner_doubleclick_revenue
grossRevenue estimated_youtube_ad_revenue
impressionBasedCpm estimated_cpm
חשיפות ad_impressions
לייקים לייקים
monetizedPlaybacks estimated_monetized_playbacks
playbackBasedCpm estimated_playback_based_cpm
playlistStarts playlist_starts
savesAdded playlist_saves_added
savesRemoved playlist_saves_removed
מניות מניות
subscribersGained subscribers_gained
subscribersLost subscribers_lost
videosAddedToPlaylists videos_added_to_playlists
videosRemovedFromPlaylists videos_removed_from_playlist
viewerPercentage views_percentage
תצוגות תצוגות