oEmbed API

oEmbed API は、oEmbed 互換形式でシンプルな埋め込み用 HTML を返します。

oEmbed API を使用すると、プログラムで埋め込みコンテンツを取得できます。たとえば、ツイート や タイムライン などです。 

oEmbed API からのレスポンスは、HTML スニペットを返します。このスニペットは、ページに X の widget JavaScript が読み込まれている場合、自動的に認識されます。

この API は一括処理での利用を推奨しており、コンテンツを埋め込む際には、堅牢なツールである publish.x.com の使用をお勧めします。

埋め込みタイムライン

返される HTML スニペットは、ページに X のウィジェット JavaScript が含まれている場合、自動的に埋め込みタイムラインとして認識されます。

oEmbed エンドポイントでは、HTML レスポンスに同梱される X の JavaScript によって解釈される HTML マークアップ内の対応するプロパティを設定することで、埋め込みタイムラインの最終的な外観をカスタマイズできます。返されるマークアップの形式は、X が新機能を追加したりタイムラインの表現を調整したりするに従って、時間とともに変更される可能性があります。

タイムライン URL で指定された X タイムラインを対象に、oEmbed 互換の JSON 形式で返します。ユーザータイムラインとリストタイムラインがサポートされています。タイムラインのマークアップは、cache_age プロパティで指定された推奨キャッシュ有効期間まで、自身のサーバー上でキャッシュすることを想定しています。

Resource URL

https://publish.x.com/oembed

Resource Information

Response formats	JSON
Requires authentication?	No
Rate limited	No

Parameters

Name	Description	Example
url	埋め込む対象となる X タイムラインの URL	* https://x.com/TwitterDev *https://x.com/TwitterDev/lists/national-parks
limit	表示する項目数 N を指定します。N は 1 以上 20 以下の値である必要があります	6
maxwidth	ウィジェットの最大幅を設定します。180 以上 1200 以下である必要があります	300
maxheight	ウィジェットの最大高さを設定します。200 より大きい必要があります	400
omit_script	レスポンスに script 要素を含めないようにします	1
lang	サポートされている X の言語コード	es
theme	dark を指定すると、タイムラインは暗い背景に明るい文字で表示されます	dark
chrome	スペース区切りのトークンでタイムラインの表示コンポーネントを削除します * noheader - ヘッダーを非表示にします * nofooter - 表示されている場合、フッターを非表示にします * noborders - ウィジェットの外枠、ツイート間、およびツイート内のすべての枠線を削除します * noscrollbar - 表示されている場合、タイムラインのスクロールバーを切り取って非表示にします * transparent - 背景色を削除します	noheader%20nofooter
aria_polite	タイムラインに追加されるツイートに対して、ARIA ライブリージョンのポライトネスの assertive 値を設定します	assertive
dnt	true に設定すると、タイムラインおよびあなたのサイト上に埋め込まれたページは、パーソナライズされたおすすめやパーソナライズされた広告などの目的には使用されません	true

Example Requests

curl --request GET --url 'https://publish.x.com/oembed?url=https%3A%2F%2Ftwitter.com%2FInterior%2Fstatus%2F507185938620219395'
twurl -H publish.x.com "/oembed?url=https://x.com/Interior/status/463440424141459456"

レスポンス例

{
  "url": "https://x.com/TwitterDev",
  "title": "",
  "html": "<a class=\"twitter-timeline\" href=\"https://x.com/TwitterDev\">Tweets by TwitterDev</a>\n<script async src=\"//platform.x.com/widgets.js\" charset=\"utf-8\"></script>",
  "width": null,
  "height": null,
  "type": "rich",
  "cache_age": "3153600000",
  "provider_name": "Twitter",
  "provider_url": "https://x.com",
  "version": "1.0"
}

埋め込みツイート

返されるHTMLスニペットは、XのウィジェットJavaScriptがページに含まれている場合、埋め込みツイートとして自動的に認識されます。

oEmbedエンドポイントでは、HTMLマークアップ内の対応するプロパティを設定することで、埋め込みツイートの最終的な表示をカスタマイズできます。これらのプロパティは、デフォルトでHTMLレスポンスにバンドルされているXのJavaScriptによって解釈されます。返されるマークアップの形式は、Xが新機能を追加したり、ツイートの表現を調整したりするにつれて、時間の経過とともに変更される可能性があります。

