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.
A consumer (eg. Pownce) makes the following HTTP request:
http://www.flickr.com/services/oembed/?url=http%3A//www.flickr.com/photos/bees/2341623661/
The provider (eg. Flickr) then responds with an oEmbed response:
{ "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/" }
This allows the consumer to turn a URL to a Flickr photo page into structured data to allow embedding of that photo in the consumer's website.
This spec is broken into three parts - configuration, the consumer request and the provider response.
An oEmbed exchange occurs between a consumer and a provider. A consumer wishes to show an embedded representation of a third party resource on their own web site, such as a photo or an embedded video. A provider implements the oEmbed API to allow consumers to fetch that representation.
Configuration for oEmbed is very simple. Providers must specify one or more URL scheme and API endpoint pairs. The URL scheme describes which URLs provided by the service may have an embedded representation. The API endpoint describes where the consumer may request representations for those URLs.
For instance:
http://www.flickr.com/photos/*
http://www.flickr.com/services/oembed/
The URL scheme may contain one or more wildcards (specified with an asterisk). Wildcards may be present in the domain portion of the URL, or in the path. Within the domain portion, wildcards may only be used for subdomains. Wildcards may not be used in the scheme (to support HTTP and HTTPS, provide two url/endpoint pairs).
Some examples:
http://www.flickr.com/photos/*
OK http://www.flickr.com/photos/*/foo/
OK http://*.flickr.com/photos/*
OK http://*.com/photos/*
NOT OK *://www.flickr.com/photos/*
NOT OK The API endpoint must point to an HTTP endpoint URL (not HTTPS) which implements the API described below.
Requests sent to the API endpoint must be HTTP GET requests, with all arguments sent as query parameters. All arguments must be urlencoded (as per RFC 1738).
The following query parameters are defined as part of the spec:
url
(required)maxwidth
(optional)maxheight
(optional)format
(optional)Providers should ignore all other arguments it doesn't expect. Providers are welcome to support custom additional parameters.
Some examples:
http://flickr.com/services/oembed?url=http%3A//flickr.com/photos/bees/2362225867/
http://flickr.com/services/oembed?url=http%3A//flickr.com/photos/bees/2362225867/&maxwidth=300&maxheight=400&format=json
Note: Providers may choose to have the format specified as part of the endpoint URL itself, rather than as a query string parameter.
For instance:
http://www.flickr.com/photos/*
http://www.flickr.com/services/oembed.xml
http://www.flickr.com/services/oembed.json
In this case, the format parameter is not needed and will be ignored. When a provider publishes a URL scheme and API endpoint pair, they should clearly state whether the format is implicit in the endpoint or if it needs to be passed as an argument.
The response returned by the provider can be in either JSON or XML. Each format specifies a way of encoding name-value pairs which comprise the response data. Each format has an associated mime-type which must be returned in the Content-type
header along with the response.
JSON responses must contain well formed JSON and must use the mime-type of application/json
. The JSON response format may be requested by the consumer by specifying a format
of json
.
For example:
{ "foo": "bar", "baz": 1 }
The key-value pairs to be returned are specified below. All text must be UTF-8 encoded.
XML responses must use the mime-type of text/xml
. The XML response format may be requested by the consumer by specifying a format
of xml
. The response body must contain well formed XML with a root element called oembed
and child elements for each key containing the value within the element body. For example:
<?xml version="1.0" encoding="utf-8" standalone="yes"?> <oembed> <foo>bar</foo> <baz>1</baz> </oembed>
The key-value pairs to be returned are specified below. All text must be UTF-8 encoded. Values should be escaped PCDATA. For example:
<?xml version="1.0" encoding="utf-8" standalone="yes"?> <oembed> <html><b>awesome!</b></html> </oembed>
Responses can specify a resource type, such as photo
or video
. Each type has specific parameters associated with it. The following response parameters are valid for all response types:
type
(required)version
(required)1.0
.title
(optional)author_name
(optional)author_url
(optional)provider_name
(optional)provider_url
(optional)cache_age
(optional)thumbnail_url
(optional)maxwidth
and maxheight
parameters. If this paramater is present, thumbnail_width
and thumbnail_height
must also be present.thumbnail_width
(optional)thumbnail_url
and thumbnail_height
must also be present.thumbnail_height
(optional)thumbnail_url
and thumbnail_width
must also be present.Providers may optionally include any parameters not specified in this document (so long as they use the same key-value format) and consumers may choose to ignore these. Consumers must ignore parameters they do not understand.
photo
typeThis type is used for representing static photos. The following parameters are defined:
url
(required)<img>
element. Only HTTP and HTTPS URLs are valid.width
(required)url
parameter.height
(required)url
parameter.Responses of this type must obey the maxwidth
and maxheight
request parameters.
video
typeThis type is used for representing playable videos. The following parameters are defined:
html
(required)width
(required)height
(required)Responses of this type must obey the maxwidth
and maxheight
request parameters. If a provider wishes the consumer to just provide a thumbnail, rather than an embeddable player, they should instead return a photo
response type.
link
typeResponses of this type allow a provider to return any generic embed data (such as title
and author_name
), without providing either the url or html parameters. The consumer may then link to the resource, using the URL specified in the original request.
rich
typeThis type is used for rich HTML content that does not fall under one of the other categories. The following parameters are defined:
html
(required)width
(required)height
(required)Responses of this type must obey the maxwidth
and maxheight
request parameters.
Providers should return any error conditions as HTTP status codes. The following status codes are defined as part of the oEmbed specification:
404 Not Found
url
parameter. This allows providers to be broad in their URL scheme, and then determine at call time if they have a representation to return.501 Not Implemented
format=xml
and the provider doesn't support XML responses. However, providers are encouraged to support both JSON and XML.401 Unauthorized
When a consumer displays any URLs, they will probably want to filter the URL scheme to be one of http
, https
or mailto
, although providers are free to specify any valid URL. Without filtering, Javascript:...
style URLs could be used for XSS attacks.
When a consumer displays HTML (as with video embeds), there's a vector for XSS attacks from the provider. To avoid this, it is recommended that consumers display the HTML in an iframe
, hosted from another domain. This ensures that the HTML cannot access cookies from the consumer domain.
oEmbed providers can choose to make their oEmbed support discoverable by adding elements to the head of their existing (X)HTML documents.
For example:
<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" />
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.
Request:
http://www.youtube.com/oembed?url=http%3A//youtube.com/watch%3Fv%3DM3r2XDceM6A&format=json
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>", }
Request:
http://iamcal.com/oembed/?url=http%3A//www.iamcal.com/linklog/1206113631/&format=xml
Response:
<?xml version="1.0" encoding="utf-8" standalone="yes"?> <oembed> <version>1.0</version> <type>link</type> <author_name>Cal Henderson</author_name> <author_url>http://iamcal.com/</author_url> <cache_age>86400</cache_age> <provider_name>iamcal.com</author_name> <provider_url>http://iamcal.com/</provider_url> </oembed>
YouTube (http://www.youtube.com/)
http://www.youtube.com/oembed
<link>
tags Flickr (http://www.flickr.com/)
http://*.flickr.com/*
http://www.flickr.com/services/oembed/
Viddler (http://www.viddler.com/)
http://*.viddler.com/*
http://lab.viddler.com/services/oembed/
Qik (http://qik.com/)
http://qik.com/video/*
http://qik.com/*
http://qik.com/api/oembed.{format}
Revision3 (http://revision3.com/)
http://*.revision3.com/*
http://revision3.com/api/oembed/
Hulu (http://www.hulu.com/)
http://www.hulu.com/watch/*
http://www.hulu.com/api/oembed.{format}
Vimeo (http://vimeo.com/)
http://www.vimeo.com/*
http://www.vimeo.com/groups/*/*
http://www.vimeo.com/api/oembed.{format}
oohEmbed (http://oohembed.com/)
http://oohembed.com/oohembed/
Poll Everywhere (http://www.polleverywhere.com/)
http://www.polleverywhere.com/polls/*
http://www.polleverywhere.com/multiple_choice_polls/*
http://www.polleverywhere.com/free_text_polls/*
http://www.polleverywhere.com/services/oembed/
My Opera (http://my.opera.com/)
http://my.opera.com/service/oembed
Clearspring Widgets (http://widgets.clearspring.com/)
http://widgets.clearspring.com/widget/v1/oembed/
To have a particular consumer display your OEmbed, please contact the consumer with your provider's URL scheme and API endpoint.
Buckybase (http://buckybase.appspot.com/)
280 Slides (http://280slides.com/)
Dumble (http://oohembed.com/dumble/)
PHP
Perl
Ruby
Python