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.
- v1.0: http://public-api.wordpress.com/oembed/1.0/
- Always latest (currently v1.0): http://public-api.wordpress.com/oembed/
Query string parameters:
- for: [required] please set to your domain or company name so we can know who our friends are.
- url: [required] any
wp.me/*and mapped [sub]domains hosted on WordPress.com, such as TechCrunch, CNN blogs and countless personal sites.
xml, defaults to
- callback: when used with
- maxwidth and/or maxheight: max width and or height for images/thumbnails, defaults to 440x330px.
- img_size: alternative to maxwidth/maxheight, as [width]x[height], defaults to 440x330px.
false, triggers the non-standard article extension for post/pages (see below).
The as_article parameter triggers a non-standard oEmbed output of type article. When content is served as_article, content can be found in a body property, instead of the standard html property. Other non-standard properties, such as related_topics, are also available. This output was originally made available for one of our partners, but is available to all.
- in as_article mode, content is stripped of tags and limited to a ~256 characters excerpt (type=article, with body property).
- in standard (as_article=false) mode, content is served as markup in full, or in excerpt if provided and as set by author (type=link, with html property).
- supports posts and pages as link/html or article/body (see as_article argument).
- supports attachments (picts/media/documents) as type link or type photo for images (gif, jpg, jpeg, png).
- thumbnail for post and pages if present, from post thumb or 1st pict in content.
- local and remote images are resized and/or re-cropped to desired dimensions, for consistency, then cached (including CDN) for speed.
- support geolocation data, when made available by the author, through custom properties (
- supports related_topics when as_article=true.
We currently support WP.me shortlinks which point to WordPress.com hosted sites. We are exploring also supporting the same feature for self-hosted WordPress sites running Jetpack or our stats plugin, when users opt-in to enable WP.me shortlinks on their self-hosted site. Stay tuned!
- Post with thumbnail on WordPress.com
- Post, on mapped domain (TechCrunch)
- Photo and text, as_article
- Post with gallery, as XML
- Custom thumb size, as_article
- WP.me URL, post
- Image attachment, as photo
- Attachement as WP.me URL, as photo
We are now adding the related link tags to site headers, for posts, pages and attachments (for public sites only) so that 3rd-party sites can automatically discover the oEmbed representation equivalent of your content:
<link rel="alternate" type="application/json+oembed" href="http://public-api.wordpress.com/oembed/1.0/?format=json&url=http%3A%2F%2Ftekartist.org%2F2011%2F07%2F13%2Fyourself-truly-by-emma%2F&for=wpcom-auto-discovery" /> <link rel="alternate" type="application/xml+oembed" href="http://public-api.wordpress.com/oembed/1.0/?format=xml&url=http%3A%2F%2Ftekartist.org%2F2011%2F07%2F13%2Fyourself-truly-by-emma%2F&for=wpcom-auto-discovery" />