Интеграция по API

Все запросы идут на один эндпоинт https://serpapi.com/search. Параметры передаются в URL: движок, фраза, ключ и при необходимости язык, страна, локация. Ответ - JSON.

Ключ в переменной окружения

Не хардкодьте ключ в коде. Положите его в файл .env и читайте оттуда. Так ключ не попадёт в репозиторий.

SERPAPI_API_KEY=ваш_ключ_здесь

Запрос через curl

Самый простой способ проверить вызов из терминала. Подставьте свой ключ в параметр api_key:

curl "https://serpapi.com/search?engine=google&q=coffee&api_key=$SERPAPI_API_KEY"

В ответ придёт JSON со всей выдачей. Чтобы посмотреть только органику, можно прогнать вывод через jq:

curl -s "https://serpapi.com/search?engine=google&q=coffee&hl=ru&gl=ru&api_key=$SERPAPI_API_KEY" \
  | jq '.organic_results[] | {title, link}'

Запрос на Python

У сервиса есть официальный клиент - пакет google-search-results. Ставится через pip:

pip install google-search-results

Базовый пример: задаём параметры словарём, получаем ответ как обычный dict.

import os
from serpapi import GoogleSearch

params = {
    "engine": "google",
    "q": "coffee",
    "hl": "ru",
    "gl": "ru",
    "api_key": os.environ["SERPAPI_API_KEY"],
}

search = GoogleSearch(params)
data = search.get_dict()

for item in data.get("organic_results", []):
    print(item["title"], "-", item["link"])

Для JavaScript и Node.js есть отдельный клиент - пакет serpapi. Логика та же: передаёте параметры, получаете JSON.

Как достать нужные поля

Ответ - вложенный объект, поэтому читайте поля аккуратно и проверяйте их наличие:

# прямой ответ, если поисковик его показал
answer = data.get("answer_box", {}).get("answer")

# первые три органических результата
top = [
    {"title": r["title"], "link": r["link"], "snippet": r.get("snippet")}
    for r in data.get("organic_results", [])[:3]
]

Используйте get с дефолтом, а не прямое обращение по ключу: не каждый блок есть в каждом ответе. Если answer_box не было, прямое чтение упадёт с ошибкой, а get вернёт пустое значение.

SerpAPI как веб-поиск для AI-агента

Главный современный сценарий - дать языковой модели инструмент поиска в интернете. Схема простая: агент решает, что нужно поискать, формулирует запрос, ваш код дёргает SerpAPI, забирает несколько верхних результатов и отдаёт их модели как контекст. Дальше модель отвечает, опираясь на свежие данные, а не только на то, что было в обучении.

def web_search(query: str, k: int = 5) -> list[dict]:
    """Инструмент веб-поиска для агента: вернуть k верхних результатов."""
    from serpapi import GoogleSearch

    search = GoogleSearch({
        "engine": "google",
        "q": query,
        "num": k,
        "api_key": os.environ["SERPAPI_API_KEY"],
    })
    data = search.get_dict()
    return [
        {"title": r["title"], "link": r["link"], "snippet": r.get("snippet", "")}
        for r in data.get("organic_results", [])[:k]
    ]

Такую функцию регистрируют как инструмент модели (tool / function calling): модель сама вызывает web_search, когда ей не хватает знаний, и получает обратно компактный список результатов.