OAuth support coming soon! Check out Sirlantis' branch in the mean time.

Vimeo API Gem

This gem implements a full-featured Ruby interface for the Vimeo API v2.

For a more in depth look at the API check out Vimeo's Simple API Documentation or Vimeo's Advanced API Documentation. I would also recommend checking out the API Forums if things aren’t working as they should — in my experience the Vimeo API has a number of bugs and oddities.

Install

First, install Gemcutter, then you can:

  sudo gem install vimeo

Don’t forget to add the following to your environment.rb file:

  config.gem "vimeo", :lib => "vimeo"

Use

There are two modules:

  Vimeo::Simple
  Vimeo::Advanced

Simple API

The wrapper for the Simple API consists of several classes. To use the Simple API, just call one of the class methods. For example:

  user_info = Vimeo::Simple::User.info("matthooks")
  # =>
  # {
  #   "id":"888046",
  #   "display_name":"Matt Hooks",
  #   "created_on":"2008-10-30 14:17:32",
  #   "is_staff":"0",
  #   "is_plus":"0",
  #   "location":"Chicago, IL",
  #   "url":"http:\/\/blackholeinthemidwest.com\/",
  #   "bio":"",
  #   "profile_url":"http:\/\/vimeo.com\/matthooks",
  #   "videos_url":"http:\/\/vimeo.com\/matthooks\/videos",
  #   "total_videos_uploaded":2,
  #   "total_videos_appears_in":0,
  #   "total_videos_liked":2,
  #   "total_contacts":3,
  #   "total_albums":0,
  #   "total_channels":1,
  #   "portrait_small":"http:\/\/images.vimeo.com\/11\/42\/16\/114216178\/114216178_30.jpg",
  #   "portrait_medium":"http:\/\/images.vimeo.com\/11\/42\/16\/114216178\/114216178_75.jpg",
  #   "portrait_large":"http:\/\/images.vimeo.com\/11\/42\/16\/114216178\/114216178_100.jpg",
  #   "portrait_huge":"http:\/\/images.vimeo.com\/11\/42\/16\/114216178\/114216178_300.jpg"
  # }

  # That's right! The data returned will be parsed and ready to use.

  user_info["location"]
  # => "Chicago, IL"

Vimeo::Simple::Activity

  Vimeo::Simple::Activity.user_did("username")
  Vimeo::Simple::Activity.happened_to_user("username")
  Vimeo::Simple::Activity.contacts_did("username")
  Vimeo::Simple::Activity.happened_to_contacts("username")
  Vimeo::Simple::Activity.everyone_did("username")

Vimeo::Simple::Album

  Vimeo::Simple::Album.videos("album_id")
  Vimeo::Simple::Album.info("album_id")

Vimeo::Simple::Channel

  Vimeo::Simple::Channel.videos("channelname")
  Vimeo::Simple::Channel.info("channelname")

Vimeo::Simple::Group

  Vimeo::Simple::Group.videos("groupname")
  Vimeo::Simple::Group.users("groupname")
  Vimeo::Simple::Group.info("groupname")

Vimeo::Simple::User

  Vimeo::Simple::User.info("username")
  Vimeo::Simple::User.videos("username")
  Vimeo::Simple::User.likes("username")
  Vimeo::Simple::User.appears_in("username")
  Vimeo::Simple::User.all_videos("username")
  Vimeo::Simple::User.subscriptions("username")
  Vimeo::Simple::User.albums("username")
  Vimeo::Simple::User.channels("username")
  Vimeo::Simple::User.groups("username")
  Vimeo::Simple::User.contacts_videos("username")
  Vimeo::Simple::User.contacts_like("username")

Vimeo::Simple::Video

  Vimeo::Simple::Video.info("video_id")

Advanced API

The classes in Vimeo::Advanced must be instantiated with an your application’s api key and secret. For example:

  vimeo_video = Vimeo::Advanced::Video.new("api_key", "secret", :token => "oauth_token", :secret => "oauth_secret")

Then you can make method calls on the instance. For example:

  vimeo_video.get_all("matthooks", :page => "2", :per_page => "50")

Some methods have optional variables. You should pass as a hash at the end of a call.

All methods require authentication. Check out Vimeo’s guides for Web Based authentication and Desktop Based authentication.

The wrapper for the Advanced API consists of the following classes and methods:

Authorization (as a website)

You have to acquire an authorized for each user. At first you will have to send the user to Vimeo to authorize your application.

  vimeo = Vimeo::Advanced::Auth.new(VIMEO_API_KEY, VIMEO_SECRET)
  token = vimeo.request_token

  # token.callback_confirmed? should be true

  # store these values in a database/session
  @the_token = token.token
  @the_secret = token.secret

  redirect_to token.authorize_url

