Hatena::Grouphatenadeveloper

はてなのともだち情報取得 API

ja/nano/friends/lists

はてなのともだち情報取得 API

本ドキュメントに関する注意事項

本ドキュメントははてなの「ともだち」の情報を取得する API について解説するものです。

はてなのともだち情報取得 API の概要

はてなのともだち情報取得 API は、 OAuth 認証を利用した JSON API です。 HTTP の GET を特定の URL に対して行うことで、あるはてなユーザーの「ともだち」となっているユーザーのリストを取得することができます。

現在次の2つの API を提供しています。

認証

本 API は OAuth によるユーザー認証に対応しています。 OAuth 認証の詳細に関しては、はてなのOAuthを利用する方法を参照してください。

ともだち一覧の取得 (/USERNAME/friends.json) には read_public 操作、ともだち状態一覧の取得 (/fr/all.json) には read_private 操作の承認を得ている必要があります。

ともだち一覧の取得 (/USERNAME/friends.json)

ともだち一覧の取得は、

http://n.hatena.com/USERNAME/friends.json

... に対して HTTP GET メソッドによりアクセスすることで行います。ここで、 USERNAME は情報を取得したいユーザー (対象ユーザー) のはてなIDとします。将来的に http から https に移行する可能性がございますので、ご注意ください。

HTTP 要求に含める引数

URL の query 部分には name=value 形式で次の引数を含めることができます。

引数名引数値個数
with_annotations詳細情報を含めるなら "1"、含めないなら "0"1個まで (省略すると "0")

HTTP 応答

取得に成功した場合、後述の JSON 形式の 200 (OK) 応答が返されます。取得に失敗した場合、 400 (Bad Request)、 401 (Authorization Required) などの HTTP 応答が返されます。

GET /sample/friends.json HTTP/1.1
Host: n.hatena.com
Authorization: OAuth ...
User-Agent: ExampleUserAgent/1.0

HTTP/1.1 200 OK
Content-Type: aplication/json; charset=utf-8

{"items":[{"url_name":"hatenacoco","display_name":"はてなココ"}]}

ともだち状態一覧の取得 (/fr/all.json)

ともだち一覧の取得は、

http://n.hatena.com/fr/all.json

... に対して HTTP GET メソッドによりアクセスすることで行います。認証しているユーザーが一覧取得の対象ユーザーとなります。将来的に http から https に移行する可能性がございますので、ご注意ください。

HTTP 応答

取得に成功した場合、後述の JSON 形式の 200 (OK) 応答が返されます。取得に失敗した場合、 400 (Bad Request)、 401 (Authorization Required) などの HTTP 応答が返されます。

GET /fr/all.json HTTP/1.1
Host: n.hatena.com
Authorization: OAuth ...
User-Agent: ExampleUserAgent/1.0

HTTP/1.1 200 OK
Content-Type: aplication/json; charset=utf-8

{"items":[
    {"url_name":"hatenacoco","display_name":"はてなココ","relation_status":"friend"},
    {"url_name":"hatenahaiku","display_name":"はてなハイク","relation_status":"requesting"}
]}

JSON データの形式

JSON データは、 items という名前を持つ配列が含まれるオブジェクトとなっています。 items 配列の各要素がユーザーを表しています。

ユーザー

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

名前 値の意味 値の種類
url_name 識別子 (URL の一部として使われる記号列) 文字列
display_name ニックネーム 文字列
label対象ユーザーが記入したともだち関係の説明 (with_annotations が真の時のみ存在)文字列
relation_status 関係 (/fr/all.json のみ存在) 文字列

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

relation_status は、 ともだち状態一覧の取得 (/fr/all.json) でのみ含まれます。値は次のいずれかです。

friend対象ユーザーとこのユーザーはともだち
requested対象ユーザーはこのユーザーにともだち申請されている
requesting対象ユーザーがこのユーザーにともだち申請している

関連ドキュメント

はてなのともだち関係設定 API
ともだち申請やともだち状態の解除などが行えます。

変更履歴

  • 2010年12月13日 API 仕様を公開
  • 2012年10月1日 はてなハイク2の記述を削除