Class: Yt::Models::Playlist

Inherits:
Resource
  • Object
show all
Defined in:
lib/yt/models/playlist.rb

Overview

Provides methods to interact with YouTube playlists.

Instance Attribute Summary collapse

Attributes inherited from Resource

#id, #privacy_status

Instance Method Summary collapse

Methods inherited from Resource

#private?, #public?, #unlisted?

Instance Attribute Details

#channel_idString (readonly)


34
# File 'lib/yt/models/playlist.rb', line 34

delegate :channel_id, to: :snippet

#channel_titleString (readonly)


38
# File 'lib/yt/models/playlist.rb', line 38

delegate :channel_title, to: :snippet

#descriptionString (readonly)


17
# File 'lib/yt/models/playlist.rb', line 17

delegate :description, to: :snippet

#item_countInteger (readonly)


50
# File 'lib/yt/models/playlist.rb', line 50

delegate :item_count, to: :content_detail

#playlist_itemsYt::Collections::PlaylistItems (readonly)


158
# File 'lib/yt/models/playlist.rb', line 158

has_many :playlist_items

#published_atTime (readonly)


30
# File 'lib/yt/models/playlist.rb', line 30

delegate :published_at, to: :snippet

#tagsArray<String> (readonly)


42
# File 'lib/yt/models/playlist.rb', line 42

delegate :tags, to: :snippet

#titleString (readonly)


13
# File 'lib/yt/models/playlist.rb', line 13

delegate :title, to: :snippet

Instance Method Details

#add_video(video_id, options = {}) ⇒ Yt::PlaylistItem

Adds a video to the playlist. Unlike #add_video!, does not raise an error if video can’t be added.

Options Hash (options):

  • :position (Integer)

    where to add video in the playlist.

Raises:


95
96
97
98
# File 'lib/yt/models/playlist.rb', line 95

def add_video(video_id, options = {})
  playlist_item_params = playlist_item_params(video_id, options)
  playlist_items.insert playlist_item_params, ignore_errors: true
end

#add_video!(video_id, options = {}) ⇒ Yt::PlaylistItem

Adds a video to the playlist. Unlike #add_video, raises an error if video can’t be added.

Options Hash (options):

  • :position (Integer)

    where to add video in the playlist.

Raises:


109
110
111
112
# File 'lib/yt/models/playlist.rb', line 109

def add_video!(video_id, options = {})
  playlist_item_params = playlist_item_params(video_id, options)
  playlist_items.insert playlist_item_params
end

#add_videos(video_ids = [], options = {}) ⇒ Array<Yt::PlaylistItem>

Adds multiple videos to the playlist. Unlike #add_videos!, does not raise an error if videos can’t be added.

Options Hash (options):

  • :position (Integer)

    where to add videos in the playlist.

Raises:


122
123
124
# File 'lib/yt/models/playlist.rb', line 122

def add_videos(video_ids = [], options = {})
  video_ids.map{|video_id| add_video video_id, options}
end

#add_videos!(video_ids = [], options = {}) ⇒ Array<Yt::PlaylistItem>

Adds multiple videos to the playlist. Unlike #add_videos, raises an error if videos can’t be added.

Options Hash (options):

  • :position (Integer)

    where to add videos in the playlist.

Raises:


134
135
136
# File 'lib/yt/models/playlist.rb', line 134

def add_videos!(video_ids = [], options = {})
  video_ids.map{|video_id| add_video! video_id, options}
end

#average_time_in_playlist(options = {}) ⇒ Hash<Date, Float>, ...

Returns the average_time_in_playlist grouped by the given dimension.

Examples:

Get the average_time_in_playlist for each day of last week:

resource.average_time_in_playlist since: 2.weeks.ago, until: 1.week.ago, by: :day
# => {Wed, 8 May 2014 => 12.0, Thu, 9 May 2014 => 34.0, …}

Get the average_time_in_playlist for this and last month:

resource.average_time_in_playlist since: 1.month.ago, by: :month
# => {Wed, 01 Apr 2014..Thu, 30 Apr 2014 => 12.0, Fri, 01 May 2014..Sun, 31 May 2014 => 34.0, …}

Get the average_time_in_playlist for this and last week:

