はてなブックマークAPIの活用: REST APIとjsonliteの違い・OAuth2認証フロー

2026年7月5日

Contents

1 REST APIとjsonliteエンドポイントの特徴と比較
- 1.1 用途に応じたエンドポイント選定ガイド
2 OAuth2.0認証フローとスコープの使い分け
- 2.1 read_publicとread_privateスコープの違い
- 2.2 アクセストークンの取得・更新フロー
3 ブックマーク取得APIのパラメータとフィルタリングオプション
- 3.1 URLパラメータの指定方法
- 3.2 フィルタリングオプションの活用
4 エラー処理とレート制限対策
- 4.1 404/400ステータスコードのハンドリング
- 4.2 API呼出頻度管理のベストプラクティス
5 実装例: PHP・Pythonでのコードサンプル
- 5.1 PHPでのクライアント実装
- 5.2 Pythonにおける非同期処理
6 旧エンドポイント廃止への対応と今後の展望
- 6.1 2020年3月以降の仕様変更点
- 6.2 移行時の注意事項
7 ブックマーク取得時のパラメータとフィルタリングの詳細
- 7.1 フィルタリングオプションの仕様確認
8 まとめ

スポンサードリンク

REST APIとjsonliteエンドポイントの特徴と比較

REST APIとjsonliteエンドポイントは共にJSON形式でデータを取得できますが、認証要件や利用可能な情報範囲に明確な違いがあります。以下に両者を比較した表を示します。

項目	REST API	jsonlite
認証要否	必須（OAuth2.0）	不要
データ形式	JSON	JSON
取得情報の範囲	ユーザー特定・カスタムフィルタリング可能	公開情報のみ
性能要件	高速な処理が必要な場合向け	軽量で即時取得が可能

用途に応じたエンドポイント選定ガイド

公開情報を取得する必要がある場合（例：Webサービスにおけるブックマーク数の可視化）: jsonliteを推奨します。
プライベートデータや詳細なフィルタリングが必要な場合（例：特定ユーザーのブックマークリスト生成）: REST APIを使用してください。

OAuth2.0認証フローとスコープの使い分け

OAuth2.0による認証は、REST API利用の前提です。read_publicとread_privateスコープの違いを理解し、用途に応じた実装が求められます。

read_publicとread_privateスコープの違い

read_publicスコープでは、公開されているブックマーク情報を取得できますが、ユーザーアカウントのプライベートデータはアクセスできません。一方、read_privateスコープは、認証ユーザー自身のブックマークを含む詳細な情報にアクセス可能です。

注意: read_privateスコープを利用するには、アプリケーション登録時に「個人情報の取り扱い」に関する承諾が必要です（Hatena Developer Centerを参照）。承諾後は、利用するデータが個人情報であることを明確に記載したプライバシーポリシーを作成し、ユーザーに提示することが義務付けられています。

アクセストークンの取得・更新フロー

Hatena Developer CenterでOAuth2.0クライアントを作成し、Client IDとClient Secretを取得します。
注意: Client Secretはアプリケーション設定画面で「暗号化保存」を選択し、セキュリティ上の理由から環境変数または暗号化ファイルに保存する必要があります（例: .envファイルやVaultなど）。
ユーザーに認可画面を表示し、アクセス許可を得ます（https://api.hatena.ne.jp/oauth2/authorize）。
アクセストークンを取得後、リフレッシュトークンを使用して自動更新を行います。

以下はPHPでのアクセストークン取得の例です（※一部省略）:

$postData = http_build_query([
    'client_id' =&gt; getenv('HATENA_CLIENT_ID'),
    'client_secret' =&gt; getenv('HATENA_CLIENT_SECRET'), // 暗号化された環境変数を使用
    'grant_type' =&gt; 'authorization_code',
    'code' =&gt; $authCode,
]);
$ch = curl_init('https://api.hatena.ne.jp/oauth2/token');
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $postData);
$response = json_decode(curl_exec($ch), true);

$postData = http_build_query([

'client_id' => getenv('HATENA_CLIENT_ID'),

'client_secret' => getenv('HATENA_CLIENT_SECRET'), // 暗号化された環境変数を使用

'grant_type' => 'authorization_code',

'code' => $authCode,

]);

$ch = curl_init('https://api.hatena.ne.jp/oauth2/token');

curl_setopt($ch, CURLOPT_POST, true);

curl_setopt($ch, CURLOPT_POSTFIELDS, $postData);

$response = json_decode(curl_exec($ch), true);

ブックマーク取得APIのパラメータとフィルタリングオプション

ブックマーク情報を取得する際は、URLパラメータを正しく指定することが不可欠です。

URLパラメータの指定方法

基本的なリクエスト構文:
GET https://api.b.hatena.ne.jp/1/bookmarks?user=ユーザー名&url=https%3A%2F%2Fexample.com

