Запросы

/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`	`;` / табуляция	Для `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. Используйте этот способ, когда запрос длинный или в нём несколько фраз: многострочный запрос в URL упрётся в ограничения длины в прокси и клиентах задолго до того, как возразит сервер.

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.

Типы JSON учитываются: true работает там, где в строке запроса нужна 1. Если параметр передан и в URL, и в теле, побеждает тело.

Ответ

Поле	Что означает
`total`	Сколько сайтов совпало во всём индексе. Точное число, а не оценка.
`total_pages`	`total`, делённое на `per_page` с округлением вверх.
`returned`	Сколько строк на самом деле на этой странице.
`truncated`	Убрал ли что-нибудь лимит открытых позиций вашего тарифа.
`took_ms`	Сколько длился поиск, в миллисекундах.
`results`	Сами строки.

Строка

Поле	Что означает
`domain`	Сайт.
`url`	Страница, на которой найдено совпадение; при поиске с `depth:` это не главная страница.
`rank`	Место в рейтинге: чем меньше, тем популярнее. `null`, если у сайта нет места в рейтинге.
`ranked`	`false` ровно тогда, когда `rank` равен `null`.
`snippets`	Только при `snippets=1`. До пяти пар `{"text", "match"}`, где `match` - то, что совпало, а `text` - то же самое с окружающим контекстом.

Листание и массовая выгрузка

Листайте с помощью page или запросите всё сразу с большим per_page - вплоть до max_per_page из /v1/account, а на платном тарифе это миллион. Отдельного эндпоинта для выгрузки нет; ответ отдаётся по мере формирования, так что миллион строк не означает, что где-то в памяти лежит миллион строк.

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