Brainzz
Brainzz explains why youtoobers' brainzz are turned to mush. ... by extracting data from the YouTube API.
Setup
$ bundle install
Run Specs
$ bundle exec rake
Regenerating VCR Cassettes
Check config/dotenv/test.env
for the required keys.
The values in this file are required environment variables
when consuming this gem.
Environment Variables
Brainzz requires the use of multiple environment variables:
- BRAINZZ_GOOGLE_API_KEY
- BRAINZZ_CLIENT_ID
- BRAINZZ_CLIENT_SECRET
- BRAINZZ_REFRESH_TOKEN
- BRAINZZ_CONTENT_OWNER:
- the Google account for the CMS that owns the YouTube channel data being sought
Place values in config/dotenv/integration.env
.
Attaining BRAINZZ_GOOGLE_API_KEY
Follow the instructions here to find the required values.
Attaining BRAINZZ_REFRESH_TOKEN
An OAUTH refresh token for the BRAINZZ_CONTENT_OWNER Google account uses BRAINZZ_CLIENT_SECRET and BRAINZZ_CLIENT_SECRET
BRAINZZ_CLIENT_ID
and BRAINZZ_CLIENT_SECRET
.
- Go to the Google OAuth Playground
- Log in with the Google account for BRAINZZ_CONTENT_OWNER
- Click on the gear (upper-right)
- Click check box to "Use your own OAuth credentials"
- Fill in BRAINZZ_CLIENT_ID and BRAINZZ_CLIENT_SECRET
- In Step 1 (Select & Authorize APIs) scroll down to YouTube Analytics API v1
- Click the last item "yt-analytics.readonly"
- Click blue 'Authorize APIs' button
- Exchange code for tokens
- Grab value for the Refresh Token and store
Interface
All public endpoints are exposed in Brainzz::Core.
Every response from the public API is wrapped in a Response
object
that will always have the same interface regardless of request.
The Response#data
attribute will be an object specific to the data requested.
playlist_items_for
On first invocation, only a playlist id is required:
playlist_id = 'my-playlist-id'
Brainzz.playlist_items_for playlist_id
This data is paginated, so if there are more than 50 results,
subsequent calls will need to pass in the response from the previous request.
In order to retrieve all playlist items,
the last_page?
attribute will need to be checked as well.
playlist_id = 'my-playlist-id'
response = nil
while response.nil? || !response.data.last_page?
response = Brainzz.playlist_items_for(playlist_id, response)
end
video_details_for
Accepts an array of video ids. The maximum length of the array is determined by YouTube. It is currently limited to 50 videos.
This endpoint returns a hash with video ids as keys and video objects as the values.
views_by_day_for
Parameters
- video id (String)
- start date (DateTime)
- end date (DateTime)
Result
An array of Brainzz::ViewCount
objects ordered by date in ascending order.
#source
will be an integer (or nil) value
corresponding to the following YouTube referrals:
ADVERTISING = 1
ANNOTATION = 2
EXT_URL = 3
NO_LINK_EMBEDDED = 4
NO_LINK_OTHER = 5
PLAYLIST = 6
PROMOTED = 7
RELATED_VIDEO = 8
SUBSCRIBER = 9
YT_CHANNEL = 10
YT_OTHER_PAGE = 11
YT_SEARCH = 12
The constants are defined in Brainzz::ViewCountEnum
.
view_totals_for
Parameters
Same as views_by_day_for.
Result
Same as views_by_day_for except date values are nil.
Views for date range are aggregated per source type.
likes_by_day_for
Parameters
- video id (String)
- start date (DateTime)
- end date (DateTime)
Result
An array of Brainzz::LikeCount
objects ordered by date in ascending order.
like_totals_for
Parameters
Same as likes_by_day_for.
Result
Same as likes_by_day_for except date values are nil.
Likes for date range are aggregated.
shares_by_day_for
Parameters
- video id (String)
- start date (DateTime)
- end date (DateTime)
Result
An array of Brainzz::ShareCount
objects ordered by date in ascending order.
share_totals_for
Parameters
Same as shares_by_day_for.
Result
Same as shares_by_day_for except date values are nil.
Shares for date range are aggregated.
Factories
Brainzz includes FactoryGirl factories for your convenience. Include them after requiring FactoryGirl:
require 'brainzz/factories'
Deployment
This project makes use of branches to manage deployment.
Pushing a new commit to the production
branch
will also build and push this gem to RubyGems.