レスポンス形式

検索リソースは1つで、レスポンスの表現形式は6種類あります。format=で選択します。初期設定はJSONで、他の形式もJSONを基準に説明しています。

formatContent-Type構造
jsonapplication/json1つのオブジェクト。結果は配列に入ります。
ndjsonapplication/x-ndjson1行に1つのJSONオブジェクト。1行目はメタデータで、"object":"meta"が付きます。
xmlapplication/xml同じ内容のXML文書。各行は<result>です。
csvtext/csvセミコロン区切り。ヘッダー行なし。
tsvtext/tab-separated-valuesCSVと同じで、タブ区切り。
txttext/plain1行に1つのURL。

jsonlはndjsonの別名として受け付けます。

どれを使うか

メモリーに収まるデータならjsonを使います。収まらないデータにはndjsonを使います。全体を囲む配列の終わりを待つ必要がなく、メタデータが行より先に届き、残りの受信中でも最初の結果から処理を始められます。スプレッドシート、シェルのパイプライン、そしてパーサーを変更せずに旧エクスポートURLからスクリプトを移行する場合には、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はすべてのフィールドを返します。フラットな形式では、初期設定でおなじみの列だけを返すため、旧エクスポートURLから移行するスクリプトもパーサーを変更する必要がありません。

リクエスト出力
format=csvimgbox.com;4187
format=csv&columns=url,rankhttps://imgbox.com/;4187
format=csv&columns=domainimgbox.com
format=txthttps://imgbox.com/
format=csv&snippets=1imgbox.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の仕様どおり二重にします。
  • スニペットはリストなので、...でつないで1つのセルに入れます。
  • 順位のないサイトは順位のセルが空になります。これがこれらの形式でのnullの表し方です。
  • 合計値は行に収まらないため、代わりにX-Total-Results、X-Returned-Results、X-Truncatedの各ヘッダーで返します。これらのヘッダーはすべての形式で送信されます。

これらは新しいAPI独自のシリアライズ形式であり、旧エクスポートの再発行ではありません。構造は意図的に似せていますが、バイト単位で同一の出力を保証するのは旧URLだけです。

形式とエラー

csv、tsv、txtは行を表すためだけの形式なので、/v1/accountでこれらを指定すると400 format_not_availableになります。エラー自体はJSONで返されます。XMLを指定した場合はXMLで返されます。

次へ 利用枠とレート制限