Hatena::Grouphatenadeveloper

はてなタイムラインエントリー一覧ネイティブ API

ja/nano/timeline/nativelist

はてなタイムラインエントリー一覧ネイティブ 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 は、 -1314803385,1 のように、符号、時刻、差分を順に指定した文字列です。符号は、 + がより新しいもの、 - がより古いものを取得することを表します。時刻と差分は基準点を表し、指定した時刻から差分の値だけ先にあるエントリーから順に取得します。時刻はいわゆる Unix 時刻形式を用います。 reftime は常に指定することをおすすめします。最新のエントリーを取得したい時は、 -time,0 (time は現在時刻) を指定してください。

非推奨 page 引数は取得する範囲をページ番号により指定できますが、使用するべきではありません。 locationhttp://c.hatena.ne.jp/ と指定した場合 (または省略した場合)、 page の既定値は 1 となります。それ以外の場合、 page の既定値は指定なしとなります。 page が指定されていると他の引数は無視されることがあります。

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 引数指定時のみ)より古いエントリーを取得するための URLURL
page (page 引数指定時のみ)非推奨 ページ番号数値

エントリー

配列 items の各要素はエントリーであり、次の情報を含むオブジェクトとなっています。

名前値の意味値の種類
app_icon_urlアプリケーションアイコンの URLURL
app_logo_urlアプリケーションロゴの URLURL
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写真の URLURL
photo_small_url写真の縮小版の URLURL
question_summary_text質問文の要約文字列
question_url質問ページの URLURL
reply_to_author親エントリーの著者対象
reply_to_eid親エントリーのエントリーID数値
source_target投稿元アプリケーション対象
spot_review_scoreスポットの評価点数値
star_urlエントリーのパーマリンク URLURL
summary_text要約文文字列
targetエントリーの言及対象 (イマココやレビューではスポット)対象

eid, data_category, created_on, star_url 以外は値が存在しないために省略されていることがあります。

なお、今後上記以外の情報も予告なく追加することがあります。

対象

authortarget 等は次の情報を含むオブジェクトとなっています。

名前値の意味値の種類
url_name識別子 (URL の一部として使われる記号列)文字列
display_nameニックネームやスポット名など表示用の名称文字列

url_name に「@」が含まれなければはてなユーザー (はてなID)、含まれればはてなユーザー以外です。

値が存在しないために省略されていることがあります。今後上記以外の情報も予告なく追加することがあります。

エントリー種別

data_category の値の意味は次の通りです。

意味
1コメント (旧形式)
2テキスト (はてなのユーザーに公開、旧形式)
3廃止 「ともだちになりました」通知
10はてなココのイマココ
11はてなココのスポットのレビュー
14テキスト (全体に公開、旧形式)
15テキスト (はてなハイク2ユーザーに公開、旧形式)
16テキスト (ともだちのともだちまで公開、旧形式)
17テキスト (ともだちに公開、旧形式)
19テキスト (指定した範囲のユーザーに公開)
20テキスト (ユーザーごとの公開範囲設定に基づき公開)
30はてなOneのコメント
31ハッピィの編集
43アプリケーション利用開始の通知
45はてなプラス利用開始の通知
50うごメモの作品
62はてなハイクの投稿
70人力検索はてなの回答への返答
75人力検索はてなの質問
76人力検索はてなの質問への回答
77人力検索はてなの質問へのコメント
78人力検索はてなのウォッチリストへの追加
79人力検索はてなのアンケート
80人力検索はてなのアンケートへの回答
85「ともだちになりました」通知
87はてなブックマークのブックマーク
89はてなフォトライフの写真・動画
95はてなココのイマココのコメント
97はてなブログの投稿
112はてなダイアリーの投稿

エントリー種別は予告なく追加することがあります。

その他

boolean は、偽を null0"0" のいずれか、真をそれ以外の値によって表します。

数値は、数値または数値を文字列化したものによって表します。

日時は、いわゆる Unix 時刻形式の数値によって表します。

GET /timeline.json?reftime=-1234567890,0 HTTP/1.1
Host: n.hatena.com
Authorization: OAuth ...
User-Agent: ExampleUserAgent/1.0

HTTP/1.1 200 OK
Content-Type: application/json

{
  "older_url": "http://...",
  "newer_url": "http://...",
  "items": [
    {
      "eid": "25152122414212111",
      "star_url": "http://n.hatena.ne.jp/...",
      ...
    },
    ...
  ]
}

関連ドキュメント

はてなタイムライン投稿 API
タイムラインにテキストや画像を投稿することができます。

変更履歴

  • 2010年12月13日 API 仕様を公開。
  • 2010年12月21日 「アプリケーション利用開始の通知」エントリーを追加、target について追記。
  • 2012年2月1日 新しい data_category 等について追記。
  • 2012年2月13日 新しい data_category 等について追記。
  • 2012年10月1日 はてなOneの記述を削除。