yt 0.14.7 → 0.15.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: e26f7e87270dc0509123f5ea88302a280e54da66
-  data.tar.gz: 73f82aca406690352fb266e2129bc4288be40f4a
+  metadata.gz: 54209e7c3dedc665ad4d6b0d93bcf6c6d9d6f546
+  data.tar.gz: 6e09959e44cbf2aad7bcf29df8dfa25f6cc903c6
 SHA512:
-  metadata.gz: 7c113de8d650081766da2ba86cbc85e2e038e02cf2e8f358ab76feabeacae8ca2fc5d29447e68608a0a31d2466177fe44722b4bfe2d25a40cb1004e7edfa2a50
-  data.tar.gz: 6600285bcf6beb7fb56d38bdb555cba51e745a0237c2a21059f9b3905faeec6487866b1deb3b028751b67a4d31fb2a27684c9f9bd63ea2f5eb12bdbdd7538c3b
+  metadata.gz: 3a83c419303aa9980ecc4769c711798742aa0a3a77202ef04e18300ba32d414994f9e2b3fa6dd5042489e5b9caaca75966c4bdcfe1a3e1a995f641d176f5a89f
+  data.tar.gz: 5f31bea6b6e1d473a42f73f2971efd7567220d0283c645b488ea6f35870be5e460352346996469179408f11fc9190ce61e17ce2ac435499ae89e732ead1e65b0

data/CHANGELOG.md

