We recently launched our brand-new API! Start using it now to access tons of added endpoints and other fresh updates.

Note: we will no longer be adding features to the old Simple API.

The Simple API is for public data only.
If your videos are private, you will need to use the Advanced API. If your video is set to hide from vimeo.com, but is embeddable, you may also be able to use oEmbed.

Response Limits

Simple API responses include up to 20 items per page.

By adding the ?page parameter to the URL, you can retrieve up to 3 pages of data. If you need more than the maximum of 60 items, you must use the Advanced API.


Response Formats

All of the different response formats return the exact same data, but you can choose the format that is easiest to work with in the programming language that you’re using.

JSON

The JSON format can be used directly in JavaScript and many other languages. You can use this format in PHP: just call json_decode() to convert the data into an array.

JSONP

JSONP is the same as the JSON response, but it’s wrapped in a callback function. To get a JSONP response, just append ?callback=myFunction to the end of the JSON request URL.

PHP

When using this format, Vimeo will return a serialized PHP array. All you have to do is pass the data through unserialize() and you’ll have an array of the data.

XML

The XML version of the data is a very simple XML format that should be easy for you to parse. You can use SimpleXML in PHP to easily parse it.


Making a User Request

To access the data for a specific user, you simply request a URL from vimeo.com and let us know what you want. The URLs are simple, they can be built with the following format:

Making the URL

http://vimeo.com/api/v2/username/request.output
username Either the shortcut URL or ID of the user, an email address will NOT work.
request The data you want. The different request types are listed below.
output Specify the output type. We currently offer JSON, PHP, and XML formats.

Requests you can make

info User info for the specified user
videos Videos created by user
likes Videos the user likes
appears_in Videos that the user appears in
all_videos Videos that the user appears in and created
subscriptions Videos the user is subscribed to
albums Albums the user has created
channels Channels the user has created and subscribed to
groups Groups the user has created and joined

Example Request

To get a list of the videos that you appear in, in XML format, you’d make this request:

http://vimeo.com/api/v2/brad/appears_in.xml

Example Response

Here’s an example of the XML response from an info call:

<?xml version="1.0" encoding="UTF-8"?>
        <users>
          <user>
              <id>101193</id>
              <display_name>Brad Dougherty</display_name>
              <created_on>2006-02-13 11:27:25</created_on>
              <is_staff>1</is_staff>
              <is_plus>0</is_plus>
              <location>Yardley, PA</location>
              <url>http://braddougherty.us</url>
              <bio>I am a Vimeo apprentice this summer! ...</bio>
              <profile_url>http://www.vimeo.com/brad</profile_url>
              <videos_url>http://www.vimeo.com/brad/videos</videos_url>
              <total_videos_uploaded>4</total_videos_uploaded>
              <total_videos_appears_in>2</total_videos_appears_in>
              <total_videos_liked>53</total_videos_liked>
              <total_contacts>45</total_contacts>
              <total_albums>0</total_albums>
              <total_channels>0</total_channels>
              <portrait_small>http://assets.vimeo.com/...jpg</portrait_small>
              <portrait_medium>http://storage10.vimeo.com/...jpg</portrait_medium>
              <portrait_large>http://00.media.vimeo.com/...jpg</portrait_large>
          </user>
        </users>

Making a Video Request

To get data about a specific video, use the following url:

Making the URL

http://vimeo.com/api/v2/video/video_id.output
video_id The ID of the video you want information for.
output Specify the output type. We currently offer JSON, PHP, and XML formats.

The data returned from this method is the same as what is returned in any video list, except there is only one.


Making an Activity Request

To access the activity data for a specific user, a user’s contacts, or everyone, you simply request the following URL:

Making the URL

http://vimeo.com/api/v2/activity/username/request.output
username Either the shortcut URL or ID of the user, an email address will NOT work.
request The data you want. The different request types are listed below.
output Specify the output type. We currently offer JSON, PHP, and XML formats.

Requests you can make

user_did Activity by the user
happened_to_user Activity on the user
contacts_did Activity by the user’s contacts
everyone_did Activity by everyone

Example Request

To get a list of the recent things you did, in serialized PHP format, you’d make this request:

http://vimeo.com/api/v2/activity/brad/user_did.php

Example Response

Here’s an example of PHP array response from a user_did call (after calling the unserialize() function):

