APIs /

Advanced API

Energistically target user friendly catalysts for change vis-a-vis intermandated functionalities. Credibly iterate accurate expertise without cross-platform alignments.

Getting Started

  1. Get your API key and download a library

    You’ll need an API key and secret (also known as a Consumer key and Consumer secret in OAuth-speak) for each application you create. To create a key, you’ll need to supply us with some basic information about your application. Don’t worry if you’re not sure about all of the information, you can always edit it later.

    Register a new application
    See the list of libraries

  2. Authenticate a user

    In order to access private data, or edit data on Vimeo, you’ll need to authenticate a user. Vimeo uses the OAuth specification. Your application will direct the user to a page on Vimeo where they will decide whether to authorize your application. If they authorize, they’ll be redirected back to your application.

    See the authentication documentation

  3. Make API calls to Vimeo

    Once a user has given permission, you can call the Vimeo API on behalf of the user. You can access all of their videos, edit videos, and upload videos (if approved).

    See the Advanced API method list

  4. Follow our API update feeds

    Follow our API Status Blog or our Twitter to keep up-to-date with changes in the API.

Endpoint

All Advanced API method calls run through the following endpoint, with the method name specified as the ?method parameter.

http://vimeo.com/api/rest/v2?method=METHOD

Methods

For a complete list of all of the methods available, see the Advanced API method list.

OAuth

You’ll need to sign every call you make to the Vimeo API using a system called OAuth. We require it so that we can verify that your app is the one making calls. It’s especially important when making API calls on behalf of users.

If you’re totally unfamiliar with OAuth, we recommend that you read hueniverse’s OAuth 1.0 Guide before you continue. OAuth is complicated, and he does a great job of explaining the process. Twitter’s guide is also very good.

The Vimeo API supports the OAuth 1.0a Protocol. We will accept the OAuth parameters in either the Authorization header, POST params, or GET params, although you should use the Authorization header.

Access tokens do not expire, unless the user removes authorization for the app from their settings page.

If you want to get right down to the nitty-gritty, skip to the Authentication page that will walk you through creating the oauth_signature parameter.

Endpoints

Request Token URL https://vimeo.com/oauth/request_token
Authorize URL https://vimeo.com/oauth/authorize
Access Token URL https://vimeo.com/oauth/access_token

Libraries

There are plenty of OAuth libraries available in pretty much every language. You should not need to implement OAuth yourself. Also be sure to see the list of libraries specifically designed for working with our API.

xAuth

xAuth is a way for desktop and mobile apps to get an OAuth access token from a user’s email and password.

xAuth access is restricted to approved apps only.

To request an access token, the make a secure HTTP POST to https://vimeo.com/oauth/access_token with the following parameters in addition to the OAuth Authorization header:

x_auth_mode Must be set to "client_auth".
x_auth_username The username or email of the user to obtain a token for.
x_auth_password The user’s password.
x_auth_permission The level of permission needed (read, write, or delete).

The user’s credentials should never be kept by the app.

The response for this method is identical to the OAuth Access Token response.

Access tokens generated by xAuth will expire when the user changes their password or if they revoke access to the application.

xAuth Errors

There are three errors that you might receive. All return an HTTP status of 401.

  • Invalid xAuth mode - The x_auth_mode parameter must be set to "client_auth".

    You’ll get this error if you set x_auth_mode to anything other than

    client_auth

    .

  • Missing required parameter - A required parameter was missing: [parameter name]

    You will get this if you don’t pass x_auth_username and x_auth_password.

  • User not found - The user credentials passed are not valid.

    You will get this if either the username or password was incorrect.

Upload API

You can use the Advanced API to upload videos to an account that has been authorized with your application. All applications must be approved for upload access before they can upload.

Upload API Documentation

Response Formats

All API results are returned using one of the following response formats:

  • XML

    The XML response is really simple. This is the default response format, so you don't need to specify the format parameter.

    <?xml version="1.0" encoding="UTF-8"?>
