SerpAPI
Живая выдача Google в структурированном JSON: web, Maps, Shopping, News, Images,
YouTube, Scholar, Jobs, Trends. Один эндпоинт, движок выбирается параметром
engine. Капчи и прокси на стороне сервиса — браузер не нужен.
Ключ
SERPAPI_API_KEY из ~/.claude/.credentials.master.env, читать через
os.getenv. Каждый вызов списывает единицу квоты плана — при отладке не гоняй
цикл по страницам вслепую. Тарифы и лимиты → references/pricing-and-limits.md.
Ключа нет — что тогда
Без SERPAPI_API_KEY любой вызов вернёт 401 Invalid API key, а не «ключ не задан».
Бесплатного тарифа, которого хватает на работу, у SerpAPI нет.
Два пути, оба ниже в этом файле:
openserp в Docker — раздел «Локальная бесплатная альтернатива»: живая выдача
Google/Yandex/Bing/DuckDuckGo, 0 кредитов. Structured-блоков (carousels, Maps,
Shopping, Trends) не отдаёт.
- Встроенный веб-поиск Claude Code — когда нужен ответ, а не разбор выдачи по
позициям.
Вызов
import os, requests
def serp(engine: str, **params) -> dict:
r = requests.get("https://serpapi.com/search", params={
"api_key": os.getenv("SERPAPI_API_KEY"),
"engine": engine, "output": "json",
"hl": "en", "gl": "us", **params,
})
r.raise_for_status()
return r.json()
Есть официальная обёртка, но ставится она под неочевидным именем:
pip install google-search-results, а импорт при этом from serpapi import GoogleSearch. Возможностей она не добавляет — тот же GET с теми же параметрами.
Локальная бесплатная альтернатива
Для простого парсинга живой выдачи (без carousels/Maps/Shopping/Trends — за
структурой оставайся на SerpAPI) — self-hosted karust/openserp в Docker,
127.0.0.1:7000, 0 кредитов. Поддерживает Google/Yandex/Bing/DuckDuckGo.
DuckDuckGo/Bing работают из коробки; Google и особенно Yandex (которого
SerpAPI не отдаёт вообще) из коробки капчатся/ратлимитятся без прокси — нужен
--proxy/--2captcha_key на старте контейнера. Полные детали, эндпоинты, гочи
→ ~/.claude/skills/seo-machine-ru/SKILL.md, секция «Яндекс/Google SERP локально
(openserp)».
Движки: параметр запроса и ключ результатов
Ключ, под которым лежат результаты, из имени движка не выводится — угадаешь
неверно, получишь пустой список и решишь, что выдача пустая.
| engine |
запрос кладётся в |
результаты в |
google |
q |
organic_results + knowledge_graph, answer_box, related_questions, related_searches |
google_maps |
q |
local_results |
google_shopping |
q |
shopping_results |
google_news |
q |
news_results |
google_images |
q |
images_results (не image_) |
youtube |
search_query (не q) |
video_results |
google_scholar |
q |
organic_results |
google_jobs |
q |
jobs_results |
google_trends |
q |
interest_over_time, related_queries, related_topics |
google_videos, google_local, google_patents |
q |
распечатай results.keys() — здесь не зафиксировано |
Параметры, которые не угадываются
| Задача |
Параметр |
| Язык / страна выдачи |
hl=en, gl=us |
| Вторая страница |
start=10 (третья — 20) |
| Свежесть: день/неделя/месяц/год |
tbs=qdr:d / qdr:w / qdr:m / qdr:y |
| Вилка цен в Shopping |
tbs=mr:1,price:1,ppr_min:50 (и/или ppr_max:200) |
| Размер картинки |
tbs=isz:l (m средние, i иконки) |
| Тип картинки |
tbs=itp:photo (clipart, lineart) |
| Публикации от года (Scholar) |
as_ylo=2023 |
| Точка на карте |
ll=@55.75,37.61,15z — с @ и z-зумом; либо location=Moscow |
| Окно Trends |
date="today 12-m" (now 1-H, now 7-d, today 1-m) + data_type=TIMESERIES |
tbs — одна строка: несколько фильтров склеиваются через запятую, второе
присваивание затирает первое.
Вложенные поля ответа
Часть значений лежит глубже, чем кажется по названию:
- News:
source.name (не source)
- YouTube:
channel.name, thumbnail.static
- Scholar:
publication_info.summary, inline_links.cited_by.total,
PDF — resources[0].link (списка resources может не быть вовсе)
- Jobs:
detected_extensions.posted_at, detected_extensions.salary
- Shopping:
price — строка с валютой, число для сравнения — extracted_price
- Maps:
gps_coordinates, hours
Гочи
- Результаты кэшируются ~30 секунд: повтор идентичного запроса вернёт тот же
снимок. Если нужна свежесть после правки — меняй параметры, а не жми повтор.
- Локаль решает состав выдачи:
gl/hl меняют не только язык подписей, но и
набор блоков (answer_box, «People also ask» появляются не везде).
1---2name: serpapi3description: "Google Search API через SerpAPI (SERPAPI_API_KEY): выдача, Maps, Shopping, News, YouTube. Триггеры: «спарси выдачу гугла», «цены google shopping»."4metadata:5 source: https://skillmd.com/skills/jhamidun/serpapi6---78# SerpAPI910Живая выдача Google в структурированном JSON: web, Maps, Shopping, News, Images,11YouTube, Scholar, Jobs, Trends. Один эндпоинт, движок выбирается параметром12`engine`. Капчи и прокси на стороне сервиса — браузер не нужен.1314## Ключ1516`SERPAPI_API_KEY` из `~/.claude/.credentials.master.env`, читать через17`os.getenv`. Каждый вызов списывает единицу квоты плана — при отладке не гоняй18цикл по страницам вслепую. Тарифы и лимиты → `references/pricing-and-limits.md`.1920<!-- no-key-block -->21### Ключа нет — что тогда2223Без `SERPAPI_API_KEY` любой вызов вернёт `401 Invalid API key`, а не «ключ не задан».24Бесплатного тарифа, которого хватает на работу, у SerpAPI нет.2526Два пути, оба ниже в этом файле:27281. **`openserp` в Docker** — раздел «Локальная бесплатная альтернатива»: живая выдача29 Google/Yandex/Bing/DuckDuckGo, 0 кредитов. Structured-блоков (carousels, Maps,30 Shopping, Trends) не отдаёт.312. **Встроенный веб-поиск Claude Code** — когда нужен ответ, а не разбор выдачи по32 позициям.3334## Вызов3536```python37import os, requests3839def serp(engine: str, **params) -> dict:40 r = requests.get("https://serpapi.com/search", params={41 "api_key": os.getenv("SERPAPI_API_KEY"),42 "engine": engine, "output": "json",43 "hl": "en", "gl": "us", **params,44 })45 r.raise_for_status()46 return r.json()47```4849Есть официальная обёртка, но ставится она под неочевидным именем:50`pip install google-search-results`, а импорт при этом `from serpapi import51GoogleSearch`. Возможностей она не добавляет — тот же GET с теми же параметрами.5253## Локальная бесплатная альтернатива5455Для простого парсинга живой выдачи (без carousels/Maps/Shopping/Trends — за56структурой оставайся на SerpAPI) — self-hosted `karust/openserp` в Docker,57`127.0.0.1:7000`, 0 кредитов. Поддерживает Google/Yandex/Bing/DuckDuckGo.58DuckDuckGo/Bing работают из коробки; Google и особенно **Yandex** (которого59SerpAPI не отдаёт вообще) из коробки капчатся/ратлимитятся без прокси — нужен60`--proxy`/`--2captcha_key` на старте контейнера. Полные детали, эндпоинты, гочи61→ `~/.claude/skills/seo-machine-ru/SKILL.md`, секция «Яндекс/Google SERP локально62(openserp)».6364## Движки: параметр запроса и ключ результатов6566Ключ, под которым лежат результаты, из имени движка не выводится — угадаешь67неверно, получишь пустой список и решишь, что выдача пустая.6869| engine | запрос кладётся в | результаты в |70|---|---|---|71| `google` | `q` | `organic_results` + `knowledge_graph`, `answer_box`, `related_questions`, `related_searches` |72| `google_maps` | `q` | `local_results` |73| `google_shopping` | `q` | `shopping_results` |74| `google_news` | `q` | `news_results` |75| `google_images` | `q` | `images_results` (не `image_`) |76| `youtube` | **`search_query`** (не `q`) | `video_results` |77| `google_scholar` | `q` | `organic_results` |78| `google_jobs` | `q` | `jobs_results` |79| `google_trends` | `q` | `interest_over_time`, `related_queries`, `related_topics` |80| `google_videos`, `google_local`, `google_patents` | `q` | распечатай `results.keys()` — здесь не зафиксировано |8182## Параметры, которые не угадываются8384| Задача | Параметр |85|---|---|86| Язык / страна выдачи | `hl=en`, `gl=us` |87| Вторая страница | `start=10` (третья — 20) |88| Свежесть: день/неделя/месяц/год | `tbs=qdr:d` / `qdr:w` / `qdr:m` / `qdr:y` |89| Вилка цен в Shopping | `tbs=mr:1,price:1,ppr_min:50` (и/или `ppr_max:200`) |90| Размер картинки | `tbs=isz:l` (`m` средние, `i` иконки) |91| Тип картинки | `tbs=itp:photo` (`clipart`, `lineart`) |92| Публикации от года (Scholar) | `as_ylo=2023` |93| Точка на карте | `ll=@55.75,37.61,15z` — с `@` и `z`-зумом; либо `location=Moscow` |94| Окно Trends | `date="today 12-m"` (`now 1-H`, `now 7-d`, `today 1-m`) + `data_type=TIMESERIES` |9596`tbs` — одна строка: несколько фильтров склеиваются через запятую, второе97присваивание затирает первое.9899## Вложенные поля ответа100101Часть значений лежит глубже, чем кажется по названию:102103- News: `source.name` (не `source`)104- YouTube: `channel.name`, `thumbnail.static`105- Scholar: `publication_info.summary`, `inline_links.cited_by.total`,106 PDF — `resources[0].link` (списка `resources` может не быть вовсе)107- Jobs: `detected_extensions.posted_at`, `detected_extensions.salary`108- Shopping: `price` — строка с валютой, число для сравнения — `extracted_price`109- Maps: `gps_coordinates`, `hours`110111## Гочи112113- Результаты кэшируются ~30 секунд: повтор идентичного запроса вернёт тот же114 снимок. Если нужна свежесть после правки — меняй параметры, а не жми повтор.115- Локаль решает состав выдачи: `gl`/`hl` меняют не только язык подписей, но и116 набор блоков (`answer_box`, «People also ask» появляются не везде).