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 three URL schemes:

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

If you supply a channel video URL, extra data about that channel will be returned with the response. Similarly, you’ll get data about a group if you use the group URL.

All of the above URLs will also work with HTTPS.

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 (required) The Vimeo URL for a video.
width The exact width of the video. Defaults to original size.
maxwidth Same as width, but video will not exceed original size.
height The exact height of the video. Defaults to original size.
maxheight Same as height, but video will not exceed original size.
byline Show the byline on the video. Defaults to true.
title Show the title on the video. Defaults to true.
portrait Show the user’s portrait on the video. Defaults to true.
color Specify the color of the video controls.
callback When returning JSON, wrap in this function.
autoplay Automatically start playback of the video. Defaults to false.
loop Play the video again automatically when it reaches the end. Defaults to false.
autopause Pause this video automatically when another one plays. Defaults to true.
xhtml Make the embed code XHTML compliant. Defaults to false.
api Enable the JavaScript API. Defaults to false.
player_id A unique id for the player that will be passed back with all JavaScript API responses.

If the owner of a video is a Plus or PRO 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 or PRO member.

Examples

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

http://vimeo.com/api/oembed.xml?url=http%3A//vimeo.com/76979871
<?xml version="1.0" encoding="UTF-8"?>
<oembed>
    <type>video</type>
    <version>1.0</version>
    <provider_name>Vimeo</provider_name>
    <provider_url>https://vimeo.com/</provider_url>
    <title>The New Vimeo Player (You Know, For Videos)</title>
    <author_name>Vimeo Staff</author_name>
    <author_url>http://vimeo.com/staff</author_url>
    <is_plus>0</is_plus>
    <html>&lt;iframe src=&quot;//player.vimeo.com/video/76979871&quot; width=&quot;1280&quot; height=&quot;720&quot; frameborder=&quot;0&quot; title=&quot;The New Vimeo Player (You Know, For Videos)&quot; webkitallowfullscreen mozallowfullscreen allowfullscreen&gt;&lt;/iframe&gt;</html>
    <width>1280</width>
    <height>720</height>
    <duration>62</duration>
    <description>It may look (mostly) the same on the surface, but under the hood we totally rebuilt our player. Here’s a quick rundown of some of the coolest new features:

• Lightning fast playback
• Redesigned Share screen
• Closed caption and subtitle compatible
• HTML5 by default
• Purchase-from-player functionality for embedded Vimeo On Demand trailers
• More responsive than ever (go ahead, resize it, we dare you!!!)

We’re really proud of these updates. So proud that we made a spiffy new page to showcase all the reasons why we have the best video player in the galaxy. Check it out here: http://vimeo.com/player

In short, this is a player that even haters can love.</description>
    <thumbnail_url>http://i.vimeocdn.com/video/452001751_1280.jpg</thumbnail_url>
    <thumbnail_width>1280</thumbnail_width>
    <thumbnail_height>720</thumbnail_height>
    <video_id>76979871</video_id>
</oembed>

JSON

http://vimeo.com/api/oembed.json?url=http%3A//vimeo.com/76979871
{
    "type": "video",
    "version": "1.0",
    "provider_name": "Vimeo",
    "provider_url": "https:\/\/vimeo.com\/",
    "title": "The New Vimeo Player (You Know, For Videos)",
    "author_name": "Vimeo Staff",
    "author_url": "http:\/\/vimeo.com\/staff",
    "is_plus": "0",
    "html": "<iframe src=\"\/\/player.vimeo.com\/video\/76979871\" width=\"1280\" height=\"720\" frameborder=\"0\" title=\"The New Vimeo Player (You Know, For Videos)\" webkitallowfullscreen mozallowfullscreen allowfullscreen><\/iframe>",
    "width": 1280,
    "height": 720,
    "duration": 62,
    "description": "It may look (mostly) the same on the surface, but under the hood we totally rebuilt our player. Here\u2019s a quick rundown of some of the coolest new features:\n\n\u2022 Lightning fast playback\n\u2022 Redesigned Share screen\n\u2022 Closed caption and subtitle compatible\n\u2022 HTML5 by default\n\u2022 Purchase-from-player functionality for embedded Vimeo On Demand trailers\n\u2022 More responsive than ever (go ahead, resize it, we dare you!!!)\n\nWe\u2019re really proud of these updates. So proud that we made a spiffy new page to showcase all the reasons why we have the best video player in the galaxy. Check it out here: http:\/\/vimeo.com\/player\n\nIn short, this is a player that even haters can love.",
    "thumbnail_url": "http:\/\/i.vimeocdn.com\/video\/452001751_1280.jpg",
    "thumbnail_width": 1280,
    "thumbnail_height": 720,
    "video_id": 76979871
}

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 our API Examples repo on GitHub.