ツイートのフォールバックマークアップは、cache_ageプロパティで指定された推奨キャッシュ有効期間まで、お使いのサーバーにキャッシュすることを想定しています。

リソース URL

https://publish.x.com/oembed

リソース情報

レスポンス形式	JSON
認証が必要	いいえ
レート制限の対象	いいえ

パラメータ

名前	デフォルト	説明
url必須 文字列		埋め込むツイートのURL
maxwidth Int [220..550]	325	レンダリングされるツイートの最大幅 (ピクセル単位の整数) です。指定された値が許可された範囲を下回る、または上回る場合は、それぞれサポートされる最小または最大の幅として返されます。調整後の幅の値は、返される width プロパティに反映されます。なお、X は oEmbed の maxheight パラメータをサポートしていません。ツイートは本質的にテキストであり、高さは画像や動画のようにスケーリングできないため予測不能です。同様に、oEmbed レスポンスには height の値は含まれません。ツイートの高さを一定に保つ必要がある実装では、以下の hide_thread および hide_media パラメータを参照してください。
hide_media Boolean、String または Int	false	true、"t"、または 1 に設定した場合、ツイート内のリンクは写真、動画、またはリンクプレビューに展開されません。
hide_thread Boolean、String または Int	false	true、"t"、または 1 に設定すると、リクエストされたツイートが別のツイートへの返信である場合でも、その会話スレッド内の直前のツイートは折りたたみ表示されません。
omit_script Boolean, String または Int	false	true、"t"、1 のいずれかが指定された場合、widgets.js の読み込みを担当する <script> は返されません。すべての X ウィジェット (埋め込みツイート を含む) で使用できるように、widgets.js への参照を各 Web ページで別途記述しておく必要があります。
align Enum {left,right,center,none}	none	親要素内で、埋め込んだツイートを左寄せ・右寄せ・中央寄せのいずれに配置するかを指定します。
lang 列挙型 (Language)	en	リクエストにより、指定された埋め込みツイートでサポートされている X の言語による HTML とレンダリング済みツイートが返されます。
theme 列挙型 {light, dark}	light	dark に設定すると、ツイートは暗い背景に明るいテキストで表示されます。
dnt Boolean	false	true に設定すると、ツイートおよびあなたのサイトに埋め込まれたそのページは、パーソナライズされたおすすめ や パーソナライズされた広告 などの目的には利用されなくなります。

リクエスト例

curl --request GET --url 'https://publish.x.com/oembed?url=https%3A%2F%2Ftwitter.com%2Ftwiterdev'
twurl -H publish.x.com "/oembed?url=https://x.com/TwitterDev"

レスポンスの例

{
  "url": "https:\/\/twitter.com\/Interior\/status\/463440424141459456",
  "author_name": "米国内務省",
  "author_url": "https:\/\/twitter.com\/Interior",
  "html": "<blockquote class=\"twitter-tweet\"><p lang=\"en\" dir=\"ltr\">Sunsets don&#39;t get much better than this one over <a href=\"https:\/\/twitter.com\/GrandTetonNPS?ref_src=twsrc%5Etfw\">@GrandTetonNPS<\/a>. <a href=\"https:\/\/twitter.com\/hashtag\/nature?src=hash&amp;ref_src=twsrc%5Etfw\">#nature<\/a> <a href=\"https:\/\/twitter.com\/hashtag\/sunset?src=hash&amp;ref_src=twsrc%5Etfw\">#sunset<\/a> <a href=\"http:\/\/t.co\/YuKy2rcjyU\">pic.x.com\/YuKy2rcjyU<\/a><\/p>&mdash; US Department of the Interior (@Interior) <a href=\"https:\/\/twitter.com\/Interior\/status\/463440424141459456?ref_src=twsrc%5Etfw\">May 5, 2014<\/a><\/blockquote>\n<script async src=\"https:\/\/platform.x.com\/widgets.js\" charset=\"utf-8\"><\/script>\n",
  "width": 550,
  "height": null,
  "type": "rich",
  "cache_age": "3153600000",
  "provider_name": "Twitter",
  "provider_url": "https:\/\/twitter.com",
  "version": "1.0"
}