resource.average_time_in_playlist since: 1.week.ago, by: :week
# => {Wed, 01 Apr 2014..Tue, 07 Apr 2014 => 20.0, Wed, 08 Apr 2014..Tue, 14 Apr 2014 => 13.0, …}

Get the average_time_in_playlist for the whole last week:

resource.average_time_in_playlist since: 2.weeks.ago, until: 1.week.ago, by: :range
# => {total: 564.0}

Get the average_time_in_playlist for the whole last week in Texas only:

resource.average_time_in_playlist since: 2.weeks.ago, until: 1.week.ago, by: :range, in: {state: 'TX'}
# => {total: 19.0}

Options Hash (options):

  • :by (Symbol) — default: :day

    The dimension to collect average_time_in_playlist by. Accepted values are: :day, :week, :month, :range.

  • :since (#to_date)

    The first day of the time-range. Also aliased as :from.

  • :until (#to_date)

    The last day of the time-range. Also aliased as :to.

  • :in (<String, Hash>)

    The location to limit the average_time_in_playlist to. Can either be the two-letter ISO-3166-1 code of a country, such as “US”, or a Hash that either contains the :country key, such as {country: “US”} or the :state key, such as {state: “TX”}. Note that YouTube API only provides data for US states.


180
# File 'lib/yt/models/playlist.rb', line 180

has_report :average_time_in_playlist, Float

#average_view_duration(options = {}) ⇒ Hash<Date, Integer>, ...

Returns the average_view_duration grouped by the given dimension.

Examples:

Get the average_view_duration for each day of last week:

resource.average_view_duration since: 2.weeks.ago, until: 1.week.ago, by: :day
# => {Wed, 8 May 2014 => 12.0, Thu, 9 May 2014 => 34.0, …}

Get the average_view_duration for this and last month:

resource.average_view_duration since: 1.month.ago, by: :month
# => {Wed, 01 Apr 2014..Thu, 30 Apr 2014 => 12.0, Fri, 01 May 2014..Sun, 31 May 2014 => 34.0, …}

Get the average_view_duration for this and last week:

resource.average_view_duration since: 1.week.ago, by: :week
# => {Wed, 01 Apr 2014..Tue, 07 Apr 2014 => 20.0, Wed, 08 Apr 2014..Tue, 14 Apr 2014 => 13.0, …}

Get the average_view_duration for the whole last week:

resource.average_view_duration since: 2.weeks.ago, until: 1.week.ago, by: :range
# => {total: 564.0}

Get the average_view_duration for the whole last week in Texas only:

resource.average_view_duration since: 2.weeks.ago, until: 1.week.ago, by: :range, in: {state: 'TX'}
# => {total: 19.0}

Options Hash (options):

  • :by (Symbol) — default: :day

    The dimension to collect average_view_duration by. Accepted values are: :day, :week, :month, :range.

  • :since (#to_date)

    The first day of the time-range. Also aliased as :from.

  • :until (#to_date)

    The last day of the time-range. Also aliased as :to.

  • :in (<String, Hash>)

    The location to limit the average_view_duration to. Can either be the two-letter ISO-3166-1 code of a country, such as “US”, or a Hash that either contains the :country key, such as {country: “US”} or the :state key, such as {state: “TX”}. Note that YouTube API only provides data for US states.


174
# File 'lib/yt/models/playlist.rb', line 174

has_report :average_view_duration, Integer

#delete(options = {}) ⇒ Boolean

Deletes the playlist.

Raises:


58
59
60
61
# File 'lib/yt/models/playlist.rb', line 58

def delete(options = {})
  do_delete {@id = nil}
  !exists?
end

#delete_playlist_items(attributes = {}) ⇒ Array<Boolean>

Deletes the playlist’s items matching all the given attributes.

Options Hash (attributes):

  • :title (<String, Regexp>)

    The item’s title. Pass a String for perfect match or a Regexp for advanced match.

  • :description (<String, Regexp>)

    The item’s description. Pass a String (perfect match) or a Regexp (advanced).

  • :privacy_status (String)

    The item’s privacy status.

  • :video_id (String)

    The item’s video ID.

Raises:


150
151
152
# File 'lib/yt/models/playlist.rb', line 150

def delete_playlist_items(attributes = {})
  playlist_items.delete_all attributes
end

#estimated_minutes_watched(options = {}) ⇒ Hash<Yt::Video, Integer>, ...

Returns the estimated_minutes_watched grouped by the given dimension.

Examples:

Get yesterday’s estimated_minutes_watched by video, eager-loading the status and statistics of each video:

resource.estimated_minutes_watched since: 1.day.ago, until: 1.day.ago, by: :video, includes: [:status, :statistics]
# => {#<Yt::Video @id=…> => 33.0, #<Yt::Video @id=…> => 12.0, …}

Get yesterday’s estimated_minutes_watched by playlist:

resource.estimated_minutes_watched since: 1.day.ago, until: 1.day.ago, by: :playlist
# => {#<Yt::Playlist @id=…> => 33.0, #<Yt::Playlist @id=…> => 12.0, …}

Get yesterday’s estimated_minutes_watched grouped by playback location:

resource.estimated_minutes_watched since: 1.day.ago, until: 1.day.ago, by: :playback_location
# => {embedded: 53.0, watch: 467.0, …}

Get yesterday’s estimated_minutes_watched by related video, eager-loading the snippet of each video

resource.estimated_minutes_watched since: 1.day.ago, until: 1.day.ago, by: :related_video, includes: [:snippet]
# => {#<Yt::Video @id=…> => 33.0, #<Yt::Video @id=…> => 12.0, …}

Get yesterday’s estimated_minutes_watched by search term:

resource.estimated_minutes_watched since: 1.day.ago, until: 1.day.ago, by: :search_term
# => {"fullscreen" => 33.0, "good music" => 12.0, …}

Get yesterday’s estimated_minutes_watched by URL that referred to the resource:

resource.estimated_minutes_watched since: 1.day.ago, until: 1.day.ago, by: :referrer
# => {"Google Search" => 33.0, "ytimg.com" => 12.0, …}

Get yesterday’s estimated_minutes_watched by device type:

resource.estimated_minutes_watched since: 1.day.ago, until: 1.day.ago, by: :device_type
# => {mobile: 133.0, tv: 412.0, …}

Get yesterday’s estimated_minutes_watched by traffic source:

resource.estimated_minutes_watched since: 1.day.ago, until: 1.day.ago, by: :traffic_source
# => {advertising: 543.0, playlist: 92.0, …}

Get the estimated_minutes_watched for each day of last week:

resource.estimated_minutes_watched since: 2.weeks.ago, until: 1.week.ago, by: :day
# => {Wed, 8 May 2014 => 12.0, Thu, 9 May 2014 => 34.0, …}

Get the estimated_minutes_watched for this and last month:

resource.estimated_minutes_watched since: 1.month.ago, by: :month
# => {Wed, 01 Apr 2014..Thu, 30 Apr 2014 => 12.0, Fri, 01 May 2014..Sun, 31 May 2014 => 34.0, …}

Get the estimated_minutes_watched for this and last week:

resource.estimated_minutes_watched since: 1.week.ago, by: :week
# => {Wed, 01 Apr 2014..Tue, 07 Apr 2014 => 20.0, Wed, 08 Apr 2014..Tue, 14 Apr 2014 => 13.0, …}

Get the estimated_minutes_watched for the whole last week:

resource.estimated_minutes_watched since: 2.weeks.ago, until: 1.week.ago, by: :range
# => {total: 564.0}

Get the estimated_minutes_watched for the whole last week in Texas only:

resource.estimated_minutes_watched since: 2.weeks.ago, until: 1.week.ago, by: :range, in: {state: 'TX'}
# => {total: 19.0}

Options Hash (options):

  • :by (Symbol) — default: :day

    The dimension to collect estimated_minutes_watched by. Accepted values are: :day, :week, :month, :range, :traffic_source, :playback_location, :related_video, :video, :playlist.

  • :includes (Array<Symbol>) — default: [:id]

    if grouped by video, related video, or playlist, the parts of each video or playlist to eager-load. Accepted values are: :id, :snippet, :status, :statistics, :content_details.

  • :since (#to_date)

    The first day of the time-range. Also aliased as :from.

  • :until (#to_date)

    The last day of the time-range. Also aliased as :to.

  • :in (<String, Hash>)

    The location to limit the estimated_minutes_watched to. Can either be the two-letter ISO-3166-1 code of a country, such as “US”, or a Hash that either contains the :country key, such as {country: “US”} or the :state key, such as {state: “TX”}. Note that YouTube API only provides data for US states.


168
# File 'lib/yt/models/playlist.rb', line 168

has_report :estimated_minutes_watched, Integer

#playlist_starts(options = {}) ⇒ Hash<Date, Integer>, ...

Returns the playlist_starts grouped by the given dimension.

Examples:

Get the playlist_starts for each day of last week:

resource.playlist_starts since: 2.weeks.ago, until: 1.week.ago, by: :day
# => {Wed, 8 May 2014 => 12.0, Thu, 9 May 2014 => 34.0, …}

Get the playlist_starts for this and last month:

resource.playlist_starts since: 1.month.ago, by: :month
# => {Wed, 01 Apr 2014..Thu, 30 Apr 2014 => 12.0, Fri, 01 May 2014..Sun, 31 May 2014 => 34.0, …}

Get the playlist_starts for this and last week:

resource.playlist_starts since: 1.week.ago, by: :week
# => {Wed, 01 Apr 2014..Tue, 07 Apr 2014 => 20.0, Wed, 08 Apr 2014..Tue, 14 Apr 2014 => 13.0, …}

Get the playlist_starts for the whole last week:

resource.playlist_starts since: 2.weeks.ago, until: 1.week.ago, by: :range
# => {total: 564.0}

Get the playlist_starts for the whole last week in Texas only:

resource.playlist_starts since: 2.weeks.ago, until: 1.week.ago, by: :range, in: {state: 'TX'}
# => {total: 19.0}

Options Hash (options):

  • :by (Symbol) — default: :day

    The dimension to collect playlist_starts by. Accepted values are: :day, :week, :month, :range.

  • :since (#to_date)

    The first day of the time-range. Also aliased as :from.

  • :until (#to_date)

    The last day of the time-range. Also aliased as :to.

  • :in (<String, Hash>)

    The location to limit the playlist_starts to. Can either be the two-letter ISO-3166-1 code of a country, such as “US”, or a Hash that either contains the :country key, such as {country: “US”} or the :state key, such as {state: “TX”}. Note that YouTube API only provides data for US states.


177
# File 'lib/yt/models/playlist.rb', line 177

has_report :playlist_starts, Integer

#reports(options = {}) ⇒ Hash<Symbol, Hash>

Returns the reports for the given metrics grouped by the given dimension.

Examples:

Get the views and estimated minutes watched by day for last week:

resource.reports only: [:views, :estimated_minutes_watched] since: 1.week.ago, by: :day
# => {views: {Wed, 8 May 2014 => 12, Thu, 9 May 2014 => 34, …}, estimated_minutes_watched: {Wed, 8 May 2014 => 9, Thu, 9 May 2014 => 6, …}}

Options Hash (options):

  • :only (Array<Symbol>)

    The metrics to generate reports for.

  • :by (Symbol) — default: :day

    The dimension to collect metrics by. Accepted values are: :day, :week, :month.

  • :since (#to_date)

    The first day of the time-range. Also aliased as :from.

  • :until (#to_date)

    The last day of the time-range. Also aliased as :to.


# File 'lib/yt/models/playlist.rb', line 162


#thumbnail_url(size = :default) ⇒ String?

Returns the URL of the playlist’s thumbnail.


26
# File 'lib/yt/models/playlist.rb', line 26

delegate :thumbnail_url, to: :snippet

#update(attributes = {}) ⇒ Boolean

Updates the attributes of a playlist.

Examples:

Update title and description of a playlist.

playlist.update title: 'New title', description: 'New description'

Update tags and status of a playlist.

playlist.update tags: ['new', 'tags'], privacy_status: 'public'

Options Hash (attributes):

  • :title (String)

    The new playlist’s title. Cannot have more than 100 characters. Can include the characters < and >, which are replaced to ‹ › in order to be accepted by YouTube.

  • :description (String)

    The new playlist’s description. Cannot have more than 5000 bytes. Can include the characters < and >, which are replaced to ‹ › in order to be accepted by YouTube.

  • :tags (Array<String>)

    The new playlist’s tags. Cannot have more than 500 characters. Can include the characters < and >, which are replaced to ‹ › in order to be accepted by YouTube.

  • :privacy_status (String)

    The new playlist’s privacy status. Must be one of: private, unscheduled, public.

Raises:


83
84
85
# File 'lib/yt/models/playlist.rb', line 83

def update(attributes = {})
  super
end

#viewer_percentage(options = {}) ⇒ Hash<Symbol, Float>, ...

Returns the viewer_percentage grouped by the given dimension.

Examples:

Get yesterday’s viewer percentage by gender:

resource.viewer_percentage since: 1.day.ago, until: 1.day.ago, by: :gender
# => {female: 53.0, male: 47.0}

Get yesterday’s viewer_percentage grouped by age group:

resource.viewer_percentage since: 1.day.ago, until: 1.day.ago, by: :age_group
# => {"18-24" => 4.54, "35-24" => 12.31, "45-34" => 8.92, …}

Get yesterday’s viewer_percentage by gender and age group:

resource.viewer_percentage since: 1.day.ago, until: 1.day.ago
# => {female: {"18-24" => 12.12, "25-34" => 16.16, …}, male:…}

Get yesterday’s viewer_percentage by gender and age group in France only:

resource.viewer_percentage since: 1.day.ago, until: 1.day.ago, in: 'FR'
# => {female: {"18-24" => 16.12, "25-34" => 13.16, …}, male:…}

Get the viewer_percentage for the whole last week in Texas only:

resource.viewer_percentage since: 2.weeks.ago, until: 1.week.ago, by: :range, in: {state: 'TX'}
# => {total: 19.0}

Options Hash (options):

  • :by (Symbol) — default: :gender_age_group

    The dimension to show viewer percentage by. Accepted values are: :gender, :age_group, :gender_age_group.

  • :since (#to_date)

    The first day of the time-range. Also aliased as :from.

  • :until (#to_date)

    The last day of the time-range. Also aliased as :to.

  • :in (<String, Hash>)

    The location to limit the viewer_percentage to. Can either be the two-letter ISO-3166-1 code of a country, such as “US”, or a Hash that either contains the :country key, such as {country: “US”} or the :state key, such as {state: “TX”}. Note that YouTube API only provides data for US states.


171
# File 'lib/yt/models/playlist.rb', line 171

has_report :viewer_percentage, Float

#views(options = {}) ⇒ Hash<Yt::Video, Integer>, ...

Returns the views grouped by the given dimension.

Examples:

Get yesterday’s views by video, eager-loading the status and statistics of each video:

resource.views since: 1.day.ago, until: 1.day.ago, by: :video, includes: [:status, :statistics]
# => {#<Yt::Video @id=…> => 33.0, #<Yt::Video @id=…> => 12.0, …}

Get yesterday’s views by playlist:

resource.views since: 1.day.ago, until: 1.day.ago, by: :playlist
# => {#<Yt::Playlist @id=…> => 33.0, #<Yt::Playlist @id=…> => 12.0, …}

Get yesterday’s views grouped by playback location:

resource.views since: 1.day.ago, until: 1.day.ago, by: :playback_location
# => {embedded: 53.0, watch: 467.0, …}

Get yesterday’s views by related video, eager-loading the snippet of each video

resource.views since: 1.day.ago, until: 1.day.ago, by: :related_video, includes: [:snippet]
# => {#<Yt::Video @id=…> => 33.0, #<Yt::Video @id=…> => 12.0, …}

Get yesterday’s views by search term:

resource.views since: 1.day.ago, until: 1.day.ago, by: :search_term
# => {"fullscreen" => 33.0, "good music" => 12.0, …}

Get yesterday’s views by URL that referred to the resource:

resource.views since: 1.day.ago, until: 1.day.ago, by: :referrer
# => {"Google Search" => 33.0, "ytimg.com" => 12.0, …}

Get yesterday’s views by device type:

resource.views since: 1.day.ago, until: 1.day.ago, by: :device_type
# => {mobile: 133.0, tv: 412.0, …}

Get yesterday’s views by traffic source:

resource.views since: 1.day.ago, until: 1.day.ago, by: :traffic_source
# => {advertising: 543.0, playlist: 92.0, …}

Get the views for each day of last week:

resource.views since: 2.weeks.ago, until: 1.week.ago, by: :day
# => {Wed, 8 May 2014 => 12.0, Thu, 9 May 2014 => 34.0, …}

Get the views for this and last month:

resource.views since: 1.month.ago, by: :month
# => {Wed, 01 Apr 2014..Thu, 30 Apr 2014 => 12.0, Fri, 01 May 2014..Sun, 31 May 2014 => 34.0, …}

Get the views for this and last week:

resource.views since: 1.week.ago, by: :week
# => {Wed, 01 Apr 2014..Tue, 07 Apr 2014 => 20.0, Wed, 08 Apr 2014..Tue, 14 Apr 2014 => 13.0, …}

Get the views for the whole last week:

resource.views since: 2.weeks.ago, until: 1.week.ago, by: :range
# => {total: 564.0}

Get the views for the whole last week in Texas only:

resource.views since: 2.weeks.ago, until: 1.week.ago, by: :range, in: {state: 'TX'}
# => {total: 19.0}

Options Hash (options):

  • :by (Symbol) — default: :day

    The dimension to collect views by. Accepted values are: :day, :week, :month, :range, :traffic_source, :playback_location, :related_video, :video, :playlist.

  • :includes (Array<Symbol>) — default: [:id]

    if grouped by video, related video, or playlist, the parts of each video or playlist to eager-load. Accepted values are: :id, :snippet, :status, :statistics, :content_details.

  • :since (#to_date)

    The first day of the time-range. Also aliased as :from.

  • :until (#to_date)

    The last day of the time-range. Also aliased as :to.

  • :in (<String, Hash>)

    The location to limit the views to. Can either be the two-letter ISO-3166-1 code of a country, such as “US”, or a Hash that either contains the :country key, such as {country: “US”} or the :state key, such as {state: “TX”}. Note that YouTube API only provides data for US states.


165
# File 'lib/yt/models/playlist.rb', line 165

has_report :views, Integer

#views_per_playlist_start(options = {}) ⇒ Hash<Date, Float>, ...

Returns the views_per_playlist_start grouped by the given dimension.

Examples:

Get the views_per_playlist_start for each day of last week:

resource.views_per_playlist_start since: 2.weeks.ago, until: 1.week.ago, by: :day
# => {Wed, 8 May 2014 => 12.0, Thu, 9 May 2014 => 34.0, …}

Get the views_per_playlist_start for this and last month:

resource.views_per_playlist_start since: 1.month.ago, by: :month
# => {Wed, 01 Apr 2014..Thu, 30 Apr 2014 => 12.0, Fri, 01 May 2014..Sun, 31 May 2014 => 34.0, …}

Get the views_per_playlist_start for this and last week:

resource.views_per_playlist_start since: 1.week.ago, by: :week
# => {Wed, 01 Apr 2014..Tue, 07 Apr 2014 => 20.0, Wed, 08 Apr 2014..Tue, 14 Apr 2014 => 13.0, …}

Get the views_per_playlist_start for the whole last week:

resource.views_per_playlist_start since: 2.weeks.ago, until: 1.week.ago, by: :range
# => {total: 564.0}

Get the views_per_playlist_start for the whole last week in Texas only:

resource.views_per_playlist_start since: 2.weeks.ago, until: 1.week.ago, by: :range, in: {state: 'TX'}
# => {total: 19.0}

Options Hash (options):

  • :by (Symbol) — default: :day

    The dimension to collect views_per_playlist_start by. Accepted values are: :day, :week, :month, :range.

  • :since (#to_date)

    The first day of the time-range. Also aliased as :from.

  • :until (#to_date)

    The last day of the time-range. Also aliased as :to.

  • :in (<String, Hash>)

    The location to limit the views_per_playlist_start to. Can either be the two-letter ISO-3166-1 code of a country, such as “US”, or a Hash that either contains the :country key, such as {country: “US”} or the :state key, such as {state: “TX”}. Note that YouTube API only provides data for US states.


183
# File 'lib/yt/models/playlist.rb', line 183

has_report :views_per_playlist_start, Float