Search: поисковая выдача

/v1/search берёт выдачу настоящим браузером и отдаёт её разобранной: не HTML поисковика, а JSON с органикой, рекламой, товарами и остальными секциями.

Разница с /v1/fetch не в адресе, а в задаче. Search знает движки и знает, где у них что лежит. Fetch не знает про содержимое ничего: адрес ваш, разбор ваш.

Первый запрос

Обязательных параметра два: q и engine. Умолчания у движка нет намеренно — иначе запрос молча уходил бы не в тот поисковик, и разбираться, почему выдача «не та», пришлось бы уже на проде.

from parreq import Parreq

client = Parreq("pr_ВАШКЛЮЧ")
res = client.google("coffee machine", gl="us", hl="en")

print(res.metadata["total_ms"], "мс")
print(res.organic[0]["title"], res.organic[0]["link"])

import { Parreq } from "parreq-client";

const client = new Parreq({ apiKey: "pr_ВАШКЛЮЧ" });
const res = await client.google({ q: "coffee machine", gl: "us", hl: "en" });

console.log(res.metadata.total_ms, "мс");
console.log(res.organic[0].title, res.organic[0].link);

curl -H "Authorization: Bearer pr_ВАШКЛЮЧ" \
  "https://api.parreq.com/v1/search?q=coffee+machine&engine=google&gl=us&hl=en"

Ответ:

{
  "search_metadata": {
    "id": "cdc9e907b324410e",
    "status": "success",
    "engine": "google",
    "requested_url": "https://www.google.com/search?q=coffee+machine&…",
    "final_url": "https://www.google.com/search?q=coffee+machine&…",
    "fetch_ms": 4120,
    "total_ms": 4180,
    "html_size": 412903,
    "detected_location": null,
    "created_at": 1787332891,
    "credits": 3,
    "credits_breakdown": { "search": 2, "engine_google": 1 },
    "credits_left": 748
  },
  "search_parameters": {
    "q": "coffee machine",
    "engine": "google",
    "device": "desktop",
    "gl": "us",
    "hl": "en",
    "page": 1,
    "location": null,
    "domain": null,
    "include": []
  },
  "organic_results": [
    {
      "position": 1,
      "title": "…",
      "link": "https://…",
      "displayed_link": "…",
      "snippet": "…"
    }
  ]
}

search_metadata.id — номер запроса. По нему же забирается снимок и находится запрос в истории кабинета.

Параметры

параметр	по умолчанию	что делает
`q`	—	поисковый запрос, обязателен
`engine`	—	`google` или `yandex`, обязателен
`device`	`desktop`	`desktop`, `desktop_mac`, `mobile`, `mobile_ios`, `tablet`
`gl`	`us`	страна: домен движка, часовой пояс, координаты, `Accept-Language`
`hl`	`en`	язык интерфейса выдачи
`page`	`1`	страница выдачи, до 20
`num`	—	результатов на странице, только Google
`location`	—	canonical name для `uule`, только Google: `Berlin,Berlin,Germany`
`domain`	по стране	переопределить домен движка: `www.google.by`
`include`	—	секции сверх органики, см. Секции ответа
`screenshot`	`false`	снимок страницы выдачи целиком, платно

gl задаёт страну выдачи, но не адрес, с которого мы приходим. Рекламу Google подбирает по IP, поэтому объявления другого рынка при несовпадении — ожидаемое поведение, а не ошибка разбора.

Устройство меняет выдачу, а не только вёрстку

device=mobile — это не «та же выдача в узкой колонке». У мобильной выдачи другой состав блоков и другой порядок органики, и сравнивать позиции между устройствами нельзя: это две разные выдачи.

Снимок выдачи

screenshot: true снимает страницу поисковика целиком — от строки запроса до пагинации, вместе с рекламой и правой колонкой. Полезен ровно для одного: убедиться, что выдача та самая, особенно когда клиент спорит о позициях.

curl -X POST https://api.parreq.com/v1/search \
  -H "Authorization: Bearer pr_ВАШКЛЮЧ" -H 'Content-Type: application/json' \
  -d '{"q":"coffee machine","engine":"google","screenshot":true}'

Ссылка приходит в search_metadata.screenshot_url, само изображение отдаёт /v1/search/{job_id}/screenshot — JPEG, шириной во всю ширину устройства (1920 для desktop).

Снимок — платная надстройка: 4 кредита, и ключу нужна возможность screenshot. Если хранилище не приняло файл, ссылки в ответе не будет, а надстройка вычитается из счёта — Кредиты и права.

GET или POST

Одно и то же. GET удобен руками и в браузере, POST — когда параметров много и не хочется собирать строку запроса. Тело POST — те же имена полей.

Сколько ждать

ситуация	время
прогретый профиль	3–10 с
профиль поднимается	+2–4 с на старт Chrome
поисковик показал капчу	до 2 минут

Ставьте клиентский таймаут не меньше 180 секунд: столько же держит и сервис, дальше отвечает 504 timeout.

Дальше

Секции ответа

Полный список секций и форма каждой.

Кредиты и права

Цена запроса, движка, секций и снимка.

Ошибки

Что повторять, а что чинить кодом.

Справочник Search

Схема запроса и ответа, примеры на Python и Node.

Начало

Search

Fetch

Browser API

Crawler

Агенты и MCP

Библиотеки

Как это работает

Search: поисковая выдача

Первый запрос

Параметры

Устройство меняет выдачу, а не только вёрстку

Снимок выдачи

GET или POST

Сколько ждать

Дальше

Секции ответа

Кредиты и права

Ошибки

Справочник Search

​Первый запрос

​Параметры

​Устройство меняет выдачу, а не только вёрстку

​Снимок выдачи

​GET или POST

​Сколько ждать

​Дальше

Секции ответа

Кредиты и права

Ошибки

Справочник Search

Первый запрос

Параметры

Устройство меняет выдачу, а не только вёрстку

Снимок выдачи

GET или POST

Сколько ждать

Дальше