This is a simple Node.js library for interacting with the Vimeo API.

• Get Started
• Help
• Troubleshooting
• Installation
• Usage
  • Authentication and access tokens
    • Unauthenticated
    • Authenticated
  • Make requests
  • Uploading videos
    • Replacing video files

Get started with the Vimeo API

There is a lot of information about the Vimeo API at https://developer.vimeo.com/api/start. Most of your questions are answered there!

Direct Help

• Stack Overflow
• Vimeo Support

Installation

npm install vimeo

Usage

All API requests and examples in this file must create a Vimeo object. Your CLIENT_ID and CLIENT_SECRET can be found on your app page under the Authentication tab. If you have not yet created an API app with Vimeo, you can create one at https://developer.vimeo.com/apps.

You can optionally provide an ACCESS_TOKEN to the constructor. Access tokens are required only to make requests, and you can set them later through the setAccessToken method.

You can generate acces tokens on your Vimeo app page or through the API.

var Vimeo = require('vimeo').Vimeo;
var client = new Vimeo(CLIENT_ID, CLIENT_SECRET, ACCESS_TOKEN);

Generate your access token

All requests require access tokens. There are two types of access tokens:

• Unauthenticated: Access tokens without a user. These tokens can view only public data.
• Authenticated: Access tokens with a user. These tokens interact on behalf of the authenticated user.

Unauthenticated

Unauthenticated API requests must generate an access token. You should not generate a new access token for each request. Instead, request an access token once and use it forever.

// `scope` is an array of permissions your token needs to access. You
// can read more at https://developer.vimeo.com/api/authentication#supported-scopes
client.generateClientCredentials(scope, function (err, response) {
  if (err) {
    throw err;
  }

  var token = response.access_token;

  // Other useful information is included alongside the access token,
  // which you can dump out to see, or visit our API documentation.
  //
  // We include the final scopes granted to the token. This is
  // important because the user, or API, might revoke scopes during
  // the authentication process.
  var scopes = response.scope;
});

Authenticated

1. Build a link to Vimeo so your users can authorize your app.

var url = client.buildAuthorizationEndpoint(redirect_uri, scopes, state)

2. Your user needs to access the authorization endpoint (either by clicking the link or through a redirect). On the authorization endpoint, the user has the option to deny your app any scopes you have requested. If they deny your app, they are redirected back to your redirect_url with an error parameter.

3. If the user accepts your app, they are redirected back to your redirect_uri with a code and state query parameter (eg. http://yourredirect.com?code=abc&state=xyz).

   1. You must validate that the state matches your state from Step 1.
   2. If the state is valid, you can exchange your code and redirect_uri for an access token.

// `redirect_uri` must be provided, and must match your configured URI.
client.accessToken(code, redirect_uri, function (err, response) {
  if (err) {
    return response.end("error\n" + err);
  }

  if (response.access_token) {
    // At this state the code has been successfully exchanged for an
    // access token
    client.setAccessToken(response.access_token);

    // Other useful information is included alongside the access token,
    // which you can dump out to see, or visit our API documentation.
    //
    // We include the final scopes granted to the token. This is
    // important because the user, or API, might revoke scopes during
    // the authentication process.
    var scopes = response.scope;

    // We also include the full user response of the newly
    // authenticated user.
    var user = response.user;
  }
});

Make requests

The API library has a request method that takes two parameters.

Options

This object contains your request information in key/value pairs.

Callback

This function is called once the upload process is complete.

client.request(/*options*/{
  // This is the path for the videos contained within the staff picks
  // channels
  path: '/channels/staffpicks/videos',
  // This adds the parameters to request page two, and 10 items per
  // page
  query: {
    page: 2,
    per_page: 10,
    fields: 'uri,name,description,duration,created_time,modified_time'
  }
}, /*callback*/function (error, body, status_code, headers) {
  if (error) {
    console.log('error');
    console.log(error);
  } else {
    console.log('body');
    console.log(body);
  }

  console.log('status code');
  console.log(status_code);
  console.log('headers');
  console.log(headers);
});

Rate limiting

You should ensure to set JSON filter fields on all requests to ensure a steady and higher X-RateLimit-Limit.

There is an open issue#51 to reflect that the current documentation states that POST, PUT, DELETE, and PATCH requests must provide parameters in the body, but this doesn't work with the JSON filter request. Here is an example of a properly formed DELETE request:

client.request(/*options*/{
  method: 'DELETE',
  path: '/channels/12345?fields=uri'
}, /*callback*/function (error, body, status_code, headers) {
  if (error) {
    console.log('error');
    console.log(error);
  } else {
    console.log('body');
    console.log(body);
  }

  console.log('status code');
  console.log(status_code);
  console.log('headers');
  console.log(headers);
});

Uploading videos

The API library has an upload method that takes five parameters.

Internally, this library executes a tus upload approach and sends a file to the server with the tus upload protocol and tus-js-client.

client.upload(
  '/home/aaron/Downloads/ada.mp4',
  function (uri) {
    console.log('File upload completed. Your Vimeo URI is:', uri)
  },
  function (bytesUploaded, bytesTotal) {
    var percentage = (bytesUploaded / bytesTotal * 100).toFixed(2)
    console.log(bytesUploaded, bytesTotal, percentage + '%')
  },
  function (error) {
    console.log('Failed because: ' + error)
  }
)

Replacing video files

To replace the source file of a video, call the replace method. It accepts five parameters:

client.upload(
  '/home/aaron/Downloads/ada-v2.mp4',
  '/videos/15'
  function (uri) {
    console.log('File upload completed. Your Vimeo URI is:', uri)
  },
  function (bytesUploaded, bytesTotal) {
    var percentage = (bytesUploaded / bytesTotal * 100).toFixed(2)
    console.log(bytesUploaded, bytesTotal, percentage + '%')
  },
  function (error) {
    console.log('Failed because: ' + error)
  }
)

Troubleshooting

If you have any questions or problems, create a ticket or contact us.

Contributors

To see the contributors, please visit the contributors graph.