Response formats

One search resource, six spellings of the answer. Pick with format=; JSON is the default and the one the others are described in terms of.

`format`	Content-Type	Shape
`json`	`application/json`	One object, results in an array.
`ndjson`	`application/x-ndjson`	One JSON object per line. The first line is the metadata, tagged `"object":"meta"`.
`xml`	`application/xml`	The same document as XML, rows as `<result>`.
`csv`	`text/csv`	Semicolon separated, no header line.
`tsv`	`text/tab-separated-values`	As CSV, tab separated.
`txt`	`text/plain`	One url per line.

jsonl is accepted as another name for ndjson.

Which to use

json for anything that fits in memory. ndjson for anything that does not: there is no enclosing array to wait for, the metadata arrives before the rows, and a reader can start work on the first result while the rest is still arriving. csv, tsv and txt for spreadsheets, shell pipelines, and for moving a script over from the old export urls without changing its parser.

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}

Choosing the columns

json and xml return every field. The flat formats default to the familiar ones instead, so a script coming from the old export urls needs no parser change:

Request	Output
`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`	a `domain;rank` line first
`format=csv&delimiter=,`	`imgbox.com,4187`

columns works for every format, so format=json with columns=domain returns objects with only that field.

Details of the flat formats

A value is quoted only when it would otherwise break the row - it contains the delimiter, a quote or a newline. Ordinary domain;rank output is bare.
Quotes inside a quoted value are doubled, as CSV expects.
Snippets, being a list, are joined with ... into one cell.
An unranked site has an empty rank cell, which is how null spells itself here.
The totals cannot fit in a row, so they are in the X-Total-Results, X-Returned-Results and X-Truncated headers instead. Those are sent for every format.

These are the new API's own serialisations, not a reissue of the old exports. The shape is familiar on purpose, but only the old urls promise the exact bytes.

Formats and errors

csv, tsv and txt are shapes for rows and nothing else, so asking for one on /v1/account is 400 format_not_available. Errors themselves come back as JSON, or as XML if that is what was asked for.

Next Quotas and rate limits