googol

Googol

Googol lets you interact with many resources provided by Google API V3.

channel = Googol::YoutubeResource.new url: 'youtube.com/fullscreen'
channel.id #=> 'UCxO1tY8h1AhOz0T4ENwmpow'
channel.title #=> "Fullscreen"
channel.description #=> "The first media company for the connected generation."

video = Googol::YoutubeResource.new url: 'youtu.be/Kd5M17e7Wek'
video.id #=> 'Kd5M17e7Wek'
video.title #=> "R.E.M. - Tongue (Video)"
video.description #=> "© 2006 WMG\nTongue (Video)"

account = Googol::GoogleAccount.new auth_params
account.email #=> '[e-mail]'

account = Googol::YoutubeAccount.new auth_params

# like the video 'Tongue'  by R.E.M.
account.like! video_id: 'Kd5M17e7Wek'

# subscribe to Fullscreen’s channel
account.subscribe_to! channel_id: 'UCxO1tY8h1AhOz0T4ENwmpow'

# unsubscribe from Fullscreen’s channel
account.unsubscribe_from! channel_id: 'UCxO1tY8h1AhOz0T4ENwmpow'

# create a playlist called "Fullscreen"
account.create_playlist! title: "Fullscreen"

# find the first playlist with "Fullscreen" in the title
account.find_playlist_by title: /Fullscreen/i

# delete all playlists with "Fullscreen" in the description
account.delete_playlists! description: /Fullscreen/i

# add the video 'Tongue' by R.E.M. to your 'Fullscreen' playlist
playlist_id = account.find_or_create_playlist_by title: 'Fullscreen'
account.add_item_to! playlist_id, video_id: 'Kd5M17e7Wek'

# add a list of 3 videos by R.E.M. to your 'Fullscreen' playlist
playlist_id = account.find_or_create_playlist_by title: 'Fullscreen'
account.add_item_to! playlist_id, ['Kd5M17e7Wek', '3D1zWC1hs0', 'G2BCrByfZ74']

# remove all the items from your 'Fullscreen' playlist
playlist_id = account.find_or_create_playlist_by title: 'Fullscreen'
account.remove_all_items_from! playlist_id

The full documentation is available at rubydoc.info.

Available classes

Googol exposes three different resources provided by Google API V3: Google Accounts, Youtube Accounts and Youtube Resources.

Google accounts

Use Googol::GoogleAccount to send and retrieve data to Google, impersonating an existing Google account.

Available instance methods are id, email, verified_email, name, given_name, family_name, link, picture, gender, and locale.

These methods require user authentication (see below).

Youtube accounts

Use Googol::YoutubeAccount to send and retrieve data to Youtube, impersonating an existing Youtube account.

Available instance methods are id, title, description, thumbnail_url, like!, subscribe_to!, find_or_create_playlist_by, and add_to!.

These methods require user authentication (see below).

Youtube resources

Use Googol::YoutubeResource to retrieve read-only information about public Youtube channels and videos.

Available instance methods are id, title, description, and thumbnail_url.

These methods require do not require user authentication.

Authentication

In order to use Googol you must register your app in the Google Developers Console:

1. Create a new app and enable access to Google+ API and YouTube Data API V3
2. Generate a new OAuth client ID (web application) and write down the client ID and client secret
3. Generate a new Public API access key (for server application) and write down the server key

Run the following command to make these tokens available to Googol:

require 'googol'
Googol::ClientTokens.client_id = '…'
Googol::ClientTokens.client_secret = '…'
Googol::ServerTokens.server_key = '…'

replacing the ellipses with the values from the Google Developers Console.

For actions that impersonate a Google or Youtube account, you also need to obtain authorization from the owner of the account you wish to impersonate:

1. In your web site, add a link to the Google's OAuth login page. The URL is:

   Googol::GoogleAccount.oauth_url(redirect_url) # to impersonate a Google Account
   Googol::YoutubeAccount.oauth_url(redirect_url) # to impersonate a Youtube Account
   

