はてなタイムラインエントリー一覧ネイティブ API
本ドキュメントに関する注意事項
本ドキュメントははてなのタイムラインのエントリー一覧を取得する API について解説するものです。本 API は実験的に公開しているものであり、API の仕様変更ならびに API の公開停止を予告なしに行う場合があります。また、開発者のみなさまのご意見を参考に、より利用しやすい API を将来的に追加することも検討しております。
はてなのタイムラインエントリー一覧ネイティブ API の概要
はてなのタイムラインエントリー一覧ネイティブ API は、 OAuth 認証を利用した REST API です。 HTTP の GET を特定の URL に対して行うことで、はてなのタイムラインのエントリーの一覧を、はてな内部での保存形式に近い形で取得することができます。
認証
本 API は OAuth によるユーザー認証に対応しています。 OAuth 認証の詳細に関しては、はてなのOAuthを利用する方法を参照してください。
タイムラインのエントリーの取得には read_private
操作の承認を得ている必要があります。
取得
タイムラインエントリー一覧の取得は
http://n.hatena.ne.jp/timeline.json
... に対して HTTP GET メソッドによりアクセスすることで行います。将来的に http から https に移行する可能性がございますので、ご注意ください。
HTTP 要求に含める引数
URL の query
部に application/x-www-form-urlencoded
形式で次の引数を指定することができます。
引数名 | 値 | 個数 |
---|---|---|
location | 取得するサービス | 0-1 |
page | 非推奨 ページ番号 | 0-1 |
per_page | 取得する最大の個数 | 0-1 (省略時は自動決定) |
reftime | 取得範囲の指定 | 0-1 (省略時は自動決定) |
取得できる範囲には制限があり、過去のすべてのエントリーを取得することはできません。
reftime
reftime
は、-1314803385,1
のように、符号、時刻、差分を順に指定した文字列です。符号は、+
がより新しいもの、-
がより古いものを取得することを表します。時刻と差分は基準点を表し、指定した時刻から差分の値だけ先にあるエントリーから順に取得します。時刻はいわゆる Unix 時刻形式を用います。 reftime
は常に指定することをおすすめします。最新のエントリーを取得したい時は、 -time,0
(time は現在時刻) を指定してください。
page
page
引数は取得する範囲をページ番号により指定できますが、使用するべきではありません。 location
を http://c.hatena.ne.jp/
と指定した場合 (または省略した場合)、 page
の既定値は 1
となります。それ以外の場合、 page
の既定値は指定なしとなります。 page
が指定されていると他の引数は無視されることがあります。
location
location
には、次のいずれかの値を指定できます。
値 | 説明 |
---|---|
http://c.hatena.ne.jp/ | はてなココ (ともだちの新着) |
http://h.hatena.ne.jp/ | はてなハイク (アンテナ) |
HTTP 応答
取得に成功した場合、 200 (OK) 応答が返されます。応答は次の章で説明する JSON 形式となっています。
取得に失敗した場合、 400 (Bad Request)、 401 (Authorization Required) などの HTTP 応答が返されます。
JSON データの形式
JSON は次の情報を含むオブジェクトとなっています。
名前 | 値の意味 | 値の種類 |
---|---|---|
has_next (page 引数指定時のみ) | 非推奨 次のページがあるか否か | boolean |
items | タイムラインに含まれるエントリーのリスト | 配列 |
newer_url (reftime 引数指定時のみ) | より新しいエントリーを取得するための URL | 文字列 |
older_url (reftime 引数指定時のみ) | より古いエントリーを取得するための URL | URL |
page (page 引数指定時のみ) | 非推奨 ページ番号 | 数値 |
エントリー
配列 items
の各要素はエントリーであり、次の情報を含むオブジェクトとなっています。
名前 | 値の意味 | 値の種類 |
---|---|---|
app_icon_url | アプリケーションアイコンの URL | URL |
app_logo_url | アプリケーションロゴの URL | URL |
app_name | アプリケーション名 | 文字列 |
app_url | アプリケーションの URL | 文字列 |
author | エントリーの著者 | 対象 |
body_diary_text | 本文テキスト (はてなダイアリー用はてな記法) | 文字列 |
body_haiku_text | 本文テキスト (はてなハイク用はてな記法) | 文字列 |
body_text | 本文テキスト | 文字列 |
created_on | 投稿日時 | 日時 |
data_category | エントリー種別 | 数値 |
eid | エントリーID (エントリー固有の数値) | 数値 |
entity1 | 廃止 関係者その1 | 対象 |
entity2 | 廃止 関係者その2 | 対象 |
mono_key | 品物ID | 英数字列 |
photo_url | 写真の URL | URL |
photo_small_url | 写真の縮小版の URL | URL |
question_summary_text | 質問文の要約 | 文字列 |
question_url | 質問ページの URL | URL |
reply_to_author | 親エントリーの著者 | 対象 |
reply_to_eid | 親エントリーのエントリーID | 数値 |
source_target | 投稿元アプリケーション | 対象 |
spot_review_score | スポットの評価点 | 数値 |
star_url | エントリーのパーマリンク URL | URL |
summary_text | 要約文 | 文字列 |
target | エントリーの言及対象 (イマココやレビューではスポット) | 対象 |
eid
, data_category
, created_on
, star_url
以外は値が存在しないために省略されていることがあります。
なお、今後上記以外の情報も予告なく追加することがあります。