Search APIは他のREST APIとは回数制限の適用の仕方が異なるということ
自分の作ったTwitterのbotに『ほんのつぶやき (@honnotsubuyaki) | Twitter』というものがあり(最初の記事は多分これ)。
これは、『読んだ4!』のTwitterアカウントである @yonda4 宛のつぶやきを横から見て、その中にASIN/ISBNっぽいものが含まれている場合に、“『タイトル』作者 Amazonへのリンク”を返す、というものなのですが。
この、“@yonda4宛のつぶやきを横から見”るのには、Twitterの
search
Returns tweets that match a specified query.
http://apiwiki.twitter.com/Twitter-Search-API-Method%3A-search
を使っています。
これは『Twitter API プログラミング』の P.262にも有るとおり、
- API実行回数制限の適用対象。
- IPアドレス単位で制限がかかる。
- REST API(http://api.twitter.com/1/〜のエンドポイントをもつAPI)とは別枠でカウントされる。
ようです。
ただ、同書には
- 同一IPアドレスからの検索関連のAPIの実行は1時間あたり150回まで。
となっていますが、
Search API Rate Limiting
The Search API is rate limited by IP address. The number of search requests that originate from a given IP address are counted against the search rate limiter. The specific number of requests a client is able to make to the Search API for a given hour is not released. Note that the Search API is not limited by the same 150 requests per hour limit as the REST API. The number is quite a bit higher and we feel it is both liberal and sufficient for most applications. We do not give the exact number because we want to discourage unnecessary search usage.
http://apiwiki.twitter.com/Rate-limiting
とあるとおり、明確に1時間あたり何回まで、などという情報は公開されていない模様です。
An application that exceeds the rate limitations of the Search API will receive HTTP 420 response codes to requests. It is a best practice to watch for this error condition and honor the Retry-After header that instructs the application when it is safe to continue. The Retry-After header's value is the number of seconds your application should wait before submitting another query (for example: Retry-After: 67).
http://apiwiki.twitter.com/Rate-limiting
のように、Search APIはレート制限による失敗時にはHTTP Response Codeに420が返り(実際、これまで『ほんのつぶやき』は5分毎にAPIを発行するようにしていたのですが、しばしば420が返ってきていました)、きちんとするなら、ヘッダの"Retry-After"を見て、その数値秒あとでリトライする、というのが正しい使い方のようです。
ちなみに、通常の REST API を叩いた時には、ヘッダで返される“x-ratelimit-〜"(〜はclass、limit、remaining、reset)という名称の値は Search API では返されません(Whitelistingについても、別枠で処理されている感じですね)。
そんなわけで、せっかく OAuth 化したのに、例えば制限が 150→350 に変わるといった旨味は、今回はないみたい、と思った次第。
ところがですね…
通常のSearch API(search/trends)のエンドポイントは、
http://search.twitter.com/<span style="font-weight:bold;font-style:italic;">種別</span>.<span style="font-weight:bold;font-style:italic;">format</span>
種別は、search、trends、trends/current、など。formatは、json, atom
なんですが、これ、エンドポイントを、
http://api.twitter.com/1/<span style="font-weight:bold;font-style:italic;">種別</span>.<span style="font-weight:bold;font-style:italic;">format</span>
に変えても、動くんですよ。
応答ヘッダには“x-ratelimit-〜"がのってきており、実際、その範囲内であれば、通常のSearch APIの制限に縛られず、コール出来るっぽい、という。
確かに『Twitter API プログラミング』の P.7には、
(将来的には、検索関連のAPIもREST APIに統合される予定です)
という記述があり、期待はしていましたが、まさか既に実現されているとは。
とはいえ、API仕様上はまだこのことに言及されている気配が無いので、現段階ではまだ密かに書いている次第。