Annictは、APIとWebサイトに短い時間で送れるリクエストの数に上限を設けています。
多くの方に安定してAnnictを使っていただくための制限です。
このページでは、上限の値と数え方、上限を超えたときの応答、たくさんのデータを取得するときのお願いをまとめています。
上限の値
上限は1分ごとの区切り (毎分0秒から59秒まで) で数えます。
区切りが変わると、数えた件数は0に戻ります。
| 対象 | 数える単位 | 上限 |
|---|---|---|
API (https://api.annict.com)。アクセストークンあり |
アクセストークンと接続元IPの組 | 1分あたり600 |
API (https://api.annict.com)。アクセストークンなし |
接続元IP | 1分あたり60 |
Webサイト (https://annict.com) |
接続元IP | 1分あたり300 |
APIの上限は、GraphQL API・REST API V1・OAuthのエンドポイント (/oauth/token など) のどれに送ったリクエストも合わせて数えます。
GraphQL APIは、1回のリクエストで取得する量にかかわらず1件と数えます。
Webサイトの上限は、ページの表示に加えて、ページを開いたときに画面が裏側で送るリクエストも数えます。
画像・CSS・JavaScriptなどの静的なファイルは数えません。
普通にWebサイトを見ているだけで上限に届くことはありません。
上限の値は見直すことがあります。
上限を下げるときは、このページとAnnictのお知らせで前もってお知らせします。
数え方
APIの数え方
アクセストークンを付けたリクエストは、アクセストークンと接続元IPの組ごとに数えます。
そのため、1つのアクセストークンを配布物に埋め込み、たくさんの端末から使うアプリケーションでは、端末ごとに (端末の接続元IPごとに) 別々に数えます。
利用者が増えても、1つのアクセストークンの上限をみんなで分け合うことにはなりません。
利用者ごとにOAuthでアクセストークンを発行するアプリケーションも、利用者ごとに別々に数えます。
反対に、自分のサーバーからまとめてデータを取得する場合は、リクエストがそのサーバーの1つのIPに集まります。
同じアクセストークンを使うリクエストは1つの組で数えるため、並列に送ると上限にすぐ届きます。
後で説明する「たくさんのデータを取得するとき」を参考に、取得を時間に分散してください。
アクセストークンは、Authorization ヘッダーと access_token パラメータのどちらで渡しても同じように数えます。
アクセストークンの渡し方はREST API V1の概要とGraphQL APIのセットアップを参照してください。
Webサイトの数え方
Webサイトは接続元IPごとに数えます。
ログインしているかどうかは関係ありません。
WebサイトからAPIで提供していない情報を機械的に取得する場合も、この上限の中で行ってください。
Webサイトの画面や構成は予告なく変わることがあり、機械的な取得が動き続けることは保証できません。
上限を超えたとき
上限を超えたリクエストには、ステータスコード429 (Too Many Requests) を返します。
次の区切りが始まるまで、同じ単位のリクエストは429になります。
429の応答には、次のリクエストを送れるようになるまでの秒数を Retry-After ヘッダーで付けます。
429を受け取ったら、Retry-After の秒数だけ待ってから再開してください。
APIの応答
APIは、上限に達する前から、すべての応答に残りの件数を示す次のヘッダーを付けます。
| ヘッダー | 意味 |
|---|---|
RateLimit-Limit |
今の区切りで送れるリクエストの上限 |
RateLimit-Remaining |
今の区切りで送れる残りのリクエスト数 |
RateLimit-Reset |
今の区切りが終わり、件数が0に戻るまでの秒数 |
RateLimit-Reset の値はUnix時刻ではなく、残りの秒数です。
Retry-After も含めて、これらのヘッダーはブラウザで動くアプリケーションのJavaScriptからも読めます。
上限を超えたときの応答の本文は、REST API V1のエラーと同じ形式のJSONです。
GraphQL APIに送ったリクエストでも同じ形式で返します。
HTTP/1.1 429 Too Many Requests
Content-Type: application/json; charset=utf-8
Retry-After: 18
RateLimit-Limit: 600
RateLimit-Remaining: 0
RateLimit-Reset: 18
{
"errors": [
{
"type": "rate_limit_exceeded",
"message": "リクエストが多すぎます。しばらく待ってからもう一度お試しください",
"developer_message": "レート制限を超えました。Retry-Afterヘッダーの秒数だけ待ってからリクエストしてください"
}
]
}
Webサイトの応答
Webサイトは、上限を超えたときに Retry-After ヘッダーを付けた429と、その旨を伝える簡単なページを返します。
残りの件数を示すヘッダーは付けません。
たくさんのデータを取得するとき
作品情報などをまとめて取得するときは、次の点に気をつけてください。
- リクエストは並列にせず、1件ずつ順番に送ってください
- リクエストの間隔を空け、1分あたりの件数が上限を下回るようにしてください。APIの残りの件数は
RateLimit-Remainingヘッダーで確かめられます - 429を受け取ったら、
Retry-Afterの秒数だけ待ってから再開してください - 全件の取得は一度に済ませず、数時間から数日に分けて少しずつ進めてください
- 取得したデータは手元に保存し、同じデータを何度も取得しないでください
- REST API V1では、1回のリクエストで取得する件数を
per_pageパラメータで最大の50件にすると、リクエストの数を減らせます
取得し直す頻度の目安
一度取得した作品情報は、次の頻度を目安に取得し直してください。
| 作品 | 取得し直す頻度の目安 |
|---|---|
| 放送中・放送前の作品 (今期・来期の作品) | 1日1回 |
| それ以外の作品 (放送が終わった作品など) | 週1回から月1回 |
放送中や放送前の作品は、話数や放送予定が変わりやすいため、こまめに取得し直すと最新の情報を反映できます。
放送が終わった作品の情報が変わることは多くありません。
連絡先が分かるようにする
機械的にリクエストを送るときは、User-Agent ヘッダーにアプリケーションの名前と連絡先 (WebサイトのURLやメールアドレス) を入れていただけると助かります。
負荷が高くなったときに、遮断する前にご連絡できることがあります。
上限を超え続ける場合
429を受け取っても間隔を空けずに送り続ける場合や、Annictの運営に支障が出る使い方をしている場合は、アクセストークンを失効させたり、接続元IPからのリクエストを遮断したりすることがあります。