Time passes, user will be redirected back to your site with a GET oauth_verifier parameter. You now need to authorize the token:

  vimeo = Vimeo::Advanced::Auth.new(VIMEO_API_KEY, VIMEO_SECRET)
  authorized_token = vimeo.authorize(@the_token, @the_secret, :oauth_verifier => @oauth_verifier)

  # store these values in a database/session
  @vimeo_oauth_token = authorized_token.token
  @vimeo_oauth_secret = authorized_token.secret

You now have acquired the required OAuth credentials. Now you need to re-establish the OAuth connection and start using the API.

  video = Vimeo::Advanced::Video.new(VIMEO_API_KEY, VIMEO_SECRET,
    :token => @vimeo_oauth_token,
    :secret => @vimeo_oauth_secret)

  # get the users profile-data (and vimeo-user-id)
  user_data = video.check_access_token
  user_id = user_data["oauth"]["user"]["id"]

  # and start the fun!
  videos = video.get_likes(user_id)

Vimeo::Advanced::Album

  album = Vimeo::Advanced::Album.new("authorization_data")

  album.add_video("auth_token", "album_id", "video_id")
  album.create("auth_token", "title", "video_id", { :description => "description", "videos" => "123,124,125" })
  album.delete("auth_token", "album_id")
  album.get_all("user_id", { :page => "1", :per_page => "25" })
  album.get_videos("auth_token", "user_id", { :page => "1", :per_page => "25", :full_response => "0", :password => nil })
  album.get_videos("auth_token", "album_id", "video_id")
  album.set_description("auth_token", "album_id", "description")
  album.get_password("auth_token", "album_id", "password")
  album.get_title("auth_token", "album_id", "title")

Vimeo::Advanced::Base

  base = Vimeo::Advanced::Base.new("authorization_data")

  base.check_access_token

Vimeo::Advanced::Channel

  channel = Vimeo::Advanced::Channel.new("authorization_data")

  channel.add_video("auth_token", "channel_id", "video_id")
  channel.get_all({ :page => "1", :per_page => "25", :sort => "newest"})
  channel.get_info(channel_id, { :page => "1", :per_page => "25" })
  channel.get_moderators(channel_id, { :page => "1", :per_page => "25" })
  channel.get_subscribers(channel_id, { :page => "1", :per_page => "25" })
  channel.get_videos(channel_id, { :page => "1", :per_page => "25", :full_response => "0" })
  channel.remove_video("auth_token", "channel_id", "video_id")
  channel.subscribe("auth_token", "channel_id")
  channel.unsubscribe("auth_token", "channel_id")

Vimeo::Advanced::Contact

  contact = Vimeo::Advanced::Contact.new("authorization_data")

  contact.get_all(user_id, { :page => "1", :per_page => "25", :sort => "newest" })
  contact.get_mutual(user_id, { :page => "1", :per_page => "25", :sort => "newest" })
  contact.get_online({ :page => "1", :per_page => "25", :sort => "newest" })
  contact.get_who_added(user_id, { :page => "1", :per_page => "25", :sort => "newest" })

Vimeo::Advanced::Group

  group = Vimeo::Advanced::Group.new("authorization_data")

  group.add_video("auth_token", "group_id", "video_id")
  group.get_all({ :page => "1", :per_page => "25", :sort => "newest" })
  group.get_files("group_id", { :page => "1", :per_page => "25" })
  group.get_info("group_id", { :page => "1", :per_page => "25" })
  group.get_members("group_id", { :page => "1", :per_page => "25", :sort => "newest" })
  group.get_moderators("group_id", { :page => "1", :per_page => "25" })
  group.get_video_comments("group_id", "video_id", { :page => "1", :per_page => "25" })
  group.get_videos("group_id", { :page => "1", :per_page => "25", :full_response => "0", :sort => "newest" })
  group.join("auth_token", "group_id")
  group.leave("auth_token", "group_id")

Vimeo::Advanced::GroupEvents

  group_events = Vimeo::Advanced::GroupEvents.new("authorization_data")

  group_events.get_month("group_id", { :page => "1", :per_page => "25", :month => nil, :year => nil })
  group_events.get_past("group_id", { :page => "1", :per_page => "25" })
  group_events.get_year("group_id", { :page => "1", :per_page => "25" })

Vimeo::Advanced::GroupForums

  group_forums = Vimeo::Advanced::GroupForums.new("authorization_data")

  group_forums.get_topic_comments("group_id", "topic_id", { :page => "1", :per_page => "25" })
  group_forums.get_topics("group_id", { :page => "1", :per_page => "25" })

Vimeo::Advanced::Person

  person = Vimeo::Advanced::Person.new("authorization_data")

  person.add_contact("auth_token", "user_id")
  person.add_subscription("auth_token", "user_id", "types") # Types is a comma-delimited string. Valid: "likes", "appears", "uploads"
  person.find_by_email("user_id")
  person.get_hd_embeds("auth_token")
  person.get_info("user_id")
  person.get_portrait_urls("user_id")
  person.remove_contact("auth_token", "user_id")
  person.remove_subscription("auth_token", "user_id", "types") # Types is a comma-delimited string. Valid: "likes", "appears", "uploads"

