GET statuses/oembed

Updated on Wed, 2013-10-09 14:42

Returns information allowing the creation of an embedded representation of a Tweet on third party sites. See the oEmbed specification for information about the response format.

While this endpoint allows a bit of customization for the final appearance of the embedded Tweet, be aware that the appearance of the rendered Tweet may change over time to be consistent with Twitter's Developer Display Requirements. Do not rely on any class or id parameters to stay constant in the returned markup.

Please note: Unlike the remainder of API v1, this OEmbed method will survive post-retirement. Implementors would be wise to handle HTTP 302 redirects, as our official "v1" OEmbed endpoint will eventually migrate to a new path. Authentication is not required to use our OEmbed method but it is recommended for more predictable rate limiting.

Resource URL

https://api.twitter.com/1/statuses/oembed.format

Parameters

Either the id or url parameters must be specified in a request. It is not necessary to include both.

id required

The Tweet/status ID to return embed code for.

Example Values: 99530515043983360

url required

The URL of the Tweet/status to be embedded.

Example Values:

To embed the Tweet at https://twitter.com/#!/twitter/status/99530515043983360, use:

https%3A%2F%2Ftwitter.com%2F%23!%2Ftwitter%2Fstatus%2F99530515043983360

To embed the Tweet at https://twitter.com/twitter/status/99530515043983360, use:

https%3A%2F%2Ftwitter.com%2Ftwitter%2Fstatus%2F99530515043983360
maxwidth

The maximum width in pixels that the embed should be rendered at. This value is constrained to be between 250 and 550 pixels.

Note that Twitter does not support the oEmbed maxheight parameter. Tweets are fundamentally text, and are therefore of unpredictable height that cannot be scaled like an image or video. Relatedly, the oEmbed response will not provide a value for height. Implementations that need consistent heights for Tweets should refer to the hide_thread and hide_media parameters below.

Example Values: 325

hide_media

Specifies whether the embedded Tweet should automatically expand images which were uploaded via POST statuses/update_with_media. When set to either true, t or 1 images will not be expanded. Defaults to false.

Example Values: true

hide_thread

Specifies whether the embedded Tweet should automatically show the original message in the case that the embedded Tweet is a reply. When set to either true, t or 1 the original Tweet will not be shown. Defaults to false.

Example Values: true

omit_script

Specifies whether the embedded Tweet HTML should include a <script> element pointing to widgets.js. In cases where a page already includes widgets.js, setting this value to true will prevent a redundant script element from being included. When set to either true, t or 1 the <script> element will not be included in the embed HTML, meaning that pages must include a reference to widgets.js manually. Defaults to false.

Example Values: true

align

Specifies whether the embedded Tweet should be left aligned, right aligned, or centered in the page. Valid values are left, right, center, and none. Defaults to none, meaning no alignment styles are specified for the Tweet.

Example Values: center

related

A value for the TWT related parameter, as described in Web Intents. This value will be forwarded to all Web Intents calls.

Example Values: 

twitterapi,twittermedia,twitter
lang

Language code for the rendered embed. This will affect the text and localization of the rendered HTML.

Example Values: fr

Example Request

GET

https://api.twitter.com/1/statuses/oembed.json?id=99530515043983360 

  1. {
  2.   "type":"rich",
  3.   "width":550,
  4.   "cache_age":"31536000000",
  5.   "height":null,
  6.   "author_url":"https:\/\/twitter.com\/twitterapi",
  7.   "html":"\u003Cblockquote class=\"twitter-tweet\"\u003E\u003Cp\u003ENew fields arrive today for Search API responses: from_user_name and to_user_name. @\u003Ca href=\"https:\/\/twitter.com\/kurrik\"\u003Ekurrik\u003C\/a\u003E explains: \u003Ca href=\"http:\/\/t.co\/HqzmL0hZ\" title=\"https:\/\/dev.twitter.com\/discussions\/3667\"\u003Edev.twitter.com\/discussions\/36\u2026\u003C\/a\u003E ^TS\u003C\/p\u003E&mdash; Twitter API (@twitterapi) \u003Ca href=\"https:\/\/twitter.com\/twitterapi\/status\/136541709390708736\" data-datetime=\"2011-11-15T20:30:55+00:00\"\u003ENovember 15, 2011\u003C\/a\u003E\u003C\/blockquote\u003E\n\u003Cscript src=\"\/\/platform.twitter.com\/widgets.js\" charset=\"utf-8\"\u003E\u003C\/script\u003E",
  8.   "version":"1.0",
  9.   "provider_name":"Twitter",
  10.   "provider_url":"http:\/\/twitter.com",
  11.   "url":"https:\/\/twitter.com\/twitterapi\/status\/136541709390708736",
  12.   "author_name":"Twitter API"
  13. }