Форматы ответа

Один поисковый ресурс и шесть вариантов записи ответа. Формат выбирается параметром 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, но с табуляцией.
`txt`	`text/plain`	По одному URL на строку.

jsonl принимается как другое имя ndjson.

Какой выбрать

json - для всего, что помещается в память. ndjson - для всего, что не помещается: нет внешнего массива, которого надо дождаться, метаданные приходят раньше строк, и обработку первого результата можно начать, пока остальные ещё идут. 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.
Фрагменты - это список, поэтому они склеиваются через ... в одну ячейку.
У сайта без места в рейтинге ячейка rank пустая - так здесь записывается null.
Итоговые числа в строку не помещаются, поэтому они передаются в заголовках X-Total-Results, X-Returned-Results и X-Truncated. Эти заголовки отправляются для любого формата.

Это собственная сериализация нового API, а не переиздание старых выгрузок. Вид намеренно сделан привычным, но точное совпадение байт в байт обещают только старые адреса.

Форматы и ошибки

csv, tsv и txt предназначены только для строк выдачи, поэтому запрос такого формата к /v1/account даёт 400 format_not_available. Сами ошибки приходят в JSON или в XML, если был запрошен он.

Далее Лимиты и ограничения частоты