Vimeo::Advanced::Test

  test = Vimeo::Advanced::Test.new("authorization_data")

  test.echo
  test.null(auth_token)
  test.login(auth_token)

Vimeo::Advanced::Upload

  upload = Vimeo::Advanced::Upload.new("authorization_data")

  upload.confirm("auth_token", "ticket_id", "json_manifest")
  upload.get_quota("auth_token")
  upload.get_ticket("auth_token")
  upload.upload("auth_token", "path_to_file", "ticket_id", "end_point")
  upload.verify_manifest("auth_token", "ticket_id", "json_manifest")

Vimeo::Advanced::Video

  video = Vimeo::Advanced::Video.new("authorization_data")

  video.add_cast("auth_token", "video_id", "user_id", { :role => nil })
  video.add_photos("auth_token", "video_id", "photo_urls")
  video.add_tags("auth_token", "video_id", "tags")
  video.clear_tags("auth_token", "video_id")
  video.delete("auth_token", "video_id")
  video.get_all("user_id", { :page => "1", :per_page => "25", :full_response => "0", :sort => "newest" })
  video.get_appears_in("user_id", { :page => "1", :per_page => "25", :full_response => "0", :sort => "newest" })
  video.get_by_tag("tag", { :page => "1", :per_page => "25", :full_response => "0", :sort => "newest" })
  video.get_cast("video_id", { :page => "1", :per_page => "25" })
  video.get_contacts_liked("user_id", { :page => "1", :per_page => "25", :full_response => "0", :sort => "newest" })
  video.get_contacts_uploaded("user_id", { :page => "1", :per_page => "25", :full_response => "0", :sort => "newest" })
  video.get_info("video_id")
  video.get_likes("user_id", { :page => "1", :per_page => "25", :full_response => "0", :sort => "newest" })
  video.get_subscriptions("user_id", { :page => "1", :per_page => "25", :full_response => "0", :sort => "newest" })
  video.get_thumbnail_urls("video_id")
  video.get_uploaded("user_id", { :page => "1", :per_page => "25", :full_response => "0", :sort => "newest" })
  video.remove_cast("auth_token", "video_id", "user_id")
  video.remove_tag("auth_token", "video_id", "tag_id")
  video.search("query", { :page => "1", :per_page => "25", :full_response => "0", :sort => "newest", :user_id => nil })
  video.set_description("auth_token", "video_id", "description")
  video.set_like("auth_token", "video_id", "like")
  video.set_privacy("auth_token", "video_id", "privacy", { :users => nil, :password => nil })
  video.set_title("auth_token", "video_id", "title")

  # comments
  video.add_comment("auth_token", "video_id", "comment_text", { :reply_to_comment_id => nil })
  video.delete_comment("auth_token", "video_id", "comment_id")
  video.edit_comment("auth_token", "video_id", "comment_id", "comment_text")
  video.get_comments_list("video_id", { :page => "1", :per_page => "25" })

Vimeo::Advanced::VideoEmbed

  video_embed = Vimeo::Advanced::VideoEmbed.new("authorization_data")

  video_embed.get_presets("auth_token", { :page => "1", :per_page => "25" })
  video_embed.set_preset("auth_token", "video_id", "preset_id")

Uploads

Uploads are a little bit tricky, so I figured I’d help you guys with a short tutorial.

  # Start by creating an instance of the Upload class.
  upload = Vimeo::Advanced::Upload.new("authorization_data")
  # I'm going to assume you've got that user's auth token stored somewhere and that they have upload access.
  auth_token = "..."

  # Let's check the user's quota.
  # You should let the user know if they don't have enough quota free and/or if their video can be uploaded in HD
  quota = upload.get_quota(auth_token)
  free_space = quota["user"]["upload_space"]["free"]
  hd = quota["user"]["hq_quota"]

  # Now let's get an upload ticket.
  ticket = upload.get_ticket(auth_token)
  ticket_id = get_ticket["ticket"]["id"]
  endpoint = get_ticket["ticket"]["endpoint"]

  # Cool! Let's post the video.
  # The file path should be absolute.
  file_path = "..."
  json_manifest = upload.upload(auth_token, file_path, ticket_id, endpoint)

  # After the upload completes...
  upload.confirm(auth_token, ticket_id, json_manifest)

There are a few steps along the way where things can go wrong.

Todo

• Better structure. There’s too many classes. Is there a way to simplify the Advanced API?
• Advanced classes should be able to take the authentication token as a parameter so you don’t have to pass it to the methods that require authentication.
• Error handling.
• Some methods are not implemented by Vimeo or don’t seem to work.
• More re-factoring.
• Make tests more robust and faster. If anyone has any ideas let me know.

Contributors

• matthooks
• sirlantis

Thanks to

• HTTParty: Easily one of the best tools I have used since I started using Ruby.
• Jeweler: Great tool for creating gems for Github.

Copyright © 2009 Matt Hooks. See LICENSE for details.