Google Custom Search API を使ってみる

## はじめに

Google Custom Search API を使ってみる。

キーワード検索結果から 数万件の URL を集めるのが今回の目的。
それを実現するために、どれくらいこの API が使えるのかを調査することになりました。

## 事前調査

### 公式情報

公式の情報はこちら。

[Custom Search JSON/Atom API - Custom Search — Google Developers] (https://developers.google.com/custom-search/json-api/v1/overview)

とりあえず、頑張って翻訳してみようかな。（グーグル翻訳の力を借りつつ・・・）

以下、 Custom Search JSON/Atom API（2015.01.05時点）のページを翻訳したものです。

* 冒頭部

> JSON/Atom のカスタム検索APIを使用すると、プログラムで Google カスタム検索から検索結果を取得し、表示する Web サイトやアプリケーションを開発できます。この API を使用すると、ウェブ検索もしくは画像検索のいず れかの結果を、JSON または Atom フォーマットにて取得する RESTful なリクエストを使用することができます。

* データ形式

> JSON/Atom のカスタム検索 API は、2つのフォーマットのうち、いずれかひとつの形式で結果を返すことができます。JSON は、デフォルトのデータフォーマットです。また、クエリパラメータに「alt=atom」を指定することによって、Atom フォーマットで結果を取得することができます。
   
* 関連ドキュメント

> このAPIを使用するための有用なリソースである 2 つの外部文書があります。

> * Google WebSearch Protocol (XML)：
>     
> JSON/Atom のカスタム検索 API は、XML APIが提供する機能のサブセットを提供しますが、その代わりにJSONまたはAtomフォーマットでデータを返します。
> 
> * OpenSearch 1.1 Specification：
> 
> （ちょっとここの内容後回し。）

* 前提条件

> * 検索エンジンID
>
> APIのユーザーの問題を呼び出すことにより、カスタム検索エンジンの既存のインスタンスに対して要求します。（←この一文の訳が意味わからん。。）そのため、APIを使用する前に、コントロールパネルにて、あなたはこのIDをひとつ作成する必要があります。別の設定オプションの詳細について知るには、チュートリアルに従ってください。あなたのエンジンIDは、コントロールパネルの「Setup > Basics > Details」 のセクションから見つけることができます。
> 
> * APIキー
> 
> JSON/Atomのカスタム検索APIは、APIキーを使用する必要があります。
> 
> カスタム検索エンジン（無料版）のユーザーは、Google開発者コンソールよりキー取得できます。
Googleサイト検索（有料版）のユーザーは、コントロールパネルの「Business > XML＆JSON」タブから、自分のAPIキーを見つけることができます。

* 価格設定

> JSON/Atom のカスタム検索APIの価格設定と割り当ては、エンジンのエディションによって異なります。
> 
> * カスタム検索エンジン（無料）
> 
> CSE ユーザーの場合、API は無料で一日あたり 100 検索クエリを提供します。あなたがより多くを必要とする場合は、開発者コンソールで「課金」をするためのサインアップをする必要があります。追加リクエストは、一日あたり 10K のクエリまで、1000 のクエリにつき 5 ドルの費用がかかります。
> 
> * Googleサイト検索（有料）
> 
> GSSの使用制限とクォータの詳細については、GSSの価格オプションを確認してください。

以上、翻訳でした。

### 先人情報

すでに使ったことがあるよ！という先人様の情報が転がっていないか調査。
以下のサイトをみつけたよ。

[[PHP] Google Custom Search API を試す (2013年7月時点版) | offsidenowの日常を綴ったブログ] (http://offsidenow.phpapps.jp/archives/415)

[Google Custom Search APIがひどい - 下林明正のブログ] (http://shimobayashi.hatenablog.com/entry/2012/12/14/Google_Custom_Search_API%E3%81%8C%E3%81%B2%E3%81%A9%E3%81%84)

[Googleカスタム検索をAPIで取得ようとしたが残念だった件 - アークウェブシステム開発SandBox] (http://www.ark-web.jp/sandbox/wiki/7615.html)

全体的に「制限がきつくて数が取れないから、無料の範囲内は残念」という意見が多い気がしました。

まぁ検索エンジン自体が今や立派なサービスになって市場化してるから、
今どき、無料で使える事を期待しちゃイカン。
あくまで、「お試し利用は無料」ってことだよね。

では、実際どんな風に取得できるのか、お試し利用やってみよ～。

## Google Custom Search API の使い方

Googleのアカウントは取得している大前提で話を進めるよ。

まずは Google Developers Console にアクセス。
https://console.developers.google.com/

※Google play の Developer Consoleではないので要注意！
（自分が間違えて開いて有料だったのでビビったｗ）

これ以降の手順に関しては、
めっちゃ丁寧に説明してくれているブログを発見したので、そちらを是非参考にして欲しい。
今日も先人様に感謝！！！

* [google custom search engine(CSE)を使って、検索結果をjsonで取得する - ryutamaki]
(http://ryutamaki.hatenablog.com/entry/2014/01/18/171640)

私もキャプチャ撮ったので、オリジナルの手順作ろうかと思ったけど、
↑のブログでの説明で十分すぎるからやめたｗ
なので、上記のブログには載っていない情報をちょこちょこ載せておこうと思う。

## リクエスト制限について（無料の場合）

Custom Search API の **無料枠** の利用制限は　**100リクエスト/日** です。

過去にトライした人の情報では、
「リクエスト制限が厳しくて使えないなぁ」っていう雰囲気はわかるんだけど、
実際のところ
「どんなふうにリクエストのカウントがされるの？」といった情報が
あまり見当たらなかったので、その点について少しまとめてみました。

ちなみに、リクエストの実行方法として、
今回はブラウザ経由でGETして、カウントの挙動を調べています。

### リクエストカウントの確認方法

Developers Console 画面から確認可能。

「有効なAPI」の画面からの確認↓

![DevelopersConsoleApi.jpg](https://qiita-image-store.s3.amazonaws.com/0/62698/ed42ebb0-02fa-6943-3a73-8be8da9cc919.jpeg)


「Custom Search API」を選択後、「使用量」を選ぶと↓こんな画面で確認できる。

![DevelopersConsoleCustomSearchApi.JPG](https://qiita-image-store.s3.amazonaws.com/0/62698/5822e782-dac6-1411-9723-1f0a51fe23f3.jpeg)

リクエストした後の変化の例↓

![DevelopersConsoleCustomSearchApi_use.JPG](https://qiita-image-store.s3.amazonaws.com/0/62698/fbe3479e-5ad1-f36d-2f53-2ab0bcc2a319.jpeg)

「割り当て」を選ぶと↓こんな画面で確認できる。

![DevelopersConsoleCustomSearchApi_quota.JPG](https://qiita-image-store.s3.amazonaws.com/0/62698/53ade098-e98a-ca1e-8e9d-e96d1e286154.jpeg)


### リクエストカウントがリセットされるタイミング

おもわぬ時間（17時付近？）に、カウントがリセットされた気がして、
もしかしたら、「1日」の範囲が日本とは異なるタイムゾーンないのかもしれないなぁ・・・
と、疑惑を持っていたら、案の定、タイムゾーンが異なった。

↑の画像の「割り当ての概要」のすぐ下を注目。

```
1 日あたり（午前 0 時（PST）から）
```

って書いてあるわ～。
タイムゾーンが **PST（太平洋時間）**だ。ロサンゼルス！！！

というわけで、
現在の日本とロサンゼルスとの時差は、**17 時間**（日本の方が、17時間進んでる）ため、
リクエストカウントのリセット時間は日本時間(JST)でいうところの **17 時**となるので要注意。


### リクエストカウントの検証結果

* 全く同じリクエストをした場合、カウントはどうなるの？
    - 全く同じリクエストをした場合でも、1リクエストとしてカウントされました。

当たり前と言えば当たり前かな。刻一刻と検索結果は変化するもんね。

* パラメータの指定ミス等で、検索結果が取得エラーになった場合、カウントはどうなるの？
    - JSON結果が返却される場合でも、1リクエストとしてカウントされました。

下記は、例えば、取得する検索結果件数を指定するパラメータ「num」に指定範囲である「1~10」以外の数字を指定した場合に帰ってきたエラー（num=11を指定）

<img src="https://qiita-image-store.s3.amazonaws.com/0/62698/424ad82b-1f6a-8e8c-c7be-f1dd62a96f0f.jpeg" style="display: block; margin: 0 auto; width: 100px;" alt="image" title="リクエストパラメータに規定範囲外の値(num=11)を指定した場合のエラー"/>

このようなエラーが返却された場合でも、1リクエストとしてカウントされました。

なので、リクエストをミスしたら、とても勿体無いね・・・。
プログラムで一気にリクエストしたら致命的だな・・・。

### リクエストパラメータについて

実際に API 使い出すと、リクエストパラメータをしばしば調べるので、メモ。

* [CSE: list - Custom Search — Google Developers](https://developers.google.com/custom-search/json-api/v1/reference/cse/list?hl=ja)

以上、おわり。