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:
and the provider, in this case Flickr will send response in JSON format:
Save $100 on HP LaserJet Pro 400 M401dn Laser Printer, only $299.99 at OfficeMax.com
Once the consumer get the response, all it has to do is to utilize the content and embed it in the page.
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
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.
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
The jQuery Code
Enter any oEmbed supporting URL (Youtube video link or Flickr link http://www.flickr.com/photos/stuckincustoms/2035748576/) in below textbox and press Get.
oEmbed in PHP
Import this small PHP library and directly use it in your application.
oEmbed for other languages
Python oEmbed (http://code.google.com/p/python-oembed/)