Array
        (
          [0] => Array
            (
              [type] => "add_tags"
              [date] => 2008-06-13 12:21:03
              [user_id] => 209837
              [user_name] => "Soxiam"
              [user_url] => "http://www.vimeo.com/soxiam"
              [user_portrait_small] => "http://20.media.vimeo.com/...jpg"
              [user_portrait_medium] => "http://90.media.vimeo.com/...jpg"
              [user_portrait_large] => "http://00.media.vimeo.com/...jpg"
              [subject_id] => 209837
              [subject_name] => "lostinspace"
              [subject_url] => "http://www.vimeo.com/lostinspace"
              [subject_portrait_small] => "http://storage13.vimeo.com/...jpg"
              [subject_portrait_medium] => "http://00.media.vimeo.com/...jpg"
              [subject_portrait_large] => "http://00.media.vimeo.com/...jpg"
              [video_id] => 429424
              [video_title] => "3space"
              [video_description] => "early lost in space film ..."
              [video_url] => "http://www.vimeo.com/429424"
              [video_thumbnail_small] => "http://40.media.vimeo.com/...jpg"
              [video_thumbnail_medium] => "http://60.media.vimeo.com/...jpg"
              [video_thumbnail_large] => "http://80.media.vimeo.com/...jpg"
              [video_stats_number_of_likes] => 22
              [video_stats_number_of_plays] => 427
              [video_stats_number_of_comments] => 6
              [video_tags] =>
              [action_tags] => "car",
            )
        )

Making a Group Request

Making the URL

http://vimeo.com/api/v2/group/groupname/request.output
groupname Either the shortcut URL or ID of the group.
request The data you want. The different request types are listed below.
output Specify the output type. We currently offer JSON, PHP, and XML formats.

Requests you can make

videos Videos added to that group
users Users who have joined the group
info Group info for the specified group

Example Request

To get a list of the videos in the ‘awesome’ group, in JSON format, you’d make this request:

http://vimeo.com/api/v2/group/awesome/videos.json

Example Response

Here’s an example of the JSON response from a videos call: (URLs have been shortened for formatting, you’ll get the full URL in your results. You’ll also probably get more than one video.)

[{
            "title": "Good Idea #4: Make A Wish",
            "url": "http:\/\/www.vimeo.com\/753571",
            "id": "753571",
            "description": "Tyler, Scott, and Jared meet a mysterious...\n",
            "upload_date": "2008-03-04 15:57:58",
            "thumbnail_small": "http:\/\/20.media.vimeo.com\/...jpg",
            "thumbnail_medium": "http:\/\/60.media.vimeo.com\/...jpg",
            "thumbnail_large": "http:\/\/30.media.vimeo.com\/...jpg",
            "user_name": "Kinetiq HD",
            "user_url": "http:\/\/www.vimeo.com\/user346742",
            "user_portrait_small": "http:\/\/40.media.vimeo.com\/...jpg",
            "user_portrait_medium": "http:\/\/00.media.vimeo.com\/...jpg",
            "user_portrait_large": "http:\/\/10.media.vimeo.com\/...jpg",
            "stats_number_of_likes": "38",
            "stats_number_of_plays": "19312",
            "stats_number_of_comments": 25,
            "tags": ""
        }]

Making a Channel Request

Making the URL

http://vimeo.com/api/v2/channel/channelname/request.output
channelname Either the shortcut URL of the channel.
request The data you want. The different request types are listed below.
output Specify the output type. We currently offer JSON, PHP, and XML formats.

Requests you can make

videos Videos in the channel
info Channel info for the specified channel

Example Request

To get the information for the “Delicious Sandwich” channel, in XML format, you’d make this request:

http://vimeo.com/api/v2/channel/delicioussandwich/info.xml

Example Response

Here’s an example of the XML response from an info call: (URLs have been shortened for formatting, you’ll get the full URL in your results. You’ll also probably get more than one video.)

<?xml version="1.0" encoding="UTF-8"?>
        <channels>
          <channel>
            <id>19</id>
            <name>Delicious Sandwich</name>
            <description>A Sandwich Blog</description>
            <logo></logo>
            <url>http://www.vimeo.com/delicioussandwich</url>
            <rss>http://www.vimeo.com/channel19/videos/rss</rss>
            <created_on>2007-08-10 09:31:58</created_on>
            <creator_id>76850</creator_id>
            <creator_display_name>Amir</creator_display_name>
            <creator_url>http://www.vimeo.com/Amir</creator_url>
            <total_videos>2</total_videos>
            <total_subscribers>69</total_subscribers>
          </channel>
        </channels>

Making an Album Request

Making the URL