user: ブックマークを取得する対象のユーザー名（省略可）
url: 指定URLに対するブックマーク情報を取得（例: https://example.com）
format: jsonと指定することでJSONレスポンスを取得可能

フィルタリングオプションの活用

複数条件のAND/OR検索は、パラメータに&で連結します。例えば:

AND検索: url=https://example.com&category=tech
OR検索（※API非対応のため論理演算子は利用不可）: 特定条件を複数指定し、サーバーサイドで結果をフィルタリングします。

補足: OR検索の非対応については、Hatena APIの公式リファレンス（https://developer.hatena.ne.jp/ja/docs/entry/bookmark）と整合性を確認してください。現在の仕様では、urlやcategoryパラメータはAND条件として扱われます。

エラー処理とレート制限対策

API呼出時にエラーが発生する可能性を想定し、適切なハンドリングが必須です。

404/400ステータスコードのハンドリング

404 Not Found: 指定したURLにブックマークがない場合に返されます。この際は、UI上でのエラーメッセージ表示やログ出力が推奨されます。
400 Bad Request: URLエンコードミスや不正なパラメータ指定の可能性があります。リクエスト内容を検証し、再度実行させるロジックを組み込む必要があります。

API呼出頻度管理のベストプラクティス

Hatena APIにはレート制限（Rate Limiting）が適用されています。以下の対策を講じましょう:

クライアントサイドでのキャッシュ: 高頻度でアクセスするURLは、一定時間のキャッシュを活用します。
エキスパートなリトライロジック: 503エラーなど一時的な障害に対応するため、指数バックオフアルゴリズムを採用します。
非同期処理の導入: Pythonではasyncioやaiohttpを活用し、複数リクエストを並列処理することが可能です。

実装例: PHP・Pythonでのコードサンプル

API利用に際しては、言語ごとのライブラリ選定が重要です。以下にPHPとPythonの実装例を示します。

PHPでのクライアント実装

&lt;?php
$access_token = getenv('HATENA_ACCESS_TOKEN'); // 環境変数から取得
$url = 'https://api.b.hatena.ne.jp/1/bookmarks?url=https%3A%2F%2Fexample.com';

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    &quot;Authorization: Bearer $access_token&quot;
]);

$response = json_decode(curl_exec($ch), true);
if (isset($response['error'])) {
    // エラーハンドリング
    error_log(&quot;API Error: &quot; . $response['error']);
} else {
    // データ処理
}

<?php

$access_token = getenv('HATENA_ACCESS_TOKEN'); // 環境変数から取得

$url = 'https://api.b.hatena.ne.jp/1/bookmarks?url=https%3A%2F%2Fexample.com';

$ch = curl_init($url);

curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

curl_setopt($ch, CURLOPT_HTTPHEADER, [

"Authorization: Bearer $access_token"

]);

$response = json_decode(curl_exec($ch), true);

if (isset($response['error'])) {

// エラーハンドリング

error_log("API Error: " . $response['error']);

} else {

// データ処理

}

Pythonにおける非同期処理

Pythonではaiohttpライブラリを用いて非同期取得が可能です。以下はコード例です（※一部省略）:

import aiohttp

async def fetch_bookmarks(url, token):
    headers = {'Authorization': f'Bearer {token}'} # セキュリティ上、トークンは暗号化保存
    async with aiohttp.ClientSession() as session:
        async with session.get(f'https://api.b.hatena.ne.jp/1/bookmarks?url={url}', headers=headers) as resp:
            if resp.status == 200:
                return await resp.json()
            else:
                print(f&quot;Error: {resp.status}&quot;)

import aiohttp

async def fetch_bookmarks(url, token):

headers = {'Authorization': f'Bearer {token}'} # セキュリティ上、トークンは暗号化保存

async with aiohttp.ClientSession() as session:

async with session.get(f'https://api.b.hatena.ne.jp/1/bookmarks?url={url}', headers=headers) as resp:

if resp.status == 200:

return await resp.json()

else:

print(f"Error: {resp.status}")

旧エンドポイント廃止への対応と今後の展望

2020年3月以降、api.b.hatena.ne.jpの利用は可能ではなくなりました。最新API（api.hatena.ne.jp）への移行が必須です。

2020年3月以降の仕様変更点

URL変更: api.b.hatena.ne.jp/1/bookmarks → https://api.hatena.ne.jp/1/bookmarks
認証フローの強化: OAuth2.0の利用が必須となったため、アプリケーション登録が新たに求められます。

移行時の注意事項

クライアントライブラリの更新: 現行のライブラリが旧エンドポイントをサポートしていない場合があります。最新バージョンにアップグレードしてください（例: python-hatenaなど）。
テスト環境での確認: 本番環境に移行する前には、テスト用アカウントで動作確認を行うことが推奨されます。