はてなブログoEmbed API
概要
本ドキュメントは、はてなブログにおけるoEmbed実装を解説するものです。
oEmbedとは
oEmbedは、Webサイトにさまざまなコンテンツを埋め込むための仕組みで、各Webサービスのプロパイダによって提供されます。現在、はてなでは、はてなブログの各記事をoEmbedを用いて埋め込むことが可能です。oEmbedの詳細についてはoembed.com(英語)をご覧ください。
詳細説明
エンドポイント
エンドポイントは以下に定義しています。
https://hatena.blog/oembed
このエンドポイントにいくつかのパラメータを加えてGETリクエストを送ることで、JSON形式もしくはXML形式でデータを取得することができます。エンコーディングはUTF-8です。
| パラメータ | デフォルト | 解説 |
|---|---|---|
| url | - | 参照したい記事のパーマリンクを指定する |
| format | json | (オプション) データの形式を指定する(jsonもしくはxml) |
なお、ブログの公開範囲が「すべての人に公開」に設定されている記事についてのみ、データを取得できます。プライベートなブログなどに対して、情報を参照することはできません。
リクエスト(JSON)
$ curl -X GET 'https://hatena.blog/oembed?url=https%3A%2F%2Fstaff.hatenablog.com%2Fentry%2F2014%2F08%2F29%2F141633&format=json'
レスポンス(JSON)
{
"author_name": "hatenablog",
"author_url": "https://blog.hatena.ne.jp/hatenablog/",
"blog_title": "はてなブログ開発ブログ",
"blog_url": "https://staff.hatenablog.com/",
"categories": [
"新機能",
"news",
"はてな記法"
],
"description": "はてなブログでは、さまざまなコンテンツを貼り付けできる「リンク挿入」機能を強化し、はてなブログの記事を簡単に、きれいに整った体裁で貼り付けることができるようにしました。はてなブログで運営されているブログを紹介したり記事に言及する際に、この 記事貼り付け 機能を利用すると、記事タイトルや、本文の概要、アイキャッチ画像などがコンパクトにまとまった ブログカード 形式で、次のように貼り付けることができます。あわせて、自分がこれまでに投稿した記事を簡単に挿入できるように、そのブログの「過去記事貼り付け」機能を、編集サイドバーに追加しました。 ※「記事貼り付け」できるのは、はてなブログの記事だけです。 …",
"height": "190",
"html": "<iframe src=\"https://hatenablog-parts.com/embed?url=https%3A%2F%2Fstaff.hatenablog.com%2Fentry%2F2014%2F08%2F29%2F141633\" title=\"はてなブログの記事を紹介しやすくしました。URLを貼るだけで、コンパクトに整ったブログカードを貼り付けることができます【追記あり】 - はてなブログ開発ブログ\" class=\"embed-card embed-blogcard\" scrolling=\"no\" frameborder=\"0\" style=\"display: block; width: 100%; height: 190px; max-width: 500px; margin: 10px 0px;\"></iframe>",
"image_url": "http://f.st-hatena.com/images/fotolife/h/hatenablog/20140828/20140828171008_original.png",
"provider_name": "Hatena Blog",
"provider_url": "https://hatena.blog",
"published": "2014-08-29 14:16:33",
"title": "はてなブログの記事を紹介しやすくしました。URLを貼るだけで、コンパクトに整ったブログカードを貼り付けることができます【追記あり】",
"type": "rich",
"url": "https://staff.hatenablog.com/entry/2014/08/29/141633",
"version": "1.0",
"width": "100%"
}
リクエスト(XML)
$ curl -X GET 'https://hatena.blog/oembed?url=https%3A%2F%2Fstaff.hatenablog.com%2Fentry%2F2014%2F08%2F29%2F141633&format=xml'
レスポンス(XML)
<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<oembed>
<author_name>hatenablog</author_name>
<author_url>https://blog.hatena.ne.jp/hatenablog/</author_url>
<blog_title>はてなブログ開発ブログ</blog_title>
<blog_url>https://staff.hatenablog.com/</blog_url>
<categories>
<anon>新機能</anon>
<anon>news</anon>
<anon>はてな記法</anon>
</categories>
<description>は てなブログでは、さまざまなコンテンツを貼り付けできる「リンク挿入」機能を強化し、はてなブログの記事を簡単に、きれいに整った体裁で貼り付けることができるようにしました。はてなブログで運営されているブログを紹介したり記事に言及する際に、この 記事貼り付け 機能を利用すると、記事タイトルや、本文の概要、アイキャッチ画像などがコンパクトにまとまった ブログカード 形式で、次のように貼り付けることができます。あわせて、自分がこれまでに投稿した記事を簡単に挿入できるように、そのブログの「過去記事貼り付け」機能を、編集サイドバーに追加しました。 ※「記事貼り付け」できるのは、はてなブログの記事だけです。 …</description>
<height>190</height>
<html><iframe src="https://hatenablog-parts.com/embed?url=https%3A%2F%2Fstaff.hatenablog.com%2Fentry%2F2014%2F08%2F29%2F141633" title="はてなブログの記事を紹介しやすくしました。URLを貼るだけで、コンパクトに整ったブログカードを貼り付けることができます【追記あり】 - はてなブログ開発ブログ" class="embed-card embed-blogcard" scrolling="no" frameborder="0" style="display: block; width: 100%; height: 190px; max-width: 500px; margin: 10px 0px;"></iframe></html>
<image_url>http://f.st-hatena.com/images/fotolife/h/hatenablog/20140828/20140828171008_original.png</image_url>
<provider_name>Hatena Blog</provider_name>
<provider_url>https://hatena.blog</provider_url>
<published>2014-08-29 14:16:33</published>
<title>はてなブログの記事を紹介しやすくしました。URLを貼るだけで、コンパクトに整ったブログカードを貼り付けることができます【追記あり】</title>
<type>rich</type>
<url>https://staff.hatenablog.com/entry/2014/08/29/141633</url>
<version>1.0</version>
<width>100%</width>
</oembed>
エラー
間違ったリクエストや閲覧権限がない場合、APIがエラーを返すことがあります。
| エラーコード | 主なエラー |
|---|---|
| 404 | 記事やブログが見つからない |
| 401 | ブログの公開範囲が「すべての人に公開」ではない |
| 400 | 指定されたパラメータが正当でない |
Discovery
oEmbedの仕様では、head内にある要素を埋め込むことで、そのWebサイトがoEmbedに対応していることを示すことができます。はてなブログoEmbedもこの仕様に準拠しており、APIのエンドポイントをここから得ることもできます。具体的には以下の要素が埋め込まれています。
<link rel="alternate" type="application/json+oembed"
href="https://hatena.blog/oembed?url=http%3A%2F%2Fblog.hatenablog.com%2Fentry%2Fabout&format=json"
title="oEmbed Profile of 「週刊はてなブログ」について" />
<link rel="alternate" type="text/xml+oembed"
href="https://hatena.blog/oembed?url=http%3A%2F%2Fblog.hatenablog.com%2Fentry%2Fabout&format=xml"
title="oEmbed Profile of 「週刊はてなブログ」について" />
参考文章
- oembed.com(英語)
変更履歴
- 2014年9月3日 リリース
- 2020年11月10日 指定されたパラメータが正当でない場合のエラーコードを501から400に変更
- 2024年3月12日 APIの提供ドメインを
hatenablog.comからhatena.blogに変更