Qiita APIでタグ指定の記事一覧を取得する際、エンドポイントのデフォルト順序やパラメータの仕様を正しく理解していないと、意図せず最新でない古い情報や偏ったデータを取得してしまう罠が存在します。
-
GET /api/v2/tags/:tag_id/itemsのデフォルト並び順は「投稿日時(created_at)の降順(新しい順)」であり、更新日時順や人気順ではない - いいね数(人気順)や柔軟な条件検索を行いたい場合は、
/api/v2/itemsエンドポイントにqueryやsortパラメータを指定する必要がある - ページネーション(
page,per_page)やレート制限(認証時1,000回/時)を考慮したリクエスト設計を行わないと、データ取得の漏れやエラー(429 Too Many Requests)の原因となる
Qiita APIにおけるタグ記事取得エンドポイントの罠とデフォルト挙動
Qiita API v2を利用して特定の技術タグが付けられた記事を収集する際、多くの方が最初に検討するのが GET /api/v2/tags/:tag_id/items エンドポイントです。しかし、このエンドポイントのレスポンス仕様とソート順に関するデフォルト挙動を正しく認識していない場合、データ分析や自動収集ツールで予期せぬトラブルを引き起こすことがあります。
GET /api/v2/tags/:tag_id/items が返す記事の一覧は、デフォルトで**「記事の作成日時(created_at)の降順(新しい順)」**に並んでいます。一見すると「最新記事が順番に取得できているから問題ない」と思われがちですが、以下のような落とし穴が存在します。
-
更新日時(updated_at)順ではない
Qiita上の記事は、過去に投稿されたものであっても内容が加筆修正(リライト)されることがあります。古い記事が最新の技術情報にアップデートされていたとしても、created_at(投稿日時)基準で取得していると、それらのリライト記事は一覧の後方に埋もれてしまいます。 -
人気順(いいね数・ストック数)ではない
Web UI上のQiitaのタグページでは「人気」「最新」などのタブ切り替えが可能ですが、GET /api/v2/tags/:tag_id/itemsエンドポイント単体ではソート順を「いいね順」に変更するパラメータが用意されていません。人気記事を取得しようとしてこのエンドポイントを無条件に叩くと、単に「直近に投稿された新規記事」だけを取得し続けることになります。 -
過去の特定期間のトレンドを拾えない
投稿日時の降順のみで取得すると、過去にバズった高品質な技術記事を見落とし、品質のばらつきがある最新記事ばかりを拾ってしまう可能性があります。
技術情報の収集やトレンド解析を目的として自動化スクリプトを作成する場合は、「自分が取得したいデータは投稿日時順の最新記事なのか、それとも評価が高い人気記事なのか」を明確に区別し、適切なエンドポイントを選択することが極めて重要です。
目的別!/tags/:tag_id/items と /items の使い分け比較
Qiita API v2において、特定タグの記事を取得する方法は主に2種類存在します。
一つは前述した GET /api/v2/tags/:tag_id/items であり、もう一つは汎用的な記事検索エンドポイントである GET /api/v2/items です。
どちらを使うべきかは、取得したいデータの目的によって明確に分かれます。両者の機能やパラメータの相違点を下表にまとめました。
エンドポイント仕様比較表
| 項目 | GET /api/v2/tags/:tag_id/items |
GET /api/v2/items |
|---|---|---|
| 主な用途 | 特定タグの最新投稿をシンプルに取得 | 複雑な検索条件指定、人気順(ソート)取得 |
| デフォルトの並び順 | 投稿日時(created_at)の降順 | 投稿日時(created_at)の降順 |
ソート変更 (sort) |
不可(固定) | 可能(例: sort=likes でいいね順ソート) |
検索クエリ (query) |
不可 | 可能(例: query=tag:Python stocks:>50) |
| ページネーション | 対応 (page, per_page) |
対応 (page, per_page) |
| 取得対象 | 指定した tag_id が付与された記事 |
検索条件にマッチする全記事 |
| 適用範囲 | パブリックデータ | パブリックデータ(Qiita Team除く) |
単に「Pythonタグが付けられた新着記事を20件取得したい」という場合は、GET /api/v2/tags/Python/items を利用するのが最もストレートで簡潔です。
一方で、「Pythonタグが付けられており、かつ一定以上の評価を得ている記事を取得したい」あるいは「特定のキーワードを本文に含むタグ記事を取得したい」といった場合は、GET /api/v2/items を使い、クエリパラメータ query=tag:Python や sort=likes を指定する必要があります。ここを混同して GET /api/v2/tags/:tag_id/items しか使っていないと、欲しい評価順のデータが得られず「古い記事ばかり取れてしまう」または「最新の低評価記事しか取れない」というミスマッチの原因になります。
ページネーション(page / per_page)と Link ヘッダーの正確な理解
API経由でデータを大量に取得する際、避けて通れないのが「ページネーション(Pagination)」の制御です。Qiita API v2におけるページネーションの仕様を誤解していると、意図せず特定の1ページ目(最新20件)のみを繰り返し取得してしまったり、全体データの一部しか取得できていないことに気づかないリスクがあります。
page と per_page の基本仕様
Qiita API v2 の一覧取得系エンドポイントでは、以下のクエリパラメータで取得範囲を制御します。
-
page: 取得するページ番号を指定します。指定可能な範囲は 1 ? 100(デフォルトは1)です。 -
per_page: 1ページあたりに取得する件数を指定します。指定可能な範囲は 1 ? 100(デフォルトは20)です。
1回のAPI呼び出しで取得できる最大件数は per_page=100 の100件までです。また、page パラメータの上限が 100 であるため、1つのリクエスト条件で辿れるのは最大で 100ページ × 100件 = 10,000件 までとなります。
レスポンスヘッダーに含まれるメタデータ
全データ件数や次のページの存在を確認するには、レスポンスの本文(JSON)ではなく、HTTPレスポンスヘッダーを参照します。
-
Total-Countヘッダー
検索条件に該当する全体の総記事数が整数値で入っています。(例:Total-Count: 1550) -
Linkヘッダー
前後のページや最初・最後のページへのURIが RFC 5988 形式で含まれます。
Link: <https://qiita.com/api/v2/items?page=1&per_page=20>; rel="first",
<https://qiita.com/api/v2/items?page=1&per_page=20>; rel="prev",
<https://qiita.com/api/v2/items?page=3&per_page=20>; rel="next",
<https://qiita.com/api/v2/items?page=100&per_page=20>; rel="last"
ループ処理を記述する際は、レスポンスの配列が空(len(items) == 0)になるか、Link ヘッダーに rel="next" が含まれなくなるまで page インクリメントを行う実装にすることで、全データの安全な走査が可能になります。
レート制限とスコープ設計:エラーハンドリングの基本
Qiita API v2 を安全かつ持続的に利用するためには、レート制限(Rate limit)、アクセストークンのスコープ設定、およびHTTPステータスコードに応じたエラー処理を正しく実装する必要があります。
レート制限(Rate Limit)のルール
APIに対する過剰なリクエストからサーバーを守るため、Qiita API v2 には呼び出し回数の上限が設けられています。
- 認証済みリクエスト(アクセストークン利用時): 1時間あたり 1,000回
- 未認証リクエスト(トークンなし): 1時間あたり 60回 (送信元IPアドレス単位でカウント)
未認証状態ではわずか60回のリクエストで制限に達してしまうため、自動化スクリプトやバッチ処理を作成する際は、必ず個人用アクセストークン(Personal Access Token)を発行し、リクエストヘッダーに含める必要があります。
現在の制限状態は、レスポンスヘッダーから確認できます。
-
Rate-Limit-Limit: 1時間あたりの上限回数(1000または60) -
Rate-Limit-Remaining: 現在のウィンドウで残っているリクエスト可能回数 -
Rate-Limit-Reset: レート制限がリセットされる時刻のUNIXタイムスタンプ
アクセストークンのスコープと利用権限
アクセストークンを発行する際、アプリケーションに必要な最小限の権限(スコープ)を付与します。Qiita API v2 のスコープは以下の4種類です。
| スコープ名 | 説明 | 適用対象 |
|---|---|---|
read_qiita |
認証ユーザーに関連するQiita上のデータの読み取り | Qiita (パブリック) |
read_qiita_team |
Qiita Team上のデータの読み取り | Qiita Team専用 |
write_qiita |
Qiita上での記事・コメント投稿や編集、いいね等 | Qiita (パブリック) |
write_qiita_team |
Qiita Team上での記事・コメント投稿や編集等 | Qiita Team専用 |
パブリックなQiitaの記事を参照・検索するだけであれば、read_qiita スコープを持つトークン、あるいは読み取り用権限で十分対応できます。
HTTPステータスコードと処理方針
Qiita API v2 から返される代表的なステータスコードと、プログラム側で取るべきハンドリング方針は以下の通りです。
| コード | 状態 | 原因と対処方針 |
|---|---|---|
| 200 OK | 成功 | GET, PATCHリクエストが正常に完了 |
| 201 Created | 成功 | POSTリクエストによりリソースが正常に作成された |
| 204 No Content | 成功 | PUT, DELETEリクエストが成功(レスポンスボディは空) |
| 400 Bad Request | クライアントエラー | パラメータの形式不備や必須項目の欠落。リクエスト内容を修正 |
| 401 Unauthorized | 認証エラー | アクセストークンが無効または未設定。Authorization ヘッダーを確認 |
| 402 / 403 Forbidden | 権限エラー | アクセストークンのスコープ不足、またはアクセス権限がないリソース |
| 404 Not Found | 未検出 | 存在しないエンドポイントや削除済みリソースへのアクセス |
| 429 Too Many Requests | レート制限超過 | 1時間の呼び出し上限を超過。Rate-Limit-Reset まで待機 |
| 500 Internal Server Error | サーバーエラー | Qiita側の障害。時間を置いてリトライ |
Team専用機能および廃止済みAPIについての注意事項
API実装時に注意すべき点として、Qiita Team専用エンドポイントの混在と、すでに廃止された旧機能の除外があります。
-
Team専用機能:
グループ管理(/api/v2/groups)、テンプレート展開(/api/v2/expanded_templates)、絵文字リアクション(/api/v2/comments/:id/reactions,/api/v2/items/:id/reactions)、記事リアクション一覧(/api/v2/items/reactions)、Team用アクセストークン(/api/v2/team_access_tokens)、SSO関連設定は、すべて Qiita Team専用 の機能です。通常のqiita.comに対するリクエストでは利用できません。 -
廃止済みAPI(使用禁止):
-
DELETE / PUT /api/v2/comments/:comment_id/thank(2020年11月4日廃止) - Project関連機能
/api/v2/projects/*全般 (2022年10月1日廃止)
これらは現在の公式仕様から削除されており、呼び出すとエラーになります。現役の機能として組み込まないよう注意してください。
-
Python(requests)による実装例1:特定タグの最新記事を安全に取得・制限確認する
ここからは Python の requests ライブラリを使用した具体的な実装コード例を紹介します。
1つ目の例は、GET /api/v2/tags/:tag_id/items エンドポイントを用いて、特定タグの最新記事を取得するコードです。環境変数 QIITA_TOKEN からアクセストークンを読み込み、レスポンスヘッダーからレート制限の残り回数を確認しながら安全にリクエストを行います。
import os
import sys
import requests
def fetch_latest_tag_items(tag_id: str, page: int = 1, per_page: int = 20):
# 環境変数からQiitaアクセストークンを取得
token = os.environ.get("QIITA_TOKEN")
# リクエストヘッダーの構築
headers = {
"Content-Type": "application/json"
}
if token:
headers["Authorization"] = f"Bearer {token}"
else:
print("[Warning] QIITA_TOKENが設定されていません。未認証(60回/時)で実行します。")
# APIエンドポイントのURL構築
url = f"https://qiita.com/api/v2/tags/{tag_id}/items"
params = {
"page": page,
"per_page": per_page
}
try:
response = requests.get(url, headers=headers, params=params, timeout=10)
# レート制限ヘッダーの確認
rate_remaining = response.headers.get("Rate-Limit-Remaining")
rate_limit = response.headers.get("Rate-Limit-Limit")
print(f"[API Status] レート制限残り: {rate_remaining} / {rate_limit}")
# ステータスコードに応じたハンドリング
if response.status_code == 200:
items = response.json()
print(f"[{tag_id}] タグの記事を {len(items)} 件取得しました(Page {page})。")
for item in items:
title = item.get("title")
created_at = item.get("created_at")
item_url = item.get("url")
print(f"- [{created_at}] {title} ({item_url})")
return items
elif response.status_code == 401:
print("[Error 401] アクセストークンが無効または期限切れです。")
elif response.status_code == 403:
print("[Error 403] アクセス権限がありません。スコープを確認してください。")
elif response.status_code == 429:
reset_time = response.headers.get("Rate-Limit-Reset")
print(f"[Error 429] レート制限に達しました。リセット時刻(UNIX): {reset_time}")
else:
print(f"[Error {response.status_code}] レスポンスエラー: {response.text}")
except requests.exceptions.RequestException as e:
print(f"[Exception] 通信エラーが発生しました: {e}")
return None
if __name__ == "__main__":
# Pythonタグの最新記事を取得
fetch_latest_tag_items(tag_id="Python", page=1, per_page=5)
このコードでは、Authorization: Bearer <TOKEN> による正しい認証ヘッダーの付与、および Rate-Limit-Remaining による残量モニタリングを組み込んでいます。401, 403, 429 などのエラーが発生した際も、プログラムが急停止せずに原因をログ出力する構成にしています。
Python(requests)による実装例2:検索クエリを使った人気順(いいね順)記事の取得とページネーション
2つ目の例は、「特定のタグが付いた記事を、人気順(いいね数順)で取得したい」場合の標準的な実装パターンです。
GET /api/v2/tags/:tag_id/items ではなく、汎用検索用の GET /api/v2/items エンドポイントを使用し、query=tag:Python および sort=likes を指定します。また、Total-Count ヘッダーと Link ヘッダーを解析しながら複数ページを取得するループ構造の例を示します。
import os
import requests
def fetch_popular_tag_items(tag_name: str, max_pages: int = 2, per_page: int = 10):
token = os.environ.get("QIITA_TOKEN")
if not token:
print("[Error] 人気順検索を実行するには QIITA_TOKEN の設定を推奨します。")
return
headers = {
"Authorization": f"Bearer {token}",
"Content-Type": "application/json"
}
# GET /api/v2/items を使用
url = "https://qiita.com/api/v2/items"
current_page = 1
total_fetched = 0
while current_page <= max_pages:
# タグ指定といいね順ソートをクエリパラメータに設定
params = {
"query": f"tag:{tag_name}",
"sort": "likes",
"page": current_page,
"per_page": per_page
}
try:
response = requests.get(url, headers=headers, params=params, timeout=10)
# 制限ヘッダーの取得
remaining = response.headers.get("Rate-Limit-Remaining")
total_count = response.headers.get("Total-Count")
print(f"--- Page {current_page} (全該当件数: {total_count}, 残数: {remaining}) ---")
if response.status_code == 200:
items = response.json()
if not items:
print("該当するデータがこれ以上ありません。")
break
for item in items:
title = item.get("title")
likes = item.get("likes_count")
created_at = item.get("created_at")
item_url = item.get("url")
print(f"★ Likes: {likes:4d} | [{created_at[:10]}] {title}")
print(f" URL: {item_url}")
total_fetched += len(items)
# レスポンスヘッダーの Link から次ページの有無を確認
link_header = response.headers.get("Link", "")
if 'rel="next"' not in link_header:
print("最終ページに到達しました。")
break
current_page += 1
elif response.status_code == 429:
print("[Error 429] レート制限を超過しました。リクエストを中断します。")
break
else:
print(f"[Error {response.status_code}] リクエスト失敗: {response.text}")
break
except requests.exceptions.RequestException as e:
print(f"[Exception] リクエスト通信エラー: {e}")
break
print(f"\n合計 {total_fetched} 件の人気記事データを取得完了しました。")
if __name__ == "__main__":
# Pythonタグの人気記事を2ページ分取得
fetch_popular_tag_items(tag_name="Python", max_pages=2, per_page=5)
このスクリプトにより、投稿日時の最新順ではなく、コミュニティで高い評価を得ている「本当に参考にすべき人気記事」を正確に並べて取得できるようになります。
まとめ
Qiita API v2 を使ってタグに関連する記事データを収集・分析する際は、エンドポイントの選択とパラメータの組み合わせに関する深い理解が不可欠です。
-
GET /api/v2/tags/:tag_id/itemsは、投稿日時(created_at)の降順で新着記事を取得したい場合に適している - いいね数順(人気順)などで記事を取得したい場合は、
GET /api/v2/itemsにquery=tag:<タグ名>とsort=likesを指定する - ページネーション処理では
page(1?100)とper_page(1?100)を正しく管理し、Total-CountやLinkヘッダーを活用して取得漏れを防ぐ - レート制限(認証時1,000回/時、未認証時60回/時)を超過しないよう、
Rate-Limit-Remainingを監視し、環境変数QIITA_TOKENを用いた認証リクエストを基本とする - Qiita Team専用のエンドポイントや、すでに廃止された旧機能(Project関連機能やcomment thank機能など)を混同しない
APIの公式仕様に沿った適切なリクエスト設計を行い、目的に応じた正確なデータ取得ロジックを構築しましょう。