Hatena::Grouphatenadeveloper

はてなスター取得 API

ja/star/apis/entry

はてなスター取得 API

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

本ドキュメントははてなスターの取得を行う API について解説するものです。

■ はてなスター取得 API の概要

はてなスター取得 API は HTTP の GET を特定の URL に対して行うことで、ある URL に対して付与されたスターを取得できる REST API です。

■ 認証

認証は不要です。公開されたスターのみ取得できます。

■ スター取得 (/entry.json)

ある URL に付与されたスターの一覧は、

http://s.hatena.com/entry.json

... に対して HTTP GET メソッドによりアクセスすることで取得できます。

HTTP 要求に含める引数

HTTP 要求には application/x-www-form-urlencoded 形式で次の引数を含めることができます。

引数名 引数値 個数
uri スターを取得する URL (scheme が http または https であるもの) 0個以上

URL は、構文解析してから文字列化しても変化しない (つまり正準化済みの) 絶対URL でなければなりません。

HTTP 応答

取得に失敗しなかった場合、 200 (OK) などの成功を表す応答が返されます。 HTTP 応答の本体は次のような JSON オブジェクトとなります。

  • entries 次のようなオブジェクトを零個以上含む配列
    • uri URL
    • stars 次のようなオブジェクトを零個以上含む配列で、当該 URL に付与された黄色のスターを表す
      • name スターをつけたユーザーのはてなID
      • quote スターの引用文 (無ければ空文字列)
      • count スターの個数を表す数値 (1個のときは省略されることがある)
    • colored_stars 次のようなオブジェクトを零個以上含む配列 (カラースターが付与されていなければ省略)
      • color スターの色 (green, red, blue など)
      • stars 黄色のスター同様の形式のオブジェクトを零個以上含む配列で、カラースターを表す

取得に失敗した場合、 400 (Bad Request)、 401 (Authorization Required) などの HTTP 応答か、エラーメッセージを含んだ JSON データの 200 (OK) 応答が返されます。

例

GET /entry.json?uri=http%3A%2F%2Fwww.example.com%2F&uri=http%3A%2F%2Fwww.example.com%2Fnotfound&uri=http%3A%2F%2Fwww.example.net%2F HTTP/1.1
Host: s.hatena.com
User-Agent: ExampleUserAgent/1.0


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

{
  "entries": [
    {
      "uri": "http://www.example.com/",
      "stars": [
        {
          "name": "sample",
          "quote": ""
        },
        {
          "name": "sample",
          "quote": ""
        }
      ],
      "colored_stars": [
        {
          "color": "purple",
          "stars": [
            {
              "name": "hatenastar",
              "quote": "Hello",
              "count": 2
            }
          ]
        }
      ]
    }
    {
      "uri": "http://www.example.net/",
      "stars": [
        {
          "name": "hatenahaiku",
          "quote": ""
        }
      ]
    }
  ]
}

■ 変更履歴

  • 2013年4月11日 API 仕様を公開