×Video encoding is running slowly right now. You can keep uploading, but it may be awhile before it converts. We apologize for the inconvenience!

oEmbed is an open standard for embedding videos and/or images into a website. You can use the Vimeo URL of any video to easily obtain the embed code for that video. To find out more about oEmbed, view the spec or check out Webmonkey's Get Started With OEmbed tutorial.

API Endpoint

You can use the API endpoint to request the embed code for a video from its URL. The response format can be either xml or json.

http://vimeo.com/api/oembed.format

Vimeo videos can use one of two URL schemes:

http://vimeo.com/*
http://vimeo.com/groups/*/videos/*

If you supply a group video URL, extra data about that group will be returned with the response.

Discovery

Vimeo supports discovery of the oEmbed URL. Each page that has a video will have two link tags with types application/json+oembed and application/xml+oembed containing the URLs for JSON and XML oEmbed responses.

Arguments

All arguments are sent as query parameters and must be urlencoded (as per RFC 1738).

url
The Vimeo URL for a video.
width
(optional) The exact width of the video. Defaults to original size.
maxwidth
(optional) Same as width, but video will not exceed original size.
height
(optional) The exact height of the video. Defaults to original size.
maxheight
(optional) Same as height, but video will not exceed original size.
byline
(optional) Show the byline on the video. Defaults to true.
title
(optional) Show the title on the video. Defaults to true.
portrait
(optional) Show the user's portrait on the video. Defaults to true.
color
(optional) Specify the color of the video controls.
callback
(optional) When returning JSON, wrap in this function.
autoplay
(optional) Automatically start playback of the video. Defaults to false.

Note: if the owner of a video is a Plus member, some of these settings may be overridden by their preferences. is_plus is provided in the response to alert you when the owner is a Plus member.

Example Call

http://vimeo.com/api/oembed.xml?url=http%3A//vimeo.com/757219

Example Responses

These are sample responses (they have been shortened for formatting). If a group video URL is used, additional data will be returned about the group. If a video's privacy is set to anything other than public or password protected, only the embed code, width, and height will be returned.

XML

Call:

http://vimeo.com/api/oembed.xml?url=http%3A//vimeo.com/757219

Response:

<?xml version="1.0" encoding="UTF-8"?>
<oembed>
  <type>video</type>
  <version>1.0</version>
  <provider_name>Vimeo</provider_name>
  <provider_url>http://www.vimeo.com/</provider_url>
  <title>Meet the office</title>
  <author_name>Blake Whitman</author_name>
  <author_url>http://www.vimeo.com/blakewhitman</author_url>
  <is_plus>0</is_plus>
  <html>&lt;object type=&quot;application/x-shockwave-flash&quot;...&lt;/object&gt;</html>
  <width>504</width>
  <height>380</height>
  <thumbnail_url>
    http://90.media.vimeo.com/d1/5/38/21/85/thumbnail-38218529.jpg
  </thumbnail_url>
  <thumbnail_width>160</thumbnail_width>
  <thumbnail_height>120</thumbnail_height>
  <video_id>757219</video_id>
</oembed>

JSON

Call:

http://vimeo.com/api/oembed.json?url=http%3A//vimeo.com/757219

Response:

{
  "type": "video",
  "version": "1.0",
  "provider_name": "Vimeo",
  "provider_url": "http:\/\/www.vimeo.com\/",
  "title": "Meet the office",
  "author_name": "Blake Whitman",
  "author_url": "http:\/\/www.vimeo.com\/blakewhitman",
  "is_plus": "0",
  "html": "&lt;object type=&quot;application...&lt;\/object&gt;",
  "width": "504",
  "height": "380",
  "thumbnail_url": "http:\/\/90.media.vimeo.com\/d1...85\/thumbnail-38218529.jpg",
  "thumbnail_width": "160",
  "thumbnail_height": "120",
  "video_id": "757219"
}

PHP and Javascript Examples

The first example is really basic and will embed a specific video on a page. The second is a little fancier and will grab a user's videos (using the Simple API) and embed the last video they uploaded.

oEmbed Example
Simple API & oEmbed Example

Be sure to check out the Downloads page for more examples.