2. Upon authorization, the user is redirected to the URL passed as an argument, with an extra 'code' query parameter which can be used to impersonate the account:

   account = Googol::GoogleAccount.new(code: code, redirect_uri: url) # to impersonate a Google Account
   account = Googol::YoutubeAccount.new(code: code, redirect_uri: url) # to impersonate a Youtube Account
   

3. To prevent the user from having to authorize the app every time, store the account’s refresh_token in your database:

   refresh_token = account.credentials[:refresh_token] # Store to your DB
   

4. To impersonate an account that has already authorized your app, just use the refresh_token:

   account = Googol::GoogleAccount.new(refresh_token: refresh_token) # to impersonate a Google Account
   account = Googol::YoutubeAccount.new(refresh_token: refresh_token) # to impersonate a Youtube Account
   

Remember to add every redirect URL that you plan to use in the Google Developers Console, and to set a Product name in Consent screen (under API & Auth).

How to install

To install on your system, run

gem install googol

To use inside a bundled Ruby project, add this line to the Gemfile:

gem 'googol', '~> 0.3.0'

Since the gem follows Semantic Versioning, indicating the full version in your Gemfile (~> major.minor.patch) guarantees that your project won’t occur in any error when you bundle update and a new version of Googol is released.

Remember that you need to set up a Google app and include its credentials in order for the gem to work (see above). In a Rails project, for instance, you can do so by writing the following code in config/initializer/googol.rb:

Googol::ClientTokens.client_id = '…'
Googol::ClientTokens.client_secret = '…'
Googol::ServerTokens.server_key = '…'

replacing the ellipses with your app values from the Google Developers Console.

Why you should use Googol…

… and not youtube_it? Because youtube_it does not support Google API V3 and the previous version has already been deprecated by Google and will soon be dropped.

… and not Google Api Client? Because Google Api Client is poorly coded, poorly documented and adds many dependencies, bloating the size of your project.

… and not your own code? Because Googol is fully tested, well documented, has few dependencies and helps you forget about the burden of dealing with Google API!

How to test

To run the tests, you must give the test app permissions to access your Google and Youtube accounts. They are free, so feel free to create a fake one.

1. Run the following commands in a ruby session:

   require 'googol'
   Googol::GoogleAccount.oauth_url  # => "https://accounts.google.com/o..."
   

2. Copy the last URL in a browser, and accept the terms. You will be redirected to a URL like http://example.com/?code=ABCDE

3. Copy the code parameter (ABCDE in the example above) and run:

   account = Googol::GoogleAccount.new code: 'ABCDE'
   account.credentials[:refresh_token]
   

4. Copy the token returned by the last command (something like 1AUJZh2x1...) and store it in an environment variable before running the test suite:

   export GOOGOL_TEST_GOOGLE_REFRESH_TOKEN="1AUJZh2x1..."
   

5. Repeat all the steps above replacing GoogleAccount with YoutubeAccount to authorize access to your Youtube account:

   export GOOGOL_TEST_YOUTUBE_REFRESH_TOKEN="2B6T5x23..."
   

6. Finally run the tests running rspec or rake. If you prefer not to set environment variables, pass the refresh token in the same line:

   GOOGOL_TEST_GOOGLE_REFRESH_TOKEN="1AUJZh2x1..." GOOGOL_TEST_YOUTUBE_REFRESH_TOKEN="2B6T5x23..." rspec
   

How to contribute

Before you submit a pull request, make sure all the tests are passing and the code is fully test-covered.

To release an updated version of the gem to Rubygems, run:

rake release

Remember to bump the version before running the command, and to document your changes in HISTORY.md and README.md if required.

The googol gem follows Semantic Versioning. Any new release that is fully backward-compatible should bump the patch version (0.0.x). Any new version that breaks compatibility should bump the minor version (0.x.0)

Don’t hesitate to send code comments, issues or pull requests through GitHub! All feedback is appreciated. A googol of thanks! :)