リクエストの送信

/v1/searchには、検索ボックスに入力するのと同じクエリと、いくつかのパラメーターを指定します。GETとPOSTのどちらでも呼び出せ、パラメーターはどちらでも同じです。

パラメーター

名前	初期値	意味
`query`	必須	検索文字列。構文はウェブサイトと同じです。クエリ構文をご覧ください。
`page`	1	1から始まります。
`per_page`	100	プランの行数上限まで指定できます。`page × per_page`も同じ上限内に収まる必要があります。プランで取得できるのはクエリの先頭N行までで、ページ送りでその先には進めません（`400 page_too_deep`）。この上限は`/v1/account`の`max_per_page`で確認できます。
`snippets`	オフ	`1`を指定すると、一致したテキストを含めます。スニペットの利用枠を消費します。
`format`	`json`	6種類から選択します。レスポンス形式をご覧ください。
`columns`	形式によって異なる	`domain`、`url`、`rank`、`ranked`、`snippets`から、必要なものをカンマ区切りで指定します。
`delimiter`	`;` / タブ	`csv`と`tsv`で使用します。
`header`	オフ	`1`を指定すると、`csv`と`tsv`にヘッダー行を付けます。

GET

curl -H "Authorization: Bearer $KEY" \
     "https://api.publicwww.com/v1/search?query=%22angular.min.js%22&page=2&per_page=50"

クエリは必ずURLエンコードしてください。引用符、スラッシュ、+はいずれも意味を持ちます。

POST

同じパラメーターをJSONの本文で送信します。クエリが長い場合や複数のフレーズを含む場合に使います。複数行のクエリをURLに入れると、サーバー側で問題になるよりずっと前に、プロキシやクライアントの長さ制限に引っかかります。

curl https://api.publicwww.com/v1/search \
     -H "Authorization: Bearer $KEY" \
     -H "Content-Type: application/json" \
     -d '{"query": ["\"angular.min.js\"", "\"bootstrap.min.css\""],
          "per_page": 50,
          "snippets": true}'

フレーズの配列は、query文字列でフレーズを改行で区切った場合とまったく同じく、そのすべてを含むという意味になります。上の例では、1つ目のフレーズを含むサイトが278件、両方を含むサイトが99件です。

JSONの型も解釈されます。クエリ文字列で1を指定するところでは、trueも使えます。同じパラメーターがURLと本文の両方で指定された場合は、本文が優先されます。

レスポンス

フィールド	意味
`total`	インデックス全体で一致するサイトの数。推定値ではなく実数です。
`total_pages`	`total`を`per_page`で割り、切り上げた値。
`returned`	このページに実際に含まれる行数。
`truncated`	プランの表示順位の上限によって行が除外されたかどうか。
`took_ms`	検索にかかった時間（ミリ秒）。
`results`	結果の行。

行

フィールド	意味
`domain`	サイト。
`url`	一致が見つかったページ。`depth:`を使った検索では、トップページとは限りません。
`rank`	ランキング上の順位。小さいほど人気があります。サイトに順位がない場合は`null`です。
`ranked`	`rank`が`null`のときに限り`false`です。
`snippets`	`snippets=1`を指定した場合のみ。最大5つの`{"text", "match"}`のペアで、`match`は一致した部分、`text`はその前後の文脈を含むテキストです。

ページ送りと大量取得

pageでページを送るか、per_pageを大きくして一度にすべてを取得します。上限は/v1/accountのmax_per_pageで、有料プランでは100万です。エクスポート専用のエンドポイントはありません。レスポンスは生成されるそばから書き出されるため、100万行を返すためにどこかのメモリーに100万行を保持することもありません。

次へレスポンス形式