oEmbed: An Open Format Every Developer Should Know About

Most of the internet users spend their online time in creating and sharing content on internet. Sharing has became one of the most popular activity of internet users. This is attributed to formats like RSS and services like Twitter, Facebook etc. that allows user to share content with each other. oEmbed addresses the important task of sharing and embedding information anywhere on internet. It allows developers to build applications that can easily access data from vast number of websites like youtube, flickr, google video, wordpress, wikipedia and many many more. So what’s oEmbed? Well if you go by the definition on oEmbed’s official website:

oEmbed is a format for allowing an embedded representation of a URL on third party sites. The simple API allows a website to display embedded content (such as photos or videos) when a user posts a link to that resource, without having to parse the resource directly.

The best example of oEmbed can be Facebook’s status update feature. When you paste a youtube movie link in Facebook’s status bar, it automatically identify the link content as youtube movie and embed it in the status. Similarly you can paste any kind of content link: Flickr, Wikipedia etc.

Basics of oEmbed

In this document I will use two terms very often, consumer and provider. Consumer is the client who wants to convert a link into embedded content. And Provider is one who get the request and send the oembed response. For example, if you paste a youtube URL in Facebook’s status update, Facebook will be the consumer and Youtube will be the provider. A consumer who wants to convert a link into content will make an HTTP request like:

http://www.flickr.com/services/oembed/?url=http%3A//www.flickr.com/photos/bees/2341623661/
Code language: HTML, XML (xml)

and the provider, in this case Flickr will send response in JSON format:

{
	"version": "1.0",
	"type": "photo",
	"width": 240,
	"height": 160,
	"title": "ZB8T0193",
	"url": "http://farm4.static.flickr.com/3123/2341623661_7c99f48bbf_m.jpg",
	"author_name": "Bees",
	"author_url": "http://www.flickr.com/photos/bees/",
	"provider_name": "Flickr",
	"provider_url": "http://www.flickr.com/"
}
Code language: HTML, XML (xml)

Youtube example: Request URL:

http://www.youtube.com/oembed?url=http%3A//youtube.com/watch%3Fv%3DM3r2XDceM6A&format=json
Code language: HTML, XML (xml)

Response:

{
	"version": "1.0",
	"type": "video",
	"provider_name": "YouTube",
	"provider_url": "http://youtube.com/",
	"width": 425,
	"height": 344,
	"title": "Amazing Nintendo Facts",
	"author_name": "ZackScott",
	"author_url": "http://www.youtube.com/user/ZackScott",
	"html":
		"<object width=\"425\" height=\"344\">
			<param name=\"movie\" value=\"http://www.youtube.com/v/M3r2XDceM6A&fs=1\"></param>
			<param name=\"allowFullScreen\" value=\"true\"></param>
			<param name=\"allowscriptaccess\" value=\"always\"></param>
			<embed src=\"http://www.youtube.com/v/M3r2XDceM6A&fs=1\"
				type=\"application/x-shockwave-flash\" width=\"425\" height=\"344\"
				allowscriptaccess=\"always\" allowfullscreen=\"true\"></embed>
		</object>",
}
Code language: HTML, XML (xml)

Once the consumer get the response, all it has to do is to utilize the content and embed it in the page.

Request Format

The consumer who is requesting for the embed content must follow some basic rules while sending request. Requests sent to the API must be HTTP GET requests, with all arguments sent as query parameters. All arguments must be urlencoded. Following are the request parameters:

• url (required): This is the URL for which embedded content is requested
• maxwidth (optional): An optional parameter for maxwidth can be passed. Some of the content provider who support this param will send the response content accordingly. For example, Flickr may set the maxwidth of image.
• maxheight (optional): Similar to maxwidth, maxheight is an optional param.
• format (optional): By default the content provider’s response is in JSON. But consumer may want the response in other formats like XML. This parameter will determine is response format

Response Format

The provider who sends the response back to consumer may send it with following parameters.

• type (required): The resource type. Valid values, along with value-specific parameters, are described below.
• version (required): The oEmbed version number. This must be 1.0.
• title (optional): A text title, describing the resource.
• author_name (optional): The name of the author/owner of the resource.
• author_url (optional): A URL for the author/owner of the resource.
• provider_name (optional): The name of the resource provider.
• provider_url (optional): The url of the resource provider.
• cache_age (optional): The suggested cache lifetime for this resource, in seconds. Consumers may choose to use this value or not.
• thumbnail_url (optional): A URL to a thumbnail image representing the resource. The thumbnail must respect any maxwidth and maxheight parameters. If this paramater is present, thumbnail_width and thumbnail_height must also be present.
• thumbnail_width (optional): The width of the optional thumbnail. If this paramater is present, thumbnail_url and thumbnail_height must also be present.
• thumbnail_height (optional): The height of the optional thumbnail. If this paramater is present, thumbnail_url and thumbnail_width must also be present.

The provider may wants to add more attributes to the response.

Letting People Know You Support oEmbed

The oEmbed providers can make their service discoverable by adding following element in HEAD for the HTML document.

<link rel="alternate" type="application/json+oembed"
	href="http://flickr.com/services/oembed?url=http%3A//flickr.com/photos/bees/2362225867/&format=json"
	title="Bacon Lollys oEmbed Profile" />
<link rel="alternate" type="text/xml+oembed"
	href="http://flickr.com/services/oembed?url=http%3A//flickr.com/photos/bees/2362225867/&format=xml"
	title="Bacon Lollys oEmbed Profile" />
Code language: HTML, XML (xml)

The URLs contained within the href attribute should be the full oEmebed endpoint plus URL and any needed format parameter. No other request parameters should be included in this URL. The type attribute must contain either application/json+oembed for JSON responses, or text/xml+oembed for XML.

oEmbed Demo with jQuery

Integrating oEmbed support in your application using jQuery is very easy using jQuery oEmbed plugin. Following is the source code the of demo. The HTML Code

Content URL:
<input type="text" id="update"/><button id="btn">Get</button>
<div id="embed"></div>
Code language: HTML, XML (xml)

The jQuery Code

$(function(){
	$('#btn').click(function() {
		$("#embed").oembed($('#update').val());
	});
});
Code language: JavaScript (javascript)

Don’t forget to include jquery library and jquery oembed javascript in the demo. The Demo Enter any oEmbed supporting URL (Youtube video link or Flickr link http://www.flickr.com/photos/stuckincustoms/2035748576/) in below textbox and press Get. (demo link)

oEmbed in PHP

There is a small PHP library that can be used to integrate oEmbed support in PHP. oEmbed-PHP is a library that provides OEmbed compatible interface for javascript and PHP clients to consume. It can deal with OEmbed providers by acting as a proxy, and it has a plugin system where you can add your own embed-providers. Import this small PHP library and directly use it in your application.

$manager = ProviderManager::getInstance();
  $obj=$manager->provide("http://www.youtube.com/watch? v=EQqJSAOOmGI","object");
  $html=$obj->renderClass();
Code language: PHP (php)

oEmbed for other languages

Perl Web-oEmbed (http://search.cpan.org/~miyagawa/Web-oEmbed/) Ruby oembed_links (http://github.com/netshade/oembed_links) Python Python oEmbed (http://code.google.com/p/python-oembed/)