回應格式
同一個搜尋資源,六種回應寫法。以 format= 選擇;JSON 是預設格式,其他格式都以它為基準來說明。
format | Content-Type | 結構 |
|---|---|---|
json | application/json | 一個物件,結果放在陣列中。 |
ndjson | application/x-ndjson | 每行一個 JSON 物件。第一行是中繼資料,標記為 "object":"meta"。 |
xml | application/xml | 以 XML 表示的同一份文件,每項結果為一個 <result>。 |
csv | text/csv | 以分號分隔,沒有標題行。 |
tsv | text/tab-separated-values | 與 CSV 相同,但以 Tab 分隔。 |
txt | text/plain | 每行一個網址。 |
jsonl 亦被接受,作為 ndjson 的別名。
該用哪一種
記憶體容納得下的,用 json;容納不下的,用 ndjson:無須等待外層陣列結束,中繼資料會先於結果送達,讀取端在其餘結果仍在傳送時,就可以開始處理第一項結果。試算表、Shell 管線,以及想把腳本從舊版匯出網址遷移過來而不改動其解析器時,請用 csv、tsv 及 txt。
ndjson
{"object":"meta","query":"\"angular.min.js\"","page":1,"per_page":2,"total":278,"total_pages":139,"returned":2,"truncated":false,"took_ms":2}
{"domain":"imgbox.com","url":"https://imgbox.com/","rank":4187,"ranked":true}
{"domain":"angularjs.org","url":"https://angularjs.org/","rank":12376,"ranked":true}
選擇欄位
json 及 xml 會返回所有欄位。平面格式則預設只返回大家熟悉的欄位,因此從舊版匯出網址遷移過來的腳本無須改動解析器:
| 請求 | 輸出 |
|---|---|
format=csv | imgbox.com;4187 |
format=csv&columns=url,rank | https://imgbox.com/;4187 |
format=csv&columns=domain | imgbox.com |
format=txt | https://imgbox.com/ |
format=csv&snippets=1 | imgbox.com;4187;the matching text |
format=csv&header=1 | 第一行為 domain;rank |
format=csv&delimiter=, | imgbox.com,4187 |
columns 適用於所有格式,因此 format=json 加上 columns=domain,返回的物件就只有該欄位。
平面格式的細節
- 只有當某個值會破壞該行的結構時——即包含分隔符、引號或換行符——才會加上引號。一般的
domain;rank輸出不加引號。 - 加了引號的值內的引號會重複一次,符合 CSV 的規範。
- 程式碼片段是一個列表,因此會以
...連接,放在同一格中。 - 沒有排名的網站,排名一格會留空——這就是
null在這裏的寫法。 - 總數無法放進任何一行,因此改為放在
X-Total-Results、X-Returned-Results及X-Truncated標頭中。所有格式都會發送這些標頭。
這些是新 API 自己的序列化格式,並非舊版匯出的翻版。結構刻意保持熟悉,但只有舊版網址才保證逐位元組相同的輸出。
格式與錯誤
csv、tsv 及 txt 只適用於結果列表,因此對 /v1/account 要求這些格式會得到 400 format_not_available。錯誤本身以 JSON 返回;如請求的是 XML,則以 XML 返回。