發送請求

/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`	六種格式之一——請參閱回應格式。
`columns`	視乎格式	以逗號分隔，從 `domain`、`url`、`rank`、`ranked`、`snippets` 中選取。
`delimiter`	`;` / Tab	適用於 `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 內容傳送相同的參數。查詢很長或包含多個詞組時請使用 POST：網址中的多行查詢，在伺服器出問題之前，早已碰上代理伺服器及用戶端的長度限制。

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 字串中以換行分隔它們完全相同。在上面的例子中，有 278 個網站包含第一個詞組，99 個網站同時包含兩個。

API 能理解 JSON 類型：在查詢字串中需要寫 1 的地方，可以用 true。如同一參數同時出現在網址及內容中，以內容為準。

回應

欄位	含義
`total`	整個索引中符合的網站數目。這是實際數目，並非估算。
`total_pages`	`total` 除以 `per_page`，向上取整。
`returned`	本頁實際包含的項數。
`truncated`	是否有結果因您方案的可見位置限制而被移除。
`took_ms`	搜尋所需時間，以毫秒計。
`results`	結果各項。

單項結果

欄位	含義
`domain`	網站。
`url`	找到符合內容的網頁；使用 `depth:` 搜尋時，這不一定是首頁。
`rank`	排名位置，數字越小越熱門。網站沒有排名時為 `null`。
`ranked`	當且僅當 `rank` 為 `null` 時為 `false`。
`snippets`	只在 `snippets=1` 時提供。最多五組 `{"text", "match"}`，其中 `match` 是符合的內容，`text` 是連同上下文的內容。

翻頁與大量取得

可用 page 逐頁翻閱，也可以用較大的 per_page 一次取得全部——上限為 /v1/account 中的 max_per_page，付費方案為一百萬。沒有獨立的匯出端點；回應會一邊生成一邊寫出，因此一百萬項結果並不需要同時保存在某處的記憶體中。

下一頁回應格式