National Library of New Zealand
Harvested by the National Library of New Zealand on: Aug 24 2011 at 11:16:43 GMT
Search boxes and external links may not function. Having trouble viewing this page? Click here
Close Minimize Help
Wayback Machine

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.
loop
(optional) Play the video again automatically when it reaches the end. Defaults to false.
xhtml
(optional) Make the embed code XHTML compliant. Defaults to true.
api
(optional) Enable the Javascript API for Moogaloop. Defaults to false.
wmode
(optional) Add the "wmode" parameter. Can be either transparent or opaque.
iframe
(optional) Use our new embed code. Defaults to true. New!

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/7100569

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/7100569

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

We have two examples for you: a really basic example for embedding a specific video on a page, and a fancier one that grabs and embeds the latest video from a user. Both examples are available from the Downloads page.