@@ -6,6 +6,25 @@ For more information about changelogs, check
 [Keep a Changelog](http://keepachangelog.com) and
 [Vandamme](http://tech-angels.github.io/vandamme).
 
+## 0.15.0 - 2015-04-19
+
+**How to upgrade**
+
+If your code never calls the `viewer_percentage(gender: [:female|:male])` method
+on a Channel or Video object, then you are good to go.
+
+If it does, then replace your calls to `viewer_percentage(gender: :female)`
+with `viewer_percentage(by: gender)[:female]`, and do the same for `:male`.
+
+Note that the _plural_ `viewer_percentages` method still works but it’s
+deprecated: you should use `viewer_percentage` instead.
+
+* [ENHANCEMENT] Remove `:gender` option in `viewer_percentage` in favor of a more generic `:by`
+* [FEATURE] New `by: :gender` option for reports, to return viewer percentage by gender
+* [FEATURE] New `by: :age_group` option for reports, to return viewer percentage by age group
+* [ENHANCEMENT] The viewer percentage report now accepts start/end date options (like any other report)
+* [DEPRECATION] Deprecate `viewer_percentages` in favor of `viewer_percentage`.
+
 ## 0.14.7 - 2015-04-17
 
 * [FEATURE] New `by: :device_type` option for reports, to return views and estimated watched minutes (channels) by device

data/README.md

@@ -41,7 +41,7 @@ To install on your system, run
 
 To use inside a bundled Ruby project, add this line to the Gemfile:
 
-    gem 'yt', '~> 0.14.7'
+    gem 'yt', '~> 0.15.0'
 
 Since the gem follows [Semantic Versioning](http://semver.org),
 indicating the full version in your Gemfile (~> *major*.*minor*.*patch*)
@@ -156,7 +156,7 @@ Use [Yt::Channel](http://rubydoc.info/github/Fullscreen/yt/master/Yt/Models/Chan
 * retrieve the views and estimated minutes watched by video
 * retrieve the views and estimated minutes watched by playlist
 * retrieve the views and estimated minutes watched by device type
-* retrieve the viewer percentage of a channel by gender and age group
+* retrieve the viewer percentage of a channel by gender, by age group or by both
 
 ```ruby
 # Channels can be initialized with ID or URL
@@ -215,8 +215,7 @@ channel.favorites_removed from: '2014-08-30', to: '2014-08-31' #=> {Sat, 30 Aug
 channel.estimated_minutes_watched #=> {Sun, 22 Feb 2015=>2433258.0, Mon, 23 Feb 2015=>2634360.0, …}
 channel.average_view_duration #=>  {Sun, 22 Feb 2015=>329.0, Mon, 23 Feb 2015=>326.0, …}
 channel.average_view_percentage # {Sun, 22 Feb 2015=>38.858253094977265, Mon, 23 Feb 2015=>37.40014235438217, …}
-channel.viewer_percentages #=> {female: {'18-24' => 12.12, '25-34' => 16.16,…}…}
-channel.viewer_percentage(gender: :male) #=> 49.12
+channel.viewer_percentage #=> {female: {'18-24' => 12.12, '25-34' => 16.16,…}…}
 
 channel.views since: 7.days.ago, by: :traffic_source #=> {advertising: 10.0, related_video: 20.0, promoted: 5.0, subscriber: 1.0, channel: 3.0, other: 7.0}
 channel.estimated_minutes_watched since: 7.days.ago, by: :traffic_source #=> {annotation: 10.0, external_app: 20.0, external_url: 5.0, embedded: 1.0, search: 3.0}
@@ -258,8 +257,8 @@ channel.subscribers_lost from: '2014-08-30', to: '2014-08-31' #=> {Sat, 30 Aug 2
 channel.estimated_minutes_watched #=> {Sun, 22 Feb 2015=>2433258.0, Mon, 23 Feb 2015=>2634360.0, …}
 channel.average_view_duration #=>  {Sun, 22 Feb 2015=>329.0, Mon, 23 Feb 2015=>326.0, …}
 channel.average_view_percentage # {Sun, 22 Feb 2015=>38.858253094977265, Mon, 23 Feb 2015=>37.40014235438217, …}
-channel.viewer_percentages #=> {female: {'18-24' => 12.12, '25-34' => 16.16,…}…}
-channel.viewer_percentage(gender: :female) #=> 49.12
+channel.viewer_percentage since: 7.days.ago #=> {female: {'18-24' => 12.12, '25-34' => 16.16,…}…}
+
 channel.views since: 7.days.ago, by: :traffic_source #=> {advertising: 10.0, related_video: 20.0, promoted: 5.0, subscriber: 1.0, channel: 3.0, other: 7.0}
 channel.estimated_minutes_watched since: 7.days.ago, by: :traffic_source #=> {annotation: 10.0, external_app: 20.0, external_url: 5.0, embedded: 1.0, search: 3.0}
 channel.views since: 7.days.ago, by: :playback_location #=> {embedded: 34.0, watch: 467.0, channel: 462.0, other: 3.0}
@@ -275,6 +274,8 @@ channel.estimated_minutes_watched since: 7.days.ago, by: :playlist #=> {#<Yt::Mo
 channel.views since: 7.days.ago, by: :device_type #=> {mobile: 144473.0, unknown_platform: 840.0, game_console: 4940.0, desktop: 102889.0, tv: 4134.0, tablet: 50189.0}
 channel.estimated_minutes_watched since: 7.days.ago, by: :device_type #=> {mobile: 144473.0, unknown_platform: 840.0, game_console: 4940.0, desktop: 102889.0, tv: 4134.0, tablet: 50189.0}
 channel.monetized_playbacks_on 5.days.ago #=> 123.0
+channel.viewer_percentage since: 7.days.ago, by: :gender #=> {female: 49.12, male: 50.88}
+channel.viewer_percentage since: 7.days.ago, by: :age_group #=> {'18-24' => 12.12, '25-34' => 16.16,…}
 
 channel.content_owner #=> 'CMSname'
 channel.linked_at #=> Wed, 28 May 2014
@@ -299,7 +300,7 @@ Use [Yt::Video](http://rubydoc.info/github/Fullscreen/yt/master/Yt/Models/Video)
 * retrieve the views of a video by embedded player location
 * retrieve the views of a video by related video
 * retrieve the views of a video by device type
-* retrieve the viewer percentage of a video by gender and age group
+* retrieve the viewer percentage of a video by gender, by age group or by both
 * retrieve data about live-streaming videos
 * retrieve the advertising options of a video
 
@@ -396,14 +397,15 @@ video.favorites_removed from: '2014-08-30', to: '2014-08-31' #=> {Sat, 30 Aug 20
 video.average_view_duration #=>  {Sun, 22 Feb 2015=>329.0, Mon, 23 Feb 2015=>326.0, …}
 video.average_view_percentage # {Sun, 22 Feb 2015=>38.858253094977265, Mon, 23 Feb 2015=>37.40014235438217, …}
 video.estimated_minutes_watched #=> {Sun, 22 Feb 2015=>2433258.0, Mon, 23 Feb 2015=>2634360.0, …}
-video.viewer_percentages #=> {female: {'18-24' => 12.12, '25-34' => 16.16,…}…}
-video.viewer_percentage(gender: :female) #=> 49.12
+video.viewer_percentage #=> {female: {'18-24' => 12.12, '25-34' => 16.16,…}…}
 
 video.views since: 7.days.ago, by: :traffic_source #=> {advertising: 10.0, related_video: 20.0, promoted: 5.0, subscriber: 1.0, channel: 3.0, other: 7.0}
 video.views since: 7.days.ago, by: :playback_location #=> {:embedded=>6.0, :watch=>11.0}
 video.views since: 7.days.ago, by: :embedded_player_location #=> {"fullscreen.net"=>45.0, "linkedin.com"=>5.0, "mashable.com"=>1.0, "unknown"=>1.0}
 video.views since: 7.days.ago, by: :related_video #=> {#<Yt::Models::Video @id=...>: 10.0, #<Yt::Models::Video @id=...>: 20.0, …}
 video.views since: 7.days.ago, by: :device_type #=> {mobile: 144473.0, unknown_platform: 840.0, game_console: 4940.0, desktop: 102889.0, tv: 4134.0, tablet: 50189.0}
+video.viewer_percentage since: 7.days.ago, by: :gender #=> {female: 49.12, male: 50.88}
+video.viewer_percentage since: 7.days.ago, by: :age_group #=> {'18-24' => 12.12, '25-34' => 16.16,…}
 
 video.delete #=> true
 ```
@@ -429,12 +431,15 @@ video.average_view_percentage # {Sun, 22 Feb 2015=>38.858253094977265, Mon, 23 F
 video.estimated_minutes_watched #=> {Sun, 22 Feb 2015=>2433258.0, Mon, 23 Feb 2015=>2634360.0, …}
 video.impressions_on 5.days.ago #=> 157.0
 video.monetized_playbacks_on 5.days.ago #=> 123.0
-
-video.viewer_percentages #=> {female: {'18-24' => 12.12, '25-34' => 16.16,…}…}
-video.viewer_percentage(gender: :female) #=> 49.12
+video.viewer_percentage #=> {female: {'18-24' => 12.12, '25-34' => 16.16,…}…}
 
 video.views since: 7.days.ago, by: :traffic_source #=> {advertising: 10.0, related_video: 20.0, promoted: 5.0, subscriber: 1.0, channel: 3.0, other: 7.0}
 video.views since: 7.days.ago, by: :playback_location #=> {:embedded=>6.0, :watch=>11.0}
+video.views since: 7.days.ago, by: :embedded_player_location #=> {"fullscreen.net"=>45.0, "linkedin.com"=>5.0, "mashable.com"=>1.0, "unknown"=>1.0}
+video.views since: 7.days.ago, by: :related_video #=> {#<Yt::Models::Video @id=...>: 10.0, #<Yt::Models::Video @id=...>: 20.0, …}
+video.views since: 7.days.ago, by: :device_type #=> {mobile: 144473.0, unknown_platform: 840.0, game_console: 4940.0, desktop: 102889.0, tv: 4134.0, tablet: 50189.0}
+video.viewer_percentage since: 7.days.ago, by: :gender #=> {female: 49.12, male: 50.88}
+video.viewer_percentage since: 7.days.ago, by: :age_group #=> {'18-24' => 12.12, '25-34' => 16.16,…}
 
 video.ad_formats #=> ["standard_instream", "trueview_instream"]
 ```

data/lib/yt/associations/has_reports.rb

@@ -43,10 +43,10 @@ module Yt
 
       def define_metric_method(metric)
         define_method metric do |options = {}|
-          from = options[:since] || options[:from] || 5.days.ago
-          to = options[:until] || options[:to] || 1.day.ago
+          from = options[:since] || options[:from] || (metric == :viewer_percentage ? 3.months.ago : 5.days.ago)
+          to = options[:until] || options[:to] || (metric == :viewer_percentage ? Date.today : 1.day.ago)
           range = Range.new *[from, to].map(&:to_date)
-          dimension = options[:by] || :day
+          dimension = options[:by] || (metric == :viewer_percentage ? :gender_age_group : :day)
 
           ivar = instance_variable_get "@#{metric}_#{dimension}"
           instance_variable_set "@#{metric}_#{dimension}", ivar || {}

data/lib/yt/associations/has_viewer_percentages.rb

@@ -4,8 +4,10 @@ module Yt
     #
     # YouTube resources with viewer percentage reports are:
     # {Yt::Models::Channel channels} and {Yt::Models::Channel videos}.
+    # @deprecated Use {#viewer_percentage} instead.
     module HasViewerPercentages
       # @!macro has_viewer_percentages
+      #   @!deprecated Use {#viewer_percentage} instead.
       #   @!method viewer_percentages
       #     @return [Hash<Symbol,Hash<String,Float>>] the viewer percentages.
       #       The first-level hash identifies the genres (:female, :male).
@@ -20,7 +22,7 @@ module Yt
       #     @example Return the % of male viewers of a video
       #       channel.viewer_percentage(gender: :male) #=> 52.02
 
-      # Defines two public instance methods to access the viewer percentages of
+      # Defines one public instance methods to access the viewer percentages of
       # a resource for a specific metric.
       # @example Adds +viewer_percentages+ and +viewer_percentage+ on Channel.
       #   class Channel < Resource
@@ -30,23 +32,15 @@ module Yt
         require 'yt/collections/viewer_percentages'
 
         define_viewer_percentages_method
-        define_viewer_percentage_method
       end
 
     private
 
       def define_viewer_percentages_method
-        # @todo: add options like start and end date
         define_method :viewer_percentages do
           @viewer_percentages ||= Collections::ViewerPercentages.of(self)[id]
         end
       end
-
-      def define_viewer_percentage_method
-        define_method :viewer_percentage do |filters = {}|
-          viewer_percentages[filters[:gender]].values.sum.round(2)
-        end
-      end
     end
   end
 end

data/lib/yt/collections/playlist_items.rb

@@ -13,6 +13,12 @@ module Yt
 
     private
 
+      def attributes_for_new_item(data)
+        snippet = data.fetch 'snippet', {}
+        data['snippet'].reverse_merge! complete: snippet.key?('position')
+        super(data)
+      end
+
       # @return [Hash] the parameters to submit to YouTube to list playlist items.
       # @see https://developers.google.com/youtube/v3/docs/playlistItems/list
       def list_params

data/lib/yt/collections/reports.rb

@@ -11,6 +11,9 @@ module Yt
         hash[:video] = {name: 'video', parse: ->(video_id) { Yt::Video.new id: video_id, auth: @auth } }
         hash[:playlist] = {name: 'playlist', parse: ->(playlist_id) { Yt::Playlist.new id: playlist_id, auth: @auth } }
         hash[:device_type] = {name: 'deviceType', parse: ->(type) { type.downcase.to_sym } }
+        hash[:gender_age_group] = {name: 'gender,ageGroup', parse: ->(gender) { gender.downcase.to_sym }}
+        hash[:gender] = {name: 'gender', parse: ->(gender) { gender.downcase.to_sym } }
+        hash[:age_group] = {name: 'ageGroup', parse: ->(age_group) { age_group[3..-1] } }
       end
 
       # @see https://developers.google.com/youtube/analytics/v1/dimsmets/dims#Traffic_Source_Dimensions
@@ -46,7 +49,13 @@ module Yt
       def within(days_range, dimension, try_again = true)
         @days_range = days_range
         @dimension = dimension
-        Hash[*flat_map{|daily_value| daily_value}]
+        if dimension == :gender_age_group # array of array
+          Hash.new{|h,k| h[k] = Hash.new 0.0}.tap do |hash|
+            each{|gender, age_group, value| hash[gender][age_group[3..-1]] = value}
+          end
+        else
+          Hash[*flat_map{|value| [value.first, value.last]}]
+        end
       # NOTE: Once in a while, YouTube responds with 400 Error and the message
       # "Invalid query. Query did not conform to the expectations."; in this
       # case running the same query after one second fixes the issue. This is
@@ -60,7 +69,7 @@ module Yt
     private
 
       def new_item(data)
-        [instance_exec(data.first, &DIMENSIONS[@dimension][:parse]), data.last]
+        [instance_exec(data.first, &DIMENSIONS[@dimension][:parse]), *data[1..-1]]
       end
 
       # @see https://developers.google.com/youtube/analytics/v1/content_owner_reports

data/lib/yt/collections/videos.rb

@@ -17,7 +17,7 @@ module Yt
 
       def attributes_for_new_item(data)
         id = use_list_endpoint? ? data['id'] : data['id']['videoId']
-        snippet = data['snippet'].reverse_merge includes_tags: false if data['snippet']
+        snippet = data['snippet'].reverse_merge complete: false if data['snippet']
         {}.tap do |attributes|
           attributes[:id] = id
           attributes[:snippet] = snippet
@@ -39,7 +39,7 @@ module Yt
             video = videos.find{|v| v.id == item['id']['videoId']}
             parts.each do |part|
               item[part] = case part
-                when 'snippet' then video.snippet.data.merge includes_tags: true
+                when 'snippet' then video.snippet.data.merge complete: true
                 when 'status' then video.status.data
                 when 'statistics' then video.statistics_set.data
                 when 'contentDetails' then video.content_detail.data

data/lib/yt/collections/viewer_percentages.rb

@@ -2,6 +2,7 @@ require 'yt/collections/base'
 
 module Yt
   module Collections
+    # @deprecated Use {Yt::Collections::Reports} instead.
     class ViewerPercentages < Base
       delegate :[], to: :all
 

data/lib/yt/models/channel.rb

@@ -58,6 +58,10 @@ module Yt
       # @macro has_report
       has_report :monetized_playbacks
 
+      # @macro has_report
+      has_report :viewer_percentage
+
+      # @deprecated Use {#has_report :viewer_percentage}.
       # @macro has_viewer_percentages
       has_viewer_percentages
 

data/lib/yt/models/playlist_item.rb

@@ -5,7 +5,7 @@ module Yt
     # Provides methods to interact with YouTube playlist items.
     # @see https://developers.google.com/youtube/v3/docs/playlistItems
     class PlaylistItem < Resource
-      delegate :channel_id, :channel_title, :playlist_id, :position, :video_id,
+      delegate :channel_id, :channel_title, :playlist_id, :video_id,
         :video, to: :snippet
 
       def delete(options = {})
@@ -17,6 +17,20 @@ module Yt
         !@id.nil?
       end
 
+      # Returns the position of the item in the playlist.
+      # Since YouTube API does not return the position on PlaylistItem#create,
+      # the memoized @snippet is erased if the video was instantiated like that,
+      # so that the full snippet (with position) is loaded, rather than the
+      # partial one.
+      # @see https://developers.google.com/youtube/v3/docs/playlistItems
+      # @return [Integer] the order in which the item appears in a playlist.
+      def position
+        unless snippet.position || snippet.complete? || @auth.nil?
+          @snippet = nil
+        end
+        snippet.position
+      end
+
     private
 
       def resource_id

data/lib/yt/models/snippet.rb

@@ -146,16 +146,17 @@ module Yt
         @video ||= Video.new id: video_id, auth: @auth if video_id
       end
 
-      # Returns whether YouTube API includes tags in this snippet.
-      # YouTube API only returns tags on Videos#list, not on Videos#search.
+      # Returns whether YouTube API includes all attributes in this snippet.
+      # For instance, YouTube API only returns tags on Videos#list, not on
+      # Videos#search. And returns position on PlaylistItems#list, not on
+      # PlaylistItems#insert.
       # This method is used to guarantee that, when a video was instantiated
-      # by calling account.videos or channel.videos, then video.tags is not
-      # simply returned as empty, but an additional call to Videos#list is
-      # made to retrieve the correct tags.
+      # by one of the methods above, an additional call to is made to retrieve
+      # the full snippet in case an attribute is missing.
       # @see https://developers.google.com/youtube/v3/docs/videos
-      # @return [Boolean] whether YouTube API includes tags in this snippet.
-      def includes_tags
-        @includes_tags ||= data.fetch :includes_tags, true
+      # @return [Boolean] whether YouTube API includes the complete snippet.
+      def complete?
+        @complete ||= data.fetch :complete, true
       end
 
     private

data/lib/yt/models/video.rb

@@ -89,6 +89,10 @@ module Yt
       # @macro has_report
       has_report :monetized_playbacks
 
+      # @macro has_report
+      has_report :viewer_percentage
+
+      # @deprecated Use {#has_report :viewer_percentage}.
       # @macro has_viewer_percentages
       has_viewer_percentages
 
@@ -124,7 +128,7 @@ module Yt
       # @return [Array<Yt::Models::Tag>] the list of keyword tags associated
       #   with the video.
       def tags
-        unless snippet.tags.any? || snippet.includes_tags || @auth.nil?
+        unless snippet.tags.any? || snippet.complete? || @auth.nil?
           @snippet = nil
         end
         snippet.tags

data/lib/yt/version.rb

@@ -1,3 +1,3 @@
 module Yt
-  VERSION = '0.14.7'
+  VERSION = '0.15.0'
 end

data/spec/collections/reports_spec.rb

@@ -9,7 +9,7 @@ describe Yt::Collections::Reports do
   let(:msg) { {response_body: {error: {errors: [error]}}}.to_json }
 
   describe '#within' do
-    let(:result) { reports.within Range.new(5.days.ago, 4.days.ago) }
+    let(:result) { reports.within Range.new(5.days.ago, 4.days.ago), :day }
     context 'given the request raises error 400 with "Invalid Query" message' do
       let(:reason) { 'badRequest' }
       let(:message) { 'Invalid query. Query did not conform to the expectations' }
@@ -22,7 +22,7 @@ describe Yt::Collections::Reports do
       end
 
       context 'but returns a success code 2XX the second time' do
-        before { try_again.and_return [1,2] }
+        before { try_again.and_return [[1,2]] }
         it { expect{result}.not_to fail }
       end
     end

data/spec/requests/as_account/account_spec.rb

@@ -51,12 +51,12 @@ describe Yt::Account, :device_app do
     end
 
     describe '.includes(:snippet)' do
-      let(:video) { $account.videos.includes(:snippet).first }
+      let(:video) { $account.videos.first }
 
       specify 'eager-loads the *full* snippet of each video' do
         expect(video.instance_variable_defined? :@snippet).to be true
         expect(video.channel_title).to be
-        expect(video.snippet.includes_tags).to be true
+        expect(video.snippet).to be_complete
       end
     end
 

data/spec/requests/as_account/authentications_spec.rb

@@ -109,10 +109,13 @@ describe Yt::Account, :device_app do
         it { expect{account.authentication}.to raise_error Yt::Errors::MissingAuth }
       end
 
-      context 'and an invalid device code' do
-        before { attrs[:device_code] = '--not-a-valid-device-code--' }
-        it { expect{account.authentication}.to raise_error Yt::Errors::MissingAuth }
-      end
+      # NOTE: This test is commented out because of YouTube irrational behavior
+      # of using to return "MissingAuth" when passing a wrong device code, and
+      # now randomly returning `{"error"=>"internal_failure"}` instead.
+      # context 'and an invalid device code' do
+      #   before { attrs[:device_code] = '--not-a-valid-device-code--' }
+      #   it { expect{account.authentication}.to raise_error Yt::Errors::MissingAuth }
+      # end
     end
 
     context 'given no token or code' do

data/spec/requests/as_account/channel_spec.rb

@@ -26,7 +26,7 @@ describe Yt::Channel, :device_app do
 
       specify 'returns the videos in the channel without their tags' do
         expect(video).to be_a Yt::Video
-        expect(video.snippet.includes_tags).to be false
+        expect(video.snippet).not_to be_complete
       end
 
       describe '.where(id: *anything*)' do
@@ -175,6 +175,7 @@ describe Yt::Channel, :device_app do
       expect{channel.estimated_minutes_watched}.not_to raise_error
       expect{channel.average_view_duration}.not_to raise_error
       expect{channel.average_view_percentage}.not_to raise_error
+      expect{channel.viewer_percentage}.not_to raise_error
       expect{channel.earnings}.to raise_error Yt::Errors::Unauthorized
       expect{channel.impressions}.to raise_error Yt::Errors::Unauthorized
       expect{channel.monetized_playbacks}.to raise_error Yt::Errors::Unauthorized
@@ -195,9 +196,9 @@ describe Yt::Channel, :device_app do
       expect{channel.impressions_on 3.days.ago}.to raise_error Yt::Errors::Unauthorized
     end
 
+    # @deprecated, use channel.viewer_percentage instead
     it 'returns valid reports for channel-related demographics' do
       expect{channel.viewer_percentages}.not_to raise_error
-      expect{channel.viewer_percentage}.not_to raise_error
     end
 
     it 'cannot give information about its content owner' do

data/spec/requests/as_account/playlist_item_spec.rb

@@ -5,7 +5,7 @@ describe Yt::PlaylistItem, :device_app do
   subject(:item) { Yt::PlaylistItem.new id: id, auth: $account }
 
   context 'given an existing playlist item' do
-    let(:id) { 'PLjW_GNR5Ir0GWEP_oveGBNjTvKkYyZfsna1TZDCBP-Z8' }
+    let(:id) { 'PLjW_GNR5Ir0GMlbJzA-aW0UV8TchJFb8p3uzrLNcZKPY' }
 
     it 'returns valid metadata' do
       expect(item.title).to be_a String

data/spec/requests/as_account/playlist_spec.rb

@@ -7,7 +7,7 @@ describe Yt::Playlist, :device_app do
   subject(:playlist) { Yt::Playlist.new id: id, auth: $account }
 
   context 'given an existing playlist' do
-    let(:id) { 'PLSWYkYzOrPMRCK6j0UgryI8E0NHhoVdRc' }
+    let(:id) { 'PLSWYkYzOrPMT9pJG5St5G0WDalhRzGkU4' }
 
     it 'returns valid metadata' do
       expect(playlist.title).to be_a String
@@ -21,6 +21,8 @@ describe Yt::Playlist, :device_app do
     end
 
     it { expect(playlist.playlist_items.first).to be_a Yt::PlaylistItem }
+    it { expect(playlist.playlist_items.first.snippet).to be_complete }
+    it { expect(playlist.playlist_items.first.position).not_to be_nil }
   end
 
   context 'given an unknown playlist' do
@@ -31,7 +33,7 @@ describe Yt::Playlist, :device_app do
   end
 
   context 'given someone else’s playlist' do
-    let(:id) { 'PLSWYkYzOrPMRCK6j0UgryI8E0NHhoVdRc' }
+    let(:id) { 'PLSWYkYzOrPMT9pJG5St5G0WDalhRzGkU4' }
     let(:video_id) { 'MESycYJytkU' }
 
     it { expect{playlist.delete}.to fail.with 'forbidden' }
@@ -137,6 +139,20 @@ describe Yt::Playlist, :device_app do
         it { expect(playlist.add_video(video_id, position: 0).position).to be 0 }
       end
 
+      # NOTE: This test sounds redundant, but it’s actually a reflection of
+      # another irrational behavior of YouTube API. In short, if you add a new
+      # video to a playlist, the returned item does not have the "position"
+      # information. You need an extra call to get it. When YouTube fixes this
+      # behavior, this test (and related code) will go away.
+      describe 'adding the video' do
+        let(:item) { playlist.add_video video_id }
+
+        specify 'returns an item without its position' do
+          expect(item.snippet).not_to be_complete
+          expect(item.position).not_to be_nil # after reloading
+        end
+      end
+
       describe 'can be removed' do
         before { playlist.add_video video_id }
 

data/spec/requests/as_account/video_spec.rb

@@ -292,6 +292,7 @@ describe Yt::Video, :device_app do
       expect{video.estimated_minutes_watched}.not_to raise_error
       expect{video.average_view_duration}.not_to raise_error
       expect{video.average_view_percentage}.not_to raise_error
+      expect{video.viewer_percentage}.not_to raise_error
       expect{video.earnings}.to raise_error Yt::Errors::Unauthorized
       expect{video.impressions}.to raise_error Yt::Errors::Unauthorized
       expect{video.monetized_playbacks}.to raise_error Yt::Errors::Unauthorized
@@ -313,9 +314,9 @@ describe Yt::Video, :device_app do
       expect{video.impressions_on 3.days.ago}.to raise_error Yt::Errors::Unauthorized
     end
 
+    # @deprecated, use video.viewer_percentage instead
     it 'returns valid reports for video-related demographics' do
       expect{video.viewer_percentages}.not_to raise_error
-      expect{video.viewer_percentage}.not_to raise_error
     end
   end
 

data/spec/requests/as_content_owner/channel_spec.rb

@@ -311,7 +311,7 @@ describe Yt::Channel, :partner do
 
       describe 'shares can be retrieved for a specific day' do
         context 'in which the channel was partnered' do
-          let(:shares) { channel.shares_on 5.days.ago}
+          let(:shares) { channel.shares_on ENV['YT_TEST_PARTNER_VIDEO_DATE']}
           it { expect(shares).to be_a Float }
         end
 
@@ -845,6 +845,58 @@ describe Yt::Channel, :partner do
         end
       end
 
+      describe 'viewer percentage can be retrieved for a range of days' do
+        let(:viewer_percentage) { channel.viewer_percentage since: 1.year.ago, until: 10.days.ago}
+        it { expect(viewer_percentage).to be_a Hash }
+      end
+
+      describe 'viewer_percentage can be grouped by gender and age group' do
+        let(:range) { {since: 1.year.ago.to_date, until: 1.week.ago.to_date} }
+        let(:keys) { range.values }
+
+        specify 'without a :by option (default)' do
+          viewer_percentage = channel.viewer_percentage range
+          expect(viewer_percentage.keys).to match_array [:female, :male]
+          expect(viewer_percentage[:female].keys - %w(65- 35-44 45-54 13-17 25-34 55-64 18-24)).to be_empty
+          expect(viewer_percentage[:female].values).to all(be_instance_of Float)
+          expect(viewer_percentage[:male].keys - %w(65- 35-44 45-54 13-17 25-34 55-64 18-24)).to be_empty
+          expect(viewer_percentage[:male].values).to all(be_instance_of Float)
+        end
+
+        specify 'with the :by option set to :gender_age_group' do
+          viewer_percentage = channel.viewer_percentage range.merge by: :gender_age_group
+          expect(viewer_percentage.keys).to match_array [:female, :male]
+          expect(viewer_percentage[:female].keys - %w(65- 35-44 45-54 13-17 25-34 55-64 18-24)).to be_empty
+          expect(viewer_percentage[:female].values).to all(be_instance_of Float)
+          expect(viewer_percentage[:male].keys - %w(65- 35-44 45-54 13-17 25-34 55-64 18-24)).to be_empty
+          expect(viewer_percentage[:male].values).to all(be_instance_of Float)
+        end
+      end
+
+      describe 'viewer_percentage can be grouped by gender' do
+        let(:range) { {since: 1.year.ago.to_date, until: 1.week.ago.to_date} }
+        let(:keys) { range.values }
+
+        specify 'with the :by option set to :gender' do
+          viewer_percentage = channel.viewer_percentage range.merge by: :gender
+          expect(viewer_percentage.keys).to match_array [:female, :male]
+          expect(viewer_percentage[:female]).to be_a Float
+          expect(viewer_percentage[:male]).to be_a Float
+        end
+      end
+
+      describe 'viewer_percentage can be grouped by age group' do
+        let(:range) { {since: 1.year.ago.to_date, until: 1.week.ago.to_date} }
+        let(:keys) { range.values }
+
+        specify 'with the :by option set to :age_group' do
+          viewer_percentage = channel.viewer_percentage range.merge by: :age_group
+          expect(viewer_percentage.keys - %w(65- 35-44 45-54 13-17 25-34 55-64 18-24)).to be_empty
+          expect(viewer_percentage.values).to all(be_instance_of Float)
+        end
+      end
+
+      # @deprecated, use channel.viewer_percentage instead
       specify 'viewer percentages by gender and age range can be retrieved' do
         expect(channel.viewer_percentages[:female]['18-24']).to be_a Float
         expect(channel.viewer_percentages[:female]['25-34']).to be_a Float
@@ -858,9 +910,6 @@ describe Yt::Channel, :partner do
         expect(channel.viewer_percentages[:male]['45-54']).to be_a Float
         expect(channel.viewer_percentages[:male]['55-64']).to be_a Float
         expect(channel.viewer_percentages[:male]['65-']).to be_a Float
-
-        expect(channel.viewer_percentage(gender: :male)).to be_a Float
-        expect(channel.viewer_percentage(gender: :female)).to be_a Float
       end
 
       specify 'information about its content owner can be retrieved' do

data/spec/requests/as_content_owner/video_spec.rb

@@ -15,7 +15,7 @@ describe Yt::Video, :partner do
 
       describe 'earnings can be retrieved for a specific day' do
         context 'in which the video made any money' do
-          let(:earnings) {video.earnings_on 5.days.ago}
+          let(:earnings) {video.earnings_on ENV['YT_TEST_PARTNER_VIDEO_DATE']}
           it { expect(earnings).to be_a Float }
         end
 
@@ -26,22 +26,14 @@ describe Yt::Video, :partner do
       end
 
       describe 'earnings can be retrieved for a range of days' do
-        let(:date) { 4.days.ago }
-
-        specify 'with a given start (:since option)' do
-          expect(video.earnings(since: date).keys.min).to eq date.to_date
-        end
+        let(:date) { ENV['YT_TEST_PARTNER_VIDEO_DATE'] }
 
-        specify 'with a given end (:until option)' do
-          expect(video.earnings(until: date).keys.max).to eq date.to_date
-        end
-
-        specify 'with a given start (:from option)' do
-          expect(video.earnings(from: date).keys.min).to eq date.to_date
+        specify 'with a given start and end (:since / :until option)' do
+          expect(video.earnings(since: date, until: date).keys.min).to eq date.to_date
         end
 
-        specify 'with a given end (:to option)' do
-          expect(video.earnings(to: date).keys.max).to eq date.to_date
+        specify 'with a given start and end (:from / :to option)' do
+          expect(video.earnings(from: date, to: date).keys.min).to eq date.to_date
         end
       end
 
@@ -113,7 +105,7 @@ describe Yt::Video, :partner do
       end
 
       describe 'views can be grouped by embedded player location' do
-        let(:range) { {since: 4.days.ago, until: 3.days.ago} }
+        let(:range) { {since: ENV['YT_TEST_PARTNER_VIDEO_DATE'], until: 3.days.ago} }
 
         specify 'with the :by option set to :embedded_player_location' do
           views = video.views range.merge by: :embedded_player_location
@@ -142,7 +134,7 @@ describe Yt::Video, :partner do
 
       describe 'comments can be retrieved for a specific day' do
         context 'in which the video was partnered' do
-          let(:comments) { video.comments_on 5.days.ago}
+          let(:comments) { video.comments_on ENV['YT_TEST_PARTNER_VIDEO_DATE']}
           it { expect(comments).to be_a Float }
         end
 
@@ -189,7 +181,7 @@ describe Yt::Video, :partner do
 
       describe 'likes can be retrieved for a specific day' do
         context 'in which the video was partnered' do
-          let(:likes) { video.likes_on 5.days.ago}
+          let(:likes) { video.likes_on ENV['YT_TEST_PARTNER_VIDEO_DATE']}
           it { expect(likes).to be_a Float }
         end
 
@@ -236,7 +228,7 @@ describe Yt::Video, :partner do
 
       describe 'dislikes can be retrieved for a specific day' do
         context 'in which the video was partnered' do
-          let(:dislikes) { video.dislikes_on 5.days.ago}
+          let(:dislikes) { video.dislikes_on ENV['YT_TEST_PARTNER_VIDEO_DATE']}
           it { expect(dislikes).to be_a Float }
         end
 
@@ -283,7 +275,7 @@ describe Yt::Video, :partner do
 
       describe 'shares can be retrieved for a specific day' do
         context 'in which the video was partnered' do
-          let(:shares) { video.shares_on 5.days.ago}
+          let(:shares) { video.shares_on ENV['YT_TEST_PARTNER_VIDEO_DATE']}
           it { expect(shares).to be_a Float }
         end
 
@@ -330,7 +322,7 @@ describe Yt::Video, :partner do
 
       describe 'gained subscribers can be retrieved for a specific day' do
         context 'in which the video was partnered' do
-          let(:subscribers_gained) { video.subscribers_gained_on 5.days.ago}
+          let(:subscribers_gained) { video.subscribers_gained_on ENV['YT_TEST_PARTNER_VIDEO_DATE']}
           it { expect(subscribers_gained).to be_a Float }
         end
 
@@ -377,7 +369,7 @@ describe Yt::Video, :partner do
 
       describe 'lost subscribers can be retrieved for a specific day' do
         context 'in which the video was partnered' do
-          let(:subscribers_lost) { video.subscribers_lost_on 5.days.ago}
+          let(:subscribers_lost) { video.subscribers_lost_on ENV['YT_TEST_PARTNER_VIDEO_DATE']}
           it { expect(subscribers_lost).to be_a Float }
         end
 
@@ -424,7 +416,7 @@ describe Yt::Video, :partner do
 
       describe 'added favorites can be retrieved for a specific day' do
         context 'in which the video was partnered' do
-          let(:favorites_added) { video.favorites_added_on 5.days.ago}
+          let(:favorites_added) { video.favorites_added_on ENV['YT_TEST_PARTNER_VIDEO_DATE']}
           it { expect(favorites_added).to be_a Float }
         end
 
@@ -471,7 +463,7 @@ describe Yt::Video, :partner do
 
       describe 'removed favorites can be retrieved for a specific day' do
         context 'in which the video was partnered' do
-          let(:favorites_removed) { video.favorites_removed_on 5.days.ago}
+          let(:favorites_removed) { video.favorites_removed_on ENV['YT_TEST_PARTNER_VIDEO_DATE']}
           it { expect(favorites_removed).to be_a Float }
         end
 
@@ -761,6 +753,58 @@ describe Yt::Video, :partner do
         end
       end
 
+      describe 'viewer percentage can be retrieved for a range of days' do
+        let(:viewer_percentage) { video.viewer_percentage since: 1.year.ago, until: 10.days.ago}
+        it { expect(viewer_percentage).to be_a Hash }
+      end
+
+      describe 'viewer_percentage can be grouped by gender and age group' do
+        let(:range) { {since: 1.year.ago.to_date, until: 1.week.ago.to_date} }
+        let(:keys) { range.values }
+
+        specify 'without a :by option (default)' do
+          viewer_percentage = video.viewer_percentage range
+          expect(viewer_percentage.keys).to match_array [:female, :male]
+          expect(viewer_percentage[:female].keys - %w(65- 35-44 45-54 13-17 25-34 55-64 18-24)).to be_empty
+          expect(viewer_percentage[:female].values).to all(be_instance_of Float)
+          expect(viewer_percentage[:male].keys - %w(65- 35-44 45-54 13-17 25-34 55-64 18-24)).to be_empty
+          expect(viewer_percentage[:male].values).to all(be_instance_of Float)
+        end
+
+        specify 'with the :by option set to :gender_age_group' do
+          viewer_percentage = video.viewer_percentage range.merge by: :gender_age_group
+          expect(viewer_percentage.keys).to match_array [:female, :male]
+          expect(viewer_percentage[:female].keys - %w(65- 35-44 45-54 13-17 25-34 55-64 18-24)).to be_empty
+          expect(viewer_percentage[:female].values).to all(be_instance_of Float)
+          expect(viewer_percentage[:male].keys - %w(65- 35-44 45-54 13-17 25-34 55-64 18-24)).to be_empty
+          expect(viewer_percentage[:male].values).to all(be_instance_of Float)
+        end
+      end
+
+      describe 'viewer_percentage can be grouped by gender' do
+        let(:range) { {since: 1.year.ago.to_date, until: 1.week.ago.to_date} }
+        let(:keys) { range.values }
+
+        specify 'with the :by option set to :gender' do
+          viewer_percentage = video.viewer_percentage range.merge by: :gender
+          expect(viewer_percentage.keys).to match_array [:female, :male]
+          expect(viewer_percentage[:female]).to be_a Float
+          expect(viewer_percentage[:male]).to be_a Float
+        end
+      end
+
+      describe 'viewer_percentage can be grouped by age group' do
+        let(:range) { {since: 1.year.ago.to_date, until: 1.week.ago.to_date} }
+        let(:keys) { range.values }
+
+        specify 'with the :by option set to :age_group' do
+          viewer_percentage = video.viewer_percentage range.merge by: :age_group
+          expect(viewer_percentage.keys - %w(65- 35-44 45-54 13-17 25-34 55-64 18-24)).to be_empty
+          expect(viewer_percentage.values).to all(be_instance_of Float)
+        end
+      end
+
+      # @deprecated, use video.viewer_percentage instead
       specify 'viewer percentages by gender and age range can be retrieved' do
         expect(video.viewer_percentages[:female]['18-24']).to be_a Float
         expect(video.viewer_percentages[:female]['25-34']).to be_a Float
@@ -774,9 +818,6 @@ describe Yt::Video, :partner do
         expect(video.viewer_percentages[:male]['45-54']).to be_a Float
         expect(video.viewer_percentages[:male]['55-64']).to be_a Float
         expect(video.viewer_percentages[:male]['65-']).to be_a Float
-
-        expect(video.viewer_percentage(gender: :male)).to be_a Float
-        expect(video.viewer_percentage(gender: :female)).to be_a Float
       end
     end
 

data/spec/requests/as_server_app/playlist_item_spec.rb

@@ -5,7 +5,7 @@ describe Yt::PlaylistItem, :server_app do
   subject(:item) { Yt::PlaylistItem.new id: id }
 
   context 'given an existing playlist item' do
-    let(:id) { 'PLjW_GNR5Ir0GWEP_oveGBNjTvKkYyZfsna1TZDCBP-Z8' }
+    let(:id) { 'PLjW_GNR5Ir0GMlbJzA-aW0UV8TchJFb8p3uzrLNcZKPY' }
 
     it 'returns valid snippet data' do
       expect(item.snippet).to be_a Yt::Snippet

data/spec/requests/as_server_app/playlist_spec.rb

@@ -5,7 +5,7 @@ describe Yt::Playlist, :server_app do
   subject(:playlist) { Yt::Playlist.new id: id }
 
   context 'given an existing playlist' do
-    let(:id) { 'PLSWYkYzOrPMRCK6j0UgryI8E0NHhoVdRc' }
+    let(:id) { 'PLSWYkYzOrPMT9pJG5St5G0WDalhRzGkU4' }
 
     it 'returns valid snippet data' do
       expect(playlist.snippet).to be_a Yt::Snippet

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: yt
 version: !ruby/object:Gem::Version
-  version: 0.14.7
+  version: 0.15.0
 platform: ruby
 authors:
 - Claudio Baccigalupo
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-04-17 00:00:00.000000000 Z
+date: 2015-04-19 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport