Qiita APIを使って特定ユーザーの投稿記事を一括取得しようとした際、「途中までしか取得できない」「全件取得したはずなのに件数が足りない」「エラーで突然取得がストップする」といったトラブルに直面していませんか?
本記事ではQiita API v2の公式仕様に基づき、記事取得における範囲・限界・正しいページネーションおよびエラーハンドリングの実装手法を解説します。
結論
- 1リクエストあたりの取得上限は最大100件(
per_page=100)、指定可能なページ数は最大100ページ(page=100)であるため、単一の取得条件におけるAPIの取得限界は最大10,000件です。 - 特定ユーザーの記事一覧を取得するには
GET /api/v2/users/:user_id/itemsを使用し、レスポンスヘッダーに含まれるTotal-CountやLinkヘッダーを参照しながらループ処理(ページネーション)を行う必要があります。 - 未認証リクエストは1時間あたり60回、個人用アクセストークン(
read_qiitaスコープ等)を使用した認証リクエストは1時間あたり1,000回までに制限されます。API呼び出し時はステータスコード(401 / 403 / 429 など)とレート制限ヘッダーを適切にハンドリングすることが不可欠です。
なぜ「特定ユーザーの記事が抜けない」現象が発生するのか?主な原因と全体像
Qiita APIを使って特定ユーザーの記事一覧を取得しようとした際、期待通りのデータが全件取得できない原因の多くは、APIのデフォルト挙動やハード制限、あるいは認証設定の不足に起因します。
1. デフォルト取得件数(per_page)のトラップ
Qiita API v2のパラメータを指定せずにエンドポイントを呼び出すと、デフォルトで per_page=20(1ページあたり20件)が適用されます。そのため、ページネーションを行わずに単一のリクエストを送信した場合、ユーザーが100件の記事を投稿していても、最初の20件しか取得できません。
2. ページ数(page)の上限制限
API仕様上、page パラメータで指定できる値は 1 から 100 までと定められています。また、per_page パラメータの上限も 100 です。この積によって、1つのエンドポイントに対するリクエストで走査できるデータの上限は 100件 × 100ページ = 最大10,000件 に固定されています。
3. レート制限による途絶
Qiita APIには、サーバ負荷軽減とサービス品質維持のためにレート制限(Rate Limit)が設けられています。アクセストークンを付与しない未認証リクエストの場合、同一IPアドレスからのリクエストは 1時間に60回 に制限されます。ページネーションで連続リクエストを送信すると、数秒から数分でレート制限に達し、HTTPステータスコード 429 Too Many Requests が返却されて取得が中断します。
4. 記事の公開状態と権限(スコープ)の不足
他人の公開記事を取得する場合は特別なスコープは不要ですが、自分自身の非公開記事や限定共有記事、またはQiita Team内の記事を取得する場合は適切なアクセス権限(アクセストークンおよびスコープ)が必要です。適切なトークンを付与していない場合、それらの記事はレスポンスに含まれないか、401 Unauthorized / 403 Forbidden エラーが発生します。
Qiita API v2におけるページネーション仕様と取得上限
特定ユーザーの投稿記事を取得するための基本エンドポイントは GET /api/v2/users/:user_id/items です。また、検索条件を細かく指定する場合は GET /api/v2/items?query=user:user_id も利用できます。
どちらのエンドポイントも、大量のデータを一度に返却するのではなく、ページネーション(Pagination)方式を採用しています。
ページネーション関連のクエリパラメータ
| パラメータ名 | 設定可能範囲 | デフォルト値 | 説明 |
|---|---|---|---|
page |
1 ? 100 | 1 | 取得するページ番号を指定します。 |
per_page |
1 ? 100 | 20 | 1ページあたりに取得する要素数を指定します。 |
効率的に全件取得を行うためには、per_page=100 を指定して1リクエストあたりの取得件数を最大化し、page を 1, 2, 3 ... とカウントアップしながらリクエストを繰り返す必要があります。
レスポンスヘッダーによるメタ情報の取得
Qiita APIのレスポンスには、ページネーションを制御するための重要なHTTPヘッダーが含まれています。
-
Total-Countヘッダー
検索条件に一致するアイテムの総件数が格納されています。たとえばTotal-Count: 250であれば、per_page=100の場合、全3ページ(100件 + 100件 + 50件)で取得が完了することが計算できます。 -
Linkヘッダー
RFC 5988に準拠した形式で、最初(first)、前(prev)、次(next)、最後(last)のページヘのURL関係が提供されます。
Link: <https://qiita.com/api/v2/users/example_user/items?page=1&per_page=100>; rel="first",
<https://qiita.com/api/v2/users/example_user/items?page=1>; rel="prev",
<https://qiita.com/api/v2/users/example_user/items?page=3&per_page=100>; rel="next",
<https://qiita.com/api/v2/users/example_user/items?page=5&per_page=100>; rel="last"
Total-Count: 450
ページネーション・制限値仕様早見表
| 項目 | 仕様・制限値 | 注意点 |
|---|---|---|
| 1リクエスト最大件数 | 100件 (per_page=100) |
リクエスト時に明示的に指定しないとデフォルト20件になります。 |
| 最大ページ数 | 100ページ (page=100) |
page=101 以上を指定するとエラーまたは空データになります。 |
| 理論上の最大取得数 | 10,000件 | 単一検索条件での限界。超える場合は期間指定クエリ等で分割します。 |
| データ通信フォーマット | JSON | リクエストヘッダーに Accept: application/json を推奨します。 |
レート制限(Rate Limit)とHTTPステータスコードの仕様
Qiita APIを安全かつ確実に運用するためには、レート制限の仕組みと返却されるHTTPステータスコードの理解が欠かせません。
レート制限の区分と仕組み
Qiita APIのレート制限は、リクエストの認証状態によって大きく異なります。
-
未認証リクエスト(Non-authenticated)
- 制限: 1時間あたり 60回
- 識別基準: クライアントのIPアドレス単位
- 用途: 動作確認や小規模な試行向け。大量データの取得には不向きです。
-
認証済みリクエスト(Authenticated)
- 制限: 1時間あたり 1,000回
- 識別基準: アクセストークン単位
- 用途: ページネーションを用いた全件取得や定常スクリプト向け。
HTTPレスポンスヘッダーから、現在のレート制限状態をリアルタイムで確認できます。
-
Rate-Limit: 1時間あたりに許可される最大リクエスト数(60 または 1000) -
Rate-Remaining: 現在のウィンドウ内で残っているリクエスト可能回数 -
Rate-Reset: レート制限がリセットされる時刻(UNIXタイムスタンプ)
アクセストークンのスコープ(Scope)
API認証を行う場合、個人用アクセストークン(またはOAuth 2.0で発行されたトークン)を利用します。アクセストークンには用途に応じた4つのスコープが用意されています。
-
read_qiita: Qiita上の認証ユーザーに関連するデータの読み取りを許可 -
read_qiita_team: Qiita Team上のデータの読み取りを許可 -
write_qiita: Qiita上のデータの書き込み(投稿・更新・削除など)を許可 -
write_qiita_team: Qiita Team上のデータの書き込みを許可
特定ユーザーの公開記事を読み込むだけであれば read_qiita スコープを持つアクセストークンを準備し、HTTPヘッダーに次のように付与します。
Authorization: Bearer <アクセストークン>
主要なHTTPステータスコードとハンドリング方針
| ステータスコード | 名称 | 原因と発生シナリオ | 推奨するハンドリング処理 |
|---|---|---|---|
| 200 OK | 成功 | GETリクエストが正常に処理された。 | レスポンスボディのJSONをパースして取得処理を継続。 |
| 201 Created | 作成成功 | POSTによるリソース作成が成功した。 | 作成されたオブジェクトのID等を取得。 |
| 204 No Content | 処理成功(内容なし) | PUT / DELETEによる更新・削除が成功した。 | レスポンスボディは空のためパースせずに終了。 |
| 400 Bad Request | 不正なリクエスト | リクエストパラメータの形式エラーや不正な値。 | パラメータ構文・値の範囲(page や per_page など)を見直す。 |
| 401 Unauthorized | 認証エラー | アクセストークンが無効、または有効期限切れ。 | トークンの再発行、Authorization ヘッダーの設定確認。 |
| 403 Forbidden | 権限エラー | 必要なスコープがトークンに付与されていない。 | トークンのスコープ設定(read_qiita 等)を再確認して再生成。 |
| 404 Not Found | リソース未存在 | 指定した user_id や item_id が存在しない。 |
指定文字列のタイポ確認、ユーザーが存在するかチェック。 |
| 429 Too Many Requests | レート制限超過 | 1時間あたりのリクエスト制限を超過した。 |
Rate-Reset ヘッダーの時刻まで処理を待機(スリープ)させる。 |
| 500 Internal Server Error | サーバ内部エラー | Qiita側の障害や一時的なシステムエラー。 | 指数バックオフ(Exponential Backoff)で時間をおいて再試行。 |
実装例1:特定ユーザーの投稿記事を全件取得するPythonスクリプト
ここからはPythonの requests ライブラリを使用して、特定ユーザーの記事をページネーションによって全件取得する最小限の実装例を紹介します。
セキュリティ上のベストプラクティスに従い、アクセストークンはコード内にハードコードせず、環境変数 QIITA_TOKEN から読み込みます。
スクリプトの解説
- 対象エンドポイント:
https://qiita.com/api/v2/users/{user_id}/items -
per_page=100を指定してリクエスト回数を最小化します。 -
Total-Countヘッダーから総件数を取得し、取得すべき総ページ数を自動計算します。 -
pageを1から順に増加させて繰り返しリクエストを送信します。
import math
import os
import sys
import requests
def fetch_all_user_items(user_id: str):
# 環境変数からアクセストークンを取得
token = os.environ.get("QIITA_TOKEN")
headers = {
"Accept": "application/json"
}
if token:
headers["Authorization"] = f"Bearer {token}"
else:
print("警告: QIITA_TOKEN が設定されていないため、未認証リクエスト(制限: 60回/時)で実行します。")
base_url = f"https://qiita.com/api/v2/users/{user_id}/items"
per_page = 100
page = 1
all_items = []
# 第1ページの取得(総件数の確認のため)
params = {"page": page, "per_page": per_page}
response = requests.get(base_url, headers=headers, params=params)
# ステータスコードのチェック
print(f"Page {page} - Status Code: {response.status_code}")
if response.status_code != 200:
print(f"エラーが発生しました: Status {response.status_code}, Response: {response.text}")
return []
# レスポンスヘッダーから全件数を取得
total_count_str = response.headers.get("Total-Count")
if not total_count_str:
print("Total-Count ヘッダーが取得できませんでした。")
return response.json()
total_count = int(total_count_str)
total_pages = math.ceil(total_count / per_page)
print(f"ユーザー '{user_id}' の全記事数: {total_count} (全 {total_pages} ページ)")
items = response.json()
all_items.extend(items)
# 2ページ目以降のループ取得
for current_page in range(2, total_pages + 1):
if current_page > 100:
print("注意: Qiita APIの仕様上限(100ページ)に達したため、これ以上の自動取得はできません。")
break
params = {"page": current_page, "per_page": per_page}
res = requests.get(base_url, headers=headers, params=params)
print(f"Page {current_page} - Status Code: {res.status_code}")
if res.status_code == 200:
all_items.extend(res.json())
else:
print(f"Page {current_page} の取得に失敗しました: Status {res.status_code}")
break
return all_items
if __name__ == "__main__":
# 対象のQiitaユーザーIDを指定(例: 'qiita')
target_user = "qiita"
articles = fetch_all_user_items(target_user)
print(f"最終取得記事数: {len(articles)} 件")
実装例2:レート制限・エラーハンドリング(401/403/429)を考慮した堅牢な取得スクリプト
実用的なバッチ処理や大量データ取得スクリプトでは、レート制限超過(429)や認証エラー(401/403)への対応が不可欠です。
以下の実装例では、レスポンスヘッダー内の Rate-Remaining を常に監視し、リクエスト残数が少なくなった場合の自動スリープや、エラー発生時の適切な例外処理・ログ出力を組み込んでいます。
スクリプトの解説
-
Rate-Remainingが一定数以下になった場合、安全のためにウェイトを挿入します。 -
429 Too Many Requestsを検知した場合は、Rate-Resetの時刻まで自動的に一時停止します。 -
401 Unauthorizedまたは403 Forbiddenが返された場合は、トークン設定の問題を指摘して安全に中断します。
import os
import time
import math
import requests
def safe_fetch_user_items(user_id: str):
token = os.environ.get("QIITA_TOKEN")
if not token:
print("エラー: 環境変数 QIITA_TOKEN が設定されていません。アクセストークンを設定してください。")
return []
headers = {
"Authorization": f"Bearer {token}",
"Accept": "application/json"
}
base_url = f"https://qiita.com/api/v2/users/{user_id}/items"
per_page = 100
page = 1
collected_items = []
while True:
if page > 100:
print("警告: API仕様の最大ページ制限 (100ページ) に到達しました。処理を終了します。")
break
params = {"page": page, "per_page": per_page}
try:
response = requests.get(base_url, headers=headers, params=params, timeout=10)
except requests.exceptions.RequestException as e:
print(f"通信エラーが発生しました: {e}")
break
status_code = response.status_code
print(f"[Page {page}] Status Code: {status_code}")
# レート制限情報の取得
rate_limit = response.headers.get("Rate-Limit")
rate_remaining = response.headers.get("Rate-Remaining")
rate_reset = response.headers.get("Rate-Reset")
if rate_remaining is not None:
print(f" Rate Limit: {rate_remaining}/{rate_limit} remaining")
# HTTPステータスコードに応じた分岐処理
if status_code == 200:
items = response.json()
if not items:
# 取得データが空になったら終了
break
collected_items.extend(items)
# 総件数から全ページ数を判定(第1回リクエスト時)
total_count_str = response.headers.get("Total-Count")
if total_count_str and page == 1:
total_count = int(total_count_str)
total_pages = math.ceil(total_count / per_page)
print(f"対象ユーザー件数: {total_count} 件 (予定ページ数: {total_pages})")
# 次のページへ
page += 1
# レート制限残数が非常に少ない場合の予防的ウェイト
if rate_remaining is not None and int(rate_remaining) < 5:
print("レート制限の残数がわずかです。10秒間スリープします...")
time.sleep(10)
elif status_code == 401:
print("エラー (401 Unauthorized): アクセストークンが無効または期限切れです。QIITA_TOKEN を確認してください。")
break
elif status_code == 403:
print("エラー (403 Forbidden): リクエストに対する権限がありません。アクセストークンのスコープを確認してください。")
break
elif status_code == 429:
print("エラー (429 Too Many Requests): レート制限を超過しました。")
if rate_reset:
reset_timestamp = int(rate_reset)
wait_time = max(reset_timestamp - int(time.time()) + 1, 1)
print(f"リセット時刻まで {wait_time} 秒間待機します...")
time.sleep(wait_time)
# 再試行のため page はインクリメントしない
continue
else:
print("60秒間待機します...")
time.sleep(60)
continue
else:
print(f"予期しないステータスコードを受信しました: {status_code}")
print(f"Response Body: {response.text}")
break
return collected_items
if __name__ == "__main__":
user_id = "qiita"
results = safe_fetch_user_items(user_id)
print(f"取得完了: 合計 {len(results)} 件の記事データを取得しました。")
検索クエリを用いた迂回策とQiita APIの機能制限
特定ユーザーの投稿記事数が 10,000 件を超える場合、単一の GET /api/v2/users/:user_id/items 呼び出しでは上限制限(page=100, per_page=100)により全件を取得しきれません。このような極端な大量投稿データを扱う場合の迂回策と、仕様上の注意点を整理します。
10,000件の壁を突破する検索クエリ活用法
GET /api/v2/items エンドポイントでは query パラメータを使って高度な検索が可能です。投稿日時の範囲を絞り込むクエリ(created:>=YYYY-MM-DD や created:<=YYYY-MM-DD)とユーザー指定クエリ(user:user_id)を組み合わせることで、各検索結果の件数を10,000件以下に分割して全件を収集できます。
GET /api/v2/items?page=1&per_page=100&query=user:qiita+created:>=2023-01-01+created:<=2023-12-31
このように作成年や月ごとに絞り込むことで、10,000件制限を回避しつつ特定ユーザーのすべての過去記事を網羅的に抽出しやすくなります。
Qiita Team専用機能と個人向け機能の区別
Qiita API v2のエンドポイントには、一般のQiita(qiita.com)では使用できず、企業・法人向けの Qiita Team(*.qiita.com)専用となっている機能が多く存在します。
以下の機能は Qiita Team専用 であり、通常のQiita個人アカウントに対して実行しても利用できないか、期待通りの動作をしません。
-
グループ管理機能(
GET /api/v2/groups,POST /api/v2/groups等) -
テンプレート機能(
GET /api/v2/templates,POST /api/v2/expanded_templates等) -
絵文字リアクション機能(
POST /api/v2/items/:item_id/reactions,GET /api/v2/items/reactions等) -
チームアクセストークン発行(
POST /api/v2/team_access_tokens) -
SSO(シングルサインオン)認証フロー(
GET /api/v2/oauth/team_authorize)
廃止済みAPI・機能に関する注意点
古い技術ブログや過去のコード例を参照している場合、すでに廃止されたエンドポイントや機能が現役として紹介されていることがあるため注意が必要です。以下は公式仕様に基づき完全に廃止・変更された機能です。
-
Project機能(2022年10月1日 廃止)
GET /api/v2/projectsGET /api/v2/projects/:project_id/comments-
GET /api/v2/projects/:project_id/reactionsなどのProject関連エンドポイントはすべて廃止済みです。
-
Comment thank / Team Like機能(2020年11月4日 廃止)
PUT /api/v2/comments/:comment_id/thank-
DELETE /api/v2/comments/:comment_id/thankは廃止されています。
-
旧OAuthチーム認証ページ(2020年6月5日 廃止)
-
read_qiita_teamやwrite_qiita_teamスコープを含む場合のGET /api/v2/oauth/authorize利用は非推薦・廃止となり、代わりにGET /api/v2/oauth/team_authorizeを使用する仕様に変更されています。
-
認証ユーザー自身の非公開記事や下書きの取得
特定ユーザーが「自分自身」である場合、自身の限定共有記事や下書き状態に近い投稿データを一覧取得したいケースがあります。
その場合は GET /api/v2/authenticated_user/items を使用します。このエンドポイントには read_qiita スコープを持つアクセストークンが必須であり、認証されたユーザー本人の投稿アイテム一覧を取得することができます。
まとめ
Qiita API v2を用いて特定ユーザーの投稿記事一覧を確実に取得するためには、APIの構造的な仕様と制約を正しく理解し、プログラム側で適切に制御することが求められます。
-
取得件数の限界: 1リクエスト最大100件(
per_page=100)、最大100ページ(page=100)の仕様により、1つのクエリでの上限は最大10,000件です。大量投稿ユーザーの記事を抜く場合はcreated:クエリによる期間分割を検討してください。 -
ページネーションの必須実装: 単一リクエストではデフォルト20件しか取れません。
Total-Countヘッダーから総件数を計算し、ループ処理で全ページを取得する実装が必要です。 -
認証とレート制限の管理: 未認証(60回/時)ではすぐに制限に達するため、個人用アクセストークン(
Authorization: Bearer)を用いて認証リクエスト(1,000回/時)を行ってください。 -
エラーコードの適切なハンドリング:
401(トークン無効)、403(スコープ不足)、429(レート制限超過)などのステータスコードに応じた例外処理を組み込むことで、途中で止まらない堅牢なスクリプトが構築できます。
公式ドキュメントの仕様を遵守し、環境変数を使った安全なトークン管理とレスポンスヘッダーの監視を行いながら、Qiita APIのデータ収集・連携機能を活用してください。