Playlists

Yt::Playlist represents a YouTube playlist. Initialize using either the YouTube ID or URL:

playlist = Yt::Playlist.new id:  'PLSWYkYzOrPMRUYaLE6C9'
# => #<Yt::Playlist:0x... @id="PLSWYkYzOrPMRUYaLE6C9">

Some methods from other classes also return a Yt::Playlist object (e.g.: Yt::Account#create_playlist) or a collection of Yt::Playlist objects (e.g.: #playlists from Yt::Account and Yt::Channel).

Authentication

Most methods of Yt::Playlist retrieve public data from YouTube (e.g.: fetch a playlist’s title and items).
To use these methods (marked with   below), you only need to get a Server API key from Google and configure:

Yt.configuration.api_key = "<your api key>"             ## replace with your API key

playlist = Yt::Playlist.new id: 'PLSWYkYzOrPMRUYaLE6C9' ## use any playlist ID
playlist.title
# => "Fullscreen Arcade"

Other methods acts on behalf of YouTube accounts (e.g.: add videos to a playlist).
To use these methods (marked with   below), you need to get an API Client ID/Secret from Google, obtain an access or refresh token from the account you want to act as, and pass the account as the :auth parameter:

Yt.configuration.client_id = "<your ID>"           ## replace with your client ID
Yt.configuration.client_secret = "<your secret>"   ## replace with your client secret
account = Yt::Account.new refresh_token: "<token>" ## use the account’s refresh token

playlist = Yt::Playlist.new id: 'PLSWYkYzOrPMRUYaLE6C9', auth: account
playlist.add_video "BPNYv0vd78A"
# => #<Yt::PlaylistItem …> (the newly added playlist item)

List of Yt::Playlist methods

any authentication works Playlist’s Snippet

→ Yt docsplaylist.id # => "PLSWYkYzOrPMRUYaLE6C9"
→ Yt docsplaylist.title # => "Fullscreen Arcade"
→ Yt docsplaylist.description # => "Retro games!"
→ Yt docsplaylist.published_at # => 2013-08-14 19:14:21 UTC
→ Yt docsplaylist.thumbnail_url # => "https://i.ytimg.com/vi/7gyM4Ue9nGY/default.jpg"
→ Yt docsplaylist.channel_id # => "UCxO1tY8h1AhOz0T4ENwmpow"
→ Yt docsplaylist.channel_title # => "Fullscreen"
→ Yt docsplaylist.tags # => ["arcade", "games"]

any authentication works Playlist’s Privacy Status

→ Yt docsplaylist.privacy_status # => "public"
→ Yt docsplaylist.public? # => true
→ Yt docsplaylist.unlisted? # => false
→ Yt docsplaylist.private? # => false

must authenticate as the playlist’s account or content owner Playlist’s Updates

→ Yt docsplaylist.update title: "Videos I like", privacy_status: "public" # => true
→ Yt docsplaylist.add_video "BPNYv0vd78A" # => #<Yt::PlaylistItem …>
→ Yt docsplaylist.add_videos %w{BPNYv0vd78A 2NW_AqhkYZZ} # => [#<Yt::PlaylistItem …>]
→ Yt docsplaylist.delete_playlist_items video_id: "BPNYv0vd78A" # => [true, false]

any authentication works Playlist’s Associations

→ Yt docsplaylist.playlist_items # => #<Yt::Collections::PlaylistItems …>

List of Yt::Playlist analytics methods

By default, analytics methods return the total value for the lifetime of a playlist (e.g., all the views of a playlist).
To set specific starting and ending dates, use the :since and :until options.
To obtain one value per each day of the range you specify (rather than the total), use the by: :day option.
To limit the results to a specific location, use the :in option .

playlist.views # => {total: 949}

range = {since: 2.months.ago, until: 1.month.ago} # use a Date or String
playlist.views range # => {total: 219}
playlist.views range.merge(by: :day) # => {Wed, 8 May 2014 => 12, Thu, 9 May 2014 …}

playlist.views in: 'FR' # => {total: 45}
playlist.views in: {country: 'US'} # => {total: 113}
playlist.views in: {state: 'TX'} # => {total: 11}
# NOTE: Not all methods can be limited by US state; check the docs for details.

For brevity, the options above are omitted in the examples below.

must authenticate as the playlist’s account or content owner Playlist’s Analytics

→ Yt docsplaylist.views # => {total: 223}
→ Yt docsplaylist.average_view_duration # => {total: 234}
→ Yt docsplaylist.playlist_starts # => {total: 44}
→ Yt docsplaylist.average_time_in_playlist # => {total: 1.23}
→ Yt docsplaylist.views_per_playlist_start # => {total: 4.53}
→ Yt docsplaylist.estimated_minutes_watched # => {total: 12}

→ Yt docsplaylist.views by: :country # => {"US" => 18, "RU" => 9, …}
→ Yt docsplaylist.average_view_duration by: :country # => {"US" => 456, …}
→ Yt docsplaylist.playlist_starts by: :country # => {"US" => 7, …}
→ Yt docsplaylist.average_time_in_playlist by: :country # => {"US" => 32.0, …}
→ Yt docsplaylist.views_per_playlist_start by: :country # => {"US" => 87, …}
→ Yt docsplaylist.estimated_minutes_watched by: :country # => {"US" => 12, …}

→ Yt docsplaylist.views by: :state # => {"TX" => 8, "AZ" => 5, …}
→ Yt docsplaylist.average_view_duration by: :state # => {"SD" => 456, …}
→ Yt docsplaylist.playlist_starts by: :state # => {"ND" => 7, …}
→ Yt docsplaylist.average_time_in_playlist by: :state # => {"MA" => 32.0, …}
→ Yt docsplaylist.views_per_playlist_start by: :state # => {"TX" => 87, …}
→ Yt docsplaylist.estimated_minutes_watched by: :state # => {"TX" => 12, …}

→ Yt docsplaylist.views by: :video, includes: [:status] # => {#<Yt::Video> => 9, …}
→ Yt docsplaylist.views by: :playlist # => {#<Yt::Playlist @id=…> => 4, …}
→ Yt docsplaylist.views by: :traffic_source # => {channel: 7, …}
→ Yt docsplaylist.views by: :playback_location # => {watch: 467, embedded: 53, …}
→ Yt docsplaylist.views by: :device_type # => {mobile: 457, tv: 954, …}
→ Yt docsplaylist.views by: :related_video # => {#<Yt::Video @id=…> => 7, …}
→ Yt docsplaylist.views by: :search_term # => {"fullscreen" => 7, "music" => 3, …}
→ Yt docsplaylist.views by: :referrer # => {"Google Search" => 7, "ytimg.com" => 3, …}

→ Yt docsplaylist.estimated_minutes_watched by: :video # => {#<Yt::Video> => 9, …}
→ Yt docsplaylist.estimated_minutes_watched by: :playlist # => {#<Yt::Playlist> => …}
→ Yt docsplaylist.estimated_minutes_watched by: :traffic_source # => {channel: 7, …}
→ Yt docsplaylist.estimated_minutes_watched by: :playback_location # => {watch: …}
→ Yt docsplaylist.estimated_minutes_watched by: :device_type # => {tv: 954, …}
→ Yt docsplaylist.estimated_minutes_watched by: :related_video # => {#<Yt::Video>…}
→ Yt docsplaylist.estimated_minutes_watched by: :search_term # => {"music" => 7, …}
→ Yt docsplaylist.estimated_minutes_watched by: :referrer # => {"Facebook" => 7, …}

→ Yt docsplaylist.viewer_percentage # => {female: {'18-24' => 4.12, '25-34' => …}, …}
→ Yt docsplaylist.viewer_percentage by: :gender # => {female: 12.3, male: 87.7}
→ Yt docsplaylist.viewer_percentage by: :age_group # => {'18-24' => 4.1, '25-34' => …}

→ Yt docsplaylist.reports only: [:views] # => {views: {…}}