Search APIは他のREST APIとは回数制限の適用の仕方が異なるということ
自分の作ったTwitterのbotに『ほんのつぶやき (@honnotsubuyaki) | Twitter
これは、『読んだ4！』のTwitterアカウントである @yonda4 宛のつぶやきを横から見て、その中にASIN／ISBNっぽいものが含まれている場合に、“『タイトル』作者 Amazonへのリンク”を返す、というものなのですが。
この、“@yonda4宛のつぶやきを横から見”るのには、Twitterの
search
http://apiwiki.twitter.com/Twitter-Search-API-Method%3A-search
Returns tweets that match a specified query.
を使っています。
これは『Twitter API プログラミング』の P.262にも有るとおり、
- API実行回数制限の適用対象。
- IPアドレス単位で制限がかかる。
- REST API(http://api.twitter.com/1/〜のエンドポイントをもつAPI)とは別枠でカウントされる。
ようです。
ただ、同書には
- 同一IPアドレスからの検索関連のAPIの実行は1時間あたり150回まで。
となっていますが、
Search API Rate Limiting
http://apiwiki.twitter.com/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.
とあるとおり、明確に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仕様上はまだこのことに言及されている気配が無いので、現段階ではまだ密かに書いている次第。
