Fullscreen/yt-core

---
title:  "Yt::PlaylistItem"
h2: "Playlist items"
---

<p>
  <code>Yt::PlaylistItem</code> represents a <a href="https://developers.google.com/youtube/v3/docs/playlistItems">YouTube playlist item</a>.
  Initialize using its YouTube ID:
</p>

{% highlight ruby %}
item = Yt::PlaylistItem.new id: 'UEwtTGVUdXRjOUdSS0Qze'
# => #<Yt::PlaylistItem:0x... @id=UEwtTGVUdXRjOUdSS0Qze>
{% endhighlight %}

<hr />
<h4>Authentication</h4>

<p>
  Most methods of <code>Yt::PlaylistItem</code> <strong>retrieve public data</strong> from YouTube (e.g.: fetch an item’s position).<br />
  To use these methods (marked with <span class="label label-success">&nbsp;</span> below), you only need to <a href="{{ site.baseurl }}/#api_key">generate an API key</a> and configure:
</p>

{% highlight ruby %}
Yt.configuration.api_key = "<your api key>"                     ## use your API key
item = Yt::PlaylistItem.new id: 'UEwtTGVUdXRjOUdSS0Qze' ## use any playlist item ID
item.position # => 0
{% endhighlight %}

<p>
  Other methods <strong>acts on behalf of YouTube accounts</strong> (e.g.: add an item to a playlist).<br />
  To use these methods (marked with  <span class="label label-warning">&nbsp;</span> below), you need to <a href="{{ site.baseurl }}/#api_client">get an API Client ID/Secret from Google</a>, then <a href="{{ site.baseurl }}/#tokens">obtain a refresh token</a> from the account you want to act as, and finally configure the values:
</p>

{% highlight ruby %}
Yt.configuration.client_id = "<your ID>"           ## replace with your client ID
Yt.configuration.client_secret = "<your secret>"   ## replace with your client secret
Yt.configuration.refresh_token = "<token>"         ## use the account’s refresh token

Yt::PlaylistItem.insert playlist_id: 'PL-LeTutc9GRKD3DhnRF_y', video_id: 'gknzFj_0vvY'
# => #<Yt::PlaylistItem:0x... @id=UEwtTGVUdXRjOUdSS0Qze>
{% endhighlight %}

<hr />
<h4>List of <code>Yt::PlaylistItem</code> data methods</h4>
<dl>
  {% include dt.html title="Playlist item’s snippet" label="success" auth="any authentication works" %}
  <dd><a class="anchor" id="snippet"></a><div class="highlight"><pre>
{% include doc.html instance="PlaylistItem#id" %}{% include example.html object='item' method='id' result='"UEwtTGVUdXRjOUdSS0Qze"' %}
{% include doc.html instance="PlaylistItem#title" %}{% include example.html object='item' method='title' result='"First public video"' %}
{% include doc.html instance="PlaylistItem#description" %}{% include example.html object='item' method='description' result='"A YouTube video to test the yt gem."' %}
{% include doc.html instance="PlaylistItem#published_at" %}{% include example.html object='item' method='published_at' result='2016-11-18 23:40:55 UTC' %}
{% include doc.html instance="PlaylistItem#thumbnail_url" %}{% include example.html object='item' method='thumbnail_url' result='"https://i.ytimg.com/vi/gknzFj_0vvY/default.jpg"' %}
{% include doc.html instance="PlaylistItem#channel_id" %}{% include example.html object='item' method='channel_id' result='"UCwCnUcLcb9-eSrHa_RQGkQQ"' %}
{% include doc.html instance="PlaylistItem#channel_title" %}{% include example.html object='item' method='channel_title' result='"Yt Test"' %}
{% include doc.html instance="PlaylistItem#playlist_id" %}{% include example.html object='item' method='playlist_id' result='"PL-LeTutc9GRKD3yBDhnRF_yE8UTaQI5Jf"' %}
{% include doc.html instance="PlaylistItem#position" %}{% include example.html object='item' method='position' result='0' %}
{% include doc.html instance="PlaylistItem#video_id" %}{% include example.html object='item' method='video_id' result='"gknzFj_0vvY"' %}</pre>
  </div></dd>

  {% include dt.html title="Playlist item’s status" label="success" auth="any authentication works" %}
  <dd><a class="anchor" id="status"></a><div class="highlight"><pre>
{% include doc.html instance="PlaylistItem#privacy_status" %}{% include example.html object='item' method='privacy_status' result='"public"' %}</pre>
  </div></dd>
</dl>
<p>
  To limit the number of HTTP requests, use <code>select</code> to specify which <a href="https://developers.google.com/youtube/v3/docs/playlistItems/list#part">parts</a> of the item’s data to load:
</p>
<dl>
  <dd><a class="anchor" id="select"></a><div class="highlight"><pre>
{% include example.html object='slow = item' result='without select: 2 HTTP requests' %}
{% include example.html object='slow' method='title' result='one HTTP request to fetch the item’s snippet' %}
{% include example.html object='slow' method='privacy_status' result='=> another HTTP request to fetch the item’s status' %}

{% include doc.html instance="PlaylistItem#select" %}{% include example.html object='fast = item' method='select' params=' <span class="ss">:snippet</span><span class="p">,</span> <span class="ss">:status</span>' result='with select: 1 HTTP request' %}
{% include example.html object='fast' method='title' result='one HTTP request to fetch both the item’s snippet and status' %}
{% include example.html object='fast' method='privacy_status' result='=> no extra HTTP requests' %}</pre>
  </div></dd>
</dl>
<dl>
  {% include dt.html title="Adding and removing a playlist item" label="warning" auth="must authenticate as the channel’s account" %}
  <dd><a class="anchor" id="insert_remove"></a><div class="highlight"><pre>
{% include doc.html class="PlaylistItem#insert" %}{% include example.html object='item = <span class="no">Yt</span><span class="o">::</span><span class="no">PlaylistItem</span>' method='insert' params=' <span class="ss">playlist_id:</span> <span class="s1">"PL-..."</span>, <span class="ss">video_id:</span> <span class="s1">"gknzFj_0vvY"</span>' %}
{% include doc.html instance="PlaylistItem#delete" %}{% include example.html object='item' method='delete' result='true' %}</pre>
  </div></dd>
</dl>