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.

Buy 2, Get 1 Free: All 10-Ream Case Paper, including OfficeMax, Boise and Hammermill Brands


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:

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

Save $100 on HP LaserJet Pro 400 M401dn Laser Printer, only $299.99 at OfficeMax.com
Youtube example:
Request URL:



    "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",
        "<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>

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"
    title="Bacon Lollys oEmbed Profile" />
<link rel="alternate" type="text/xml+oembed"
    title="Bacon Lollys oEmbed Profile" />

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>

The jQuery Code

    $('#btn').click(function() {

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");

oEmbed for other languages

Web-oEmbed (http://search.cpan.org/~miyagawa/Web-oEmbed/)

oembed_links (http://github.com/netshade/oembed_links)

Python oEmbed (http://code.google.com/p/python-oembed/)

23 thoughts on “oEmbed: An Open Format Every Developer Should Know About

  1. I’m impressed, I have to admit. Seldom do I encounter a blog that’s both equally educative and
    amusing, and let me tell you, you have hit the nail on the head.
    The problem is something too few men and women are speaking intelligently about.
    I’m very happy that I found this during my search for something regarding this.

  2. I thinκ that what you ρoѕteԁ was very
    logical. Hoωever, consider thiѕ, suрρose you сomposed a catchіer post title?
    I ain’t saying your content is not good, but suppose you added something that makes people want more? I mean Latest-Tutorial

  3. I’m not sure exactly why but this website is loading incredibly slow for me. Is anyone else having this issue or is it a problem on my end? I’ll check back later and see if the problem still exists.

  4. I was curious if you ever thought of changing the structure of your
    website? Its very well written; I love what youve got to say.
    But maybe you could a little more in the way of content so people could connect with it better.
    Youve got an awful lot of text for only having one or two images.

    Maybe you could space it out better?

  5. I know this if off topic but I’m looking into starting my own blog and was curious what all is needed to get setup? I’m assuming having
    a blog like yours would cost a pretty penny? I’m not very web savvy so I’m not 100% positive. Any tips or advice would be greatly appreciated. Thank you

  6. wała chociażby potoczny idiotyczny
    wугaz vested pyѕka.
    Siг Roger klеρnął w poκrуty wełną kufer.
    – Jak chybka – rąbnął z zadowoleniem.

    Νie była tο do końca
    praωdziwość. Wszaκ ѕtraszуdłο,
    spośród naturу przеwidujący nіе bęԁ.

  7. Thanks for your marvelous posting! I actually enjoyed reading it, you can be a great author.
    I will always bookmark your blog and may come back at some point.

    I want to encourage you to definitely continue your great job,
    have a nice day!

Leave a Reply

Your email address will not be published. Required fields are marked *