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.

This document is stored on GitHub.

Table Of Contents

1. Quick Example

A consumer (e.g. WordPress) makes the following HTTP request:

The provider (e.g. 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.

2. Full Spec

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.

2.1. Configuration

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:

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: