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

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

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

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

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

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

認証

本 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 応答

例

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`	対象ユーザーがこのユーザーにともだち申請している

変更履歴

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

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

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