<rsp generated_in="0.0438" stat="ok">
  <person id="101193" is_plus="1" is_staff="1">
    <username>brad</username>
    <display_name>Brad Dougherty</display_name>
    <location>Brooklyn, NY</location>
    <url>http://brad.is</url>
    <number_of_contacts>60</number_of_contacts>
    <number_of_uploads>6</number_of_uploads>
    <number_of_likes>216</number_of_likes>
    <number_of_videos>14</number_of_videos>
    <number_of_videos_appears_in>8</number_of_videos_appears_in>
    <profileurl>http://www.vimeo.com/brad/</profileurl>
    <videosurl>http://www.vimeo.com/brad/videos/</videosurl>
  </person>
</rsp>

    In the event of an error, you'll get something like this:

    <?xml version="1.0" encoding="UTF-8"?>
<rsp stat="fail" generated_in="0.00032">
  <err code="1" msg="User Not Found" />
</rsp>

  • JSON

    JSON (JavaScript Object Notation) is a lightweight computer data interchange format. It is a text-based, human-readable format for representing objects and other data structures and is mainly used to transmit such structured data over a network connection (in a process called serialization). (Wikipedia)

    To get an API response in JSON format, send a parameter format in the request with a value of json.

    {
    "generated_in": "0.0283",
    "stat": "ok",
    "person": {
        "id": "101193",
        "is_plus": "1",
        "is_staff": "1",
        "username": "brad",
        "display_name": "Brad Dougherty",
        "location": "Rochester, NY",
        "url": "http:\/\/brad.dougherty.name",
        "number_of_contacts": "60",
        "number_of_uploads": "6",
        "number_of_likes": "216",
        "number_of_videos": "14",
        "number_of_videos_appears_in": "8",
        "profileurl": "http:\/\/www.vimeo.com\/brad\/",
        "videosurl": "http:\/\/www.vimeo.com\/brad\/videos\/"
    }
}

    In the event of an error, you'll get something like this:

    {
    "generated_in": "0.0283",
    "stat": "fail",
    "err": {
        "code": "1",
        "msg": "User Not Found"
    }
}

  • JSONP

    JSONP is the same as the JSON response, but it's wrapped in a callback function.

    To get an API response in JSONP format, send a parameter format in the request with a value of jsonp, and a callback parameter set to the name of the function you want to call. If no callback is set, it will default to vimeoCallback.

    vimeoCallback({
    "generated_in": "0.0283",
    "stat": "ok",
    "person": {
        "id": "101193",
        "is_plus": "1",
        "is_staff": "1",
        "username": "brad",
        "display_name": "Brad Dougherty",
        "location": "Rochester, NY",
        "url": "http:\/\/brad.dougherty.name",
        "number_of_contacts": "60",
        "number_of_uploads": "6",
        "number_of_likes": "216",
        "number_of_videos": "14",
        "number_of_videos_appears_in": "8",
        "profileurl": "http:\/\/www.vimeo.com\/brad\/",
        "videosurl": "http:\/\/www.vimeo.com\/brad\/videos\/"
    }
})

    In the event of an error, you'll get something like this:

    vimeoCallback({
    "generated_in": "0.0283",
    "stat": "fail",
    "err": {
        "code": "1",
        "msg": "User Not Found"
    }
})

  • PHP

    The PHP result is a serialized version of the XML format. So the responses will be the same as above, only as PHP objects.

    To get an API response in PHP format, send a parameter format in the request with a value of php.

    stdClass Object
(
    [generated_in] => 0.0717
    [stat] => ok
    [person] => stdClass Object
        (
            [id] => 101193
            [is_plus] => 1
            [is_staff] => 1
            [username] => brad
            [display_name] => Brad Dougherty
            [location] => Rochester, NY
            [url] => http://brad.is
            [number_of_contacts] => 60
            [number_of_uploads] => 4
            [number_of_likes] => 215
            [number_of_videos] => 12
            [number_of_videos_appears_in] => 8
            [profileurl] => http://www.vimeo.com/brad/
            [videosurl] => http://www.vimeo.com/brad/videos/
        )

)

    In the event of an error, you'll get something like this:

    stdClass Object
(
    [generated_in] => 0.0717
    [stat] => fail
    [err] => stdClass Object
        (
            [code] => 1
            [msg] => User Not Found
        )

)

Official Libraries

These are the libraries and examples that we’ve written for you.

Advanced API PHP Library

Download / GitHub Page

Unofficial Libraries & Downloads

This is a sampling of plugins made by members of the Vimeo community. They are not maintained or supported by Vimeo, so use them at your own risk. If you have trouble with them, contact the developer directly.