oEmbed API

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.

Arguments

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

url
width
maxwidth
byline
title
portrait
color
callback

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

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.

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><![CDATA[
    &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>
  <clip_id>757219</clip_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",
  "clip_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.

vimeo-oEmbed-example.zip (4 K)
vimeo-simple-api-oEmbed-example.zip (4 K)