http://vimeo.com/api/v2/album/album_id/request.output
album_id The ID of the album.
request The data you want. The different request types are listed below.
output Specify the output type. We currently offer JSON, PHP, and XML formats.

Requests you can make

videos Videos in that album
info Album info for the specified album

Example Request

To get a list of the videos in album 21, in XML format, you’d make this request:

http://vimeo.com/api/v2/album/21/videos.xml

Example Response

Here’s an example of the XML response from a videos call: (URLs have been shortened for formatting, you’ll get the full URL in your results. You’ll also probably get more than one video.)

<?xml version="1.0" encoding="UTF-8"?>
        <videos>
          <video>
            <title>the oregon trail: prequel</title>
            <url>http://www.vimeo.com/314947</url>
            <id>314947</id>
            <description>this movie is rated d ...</description>
            <upload_date>2007-09-21 20:36:30</upload_date>
            <thumbnail_small>http://80.media.vimeo.com/...jpg</thumbnail_small>
            <thumbnail_medium>http://10.media.vimeo.com/...jpg</thumbnail_medium>
            <thumbnail_large>http://00.media.vimeo.com/...jpg</thumbnail_large>
            <user_name>Soxiam</user_name>
            <user_url>http://www.vimeo.com/soxiam</user_url>
            <user_portrait_small>http://assets.vimeo.com/...jpg</user_thumbnail_small>
            <user_portrait_medium>http://00.media.vimeo.com/...jog</user_thumbnail_medium>
            <user_portrait_large>http://70.media.vimeo.com/...jpg</user_thumbnail_large>
            <stats_number_of_likes>72</stats_number_of_likes>
            <stats_number_of_plays>3269</stats_number_of_plays>
            <stats_number_of_comments>43</stats_number_of_comments>
            <tags></tags>
          </video>
        </videos>

That is pretty much it! Simple, eh?


Response Data

There are a few different types of responses.

Video Data

title Video title
url URL to the Video Page
id Video ID
description The description of the video
thumbnail_small URL to a small version of the thumbnail
thumbnail_medium URL to a medium version of the thumbnail
thumbnail_large URL to a large version of the thumbnail
user_name The user name of the video’s uploader
user_url The URL to the user profile
upload_date The date/time the video was uploaded on
user_portrait_small Small user portrait (30px)
user_portrait_medium Medium user portrait (100px)
user_portrait_large Large user portrait (300px)
stats_number_of_likes # of likes
stats_number_of_views # of views
stats_number_of_comments # of comments
duration Duration of the video in seconds
width Standard definition width of the video
height Standard definition height of the video
tags Comma separated list of tags

User Info Data

id User ID
display_name User name
created_on Date the user signed up
is_staff Is this user a staff member?
is_plus Is this user a Vimeo Plus member?
location The location of the user
url User supplied url
bio The bio information from the user profile
profile_url URL to the user profile
videos_url URL to the video list for this user
total_videos_uploaded Total # of videos uploaded
total_videos_appears_in Total # of videos user appears in
total_videos_liked Total # of videos liked by user
total_contacts Total # of contacts
total_albums Total # of albums
total_channels Total # of channels moderated by user
portrait_small Small user portrait (30px)
portrait_medium Medium user portrait (100px)
portrait_large Large user portrait (300px)

Group Info Data

id Group ID
name Group name
description Group description
url URL for the group page
logo Group logo (header)
thumbnail Thumbnail
created_on Date the group was created
creator_id User ID of the group creator
creator_display_name Name of the User who created the group
creator_url The URL to the group creator’s profile
total_members Total # of users joined
total_videos Total # of videos posted to the group
total_files Total # of files uploaded to the group
total_forum_topics Total # of forum topics
total_events Total # of events
total_upcoming_events Total # of upcoming events

Channel Info Data

id Channel ID
name Channel name
description Channel description
logo Channel logo (header)
url URL for the channel page
rss RSS feed for the channel’s videos
created_on Date the channel was created
creator_id User ID of the channel creator
creator_display_name Name of the User who created the channel
creator_url The URL to the channel creator’s profile
total_videos Total # of videos posted in the channel
total_subscribers Total # of users subscribed

Album Info Data

id Album ID
created_on Date the album was created
last_modified Date the album was last modified
title Album title
description Album description
url URL for the album page
thumbnail Thumbnail
total_videos Total # of videos added to the album
user_id User ID of the user who made the album
user_display_name Name of the User who created the album
user_url The URL to the album creator’s profile

How about an example?

We’re already one step ahead of you! Just check out our API Examples repo on GitHub.