Serper.live API

Швидкий старт

Три кроки від порожнього акаунта до першого живого результату.

1. Створіть акаунт і токен у розділі API-токени. Повне значення токена показується один раз, тож збережіть його в менеджері секретів.
2. Поповніть баланс у USDT або USDC на сторінці Баланс. Один живий пошук коштує $0.10, і тарифікуються лише успішні пошуки.
3. Надішліть запит нижче зі своїм токеном. У відповіді буде поточна видача Google для цього ринку.

curl -X POST https://api.serper.live/v1/search \
  -H "Authorization: Bearer sl_live_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"query":"best coffee shops","country":"TR"}'

const response = await fetch('https://api.serper.live/v1/search', {
    method: 'POST',
    headers: {
        Authorization: 'Bearer sl_live_YOUR_TOKEN',
        'Content-Type': 'application/json',
    },
    body: JSON.stringify({ query: 'best coffee shops', country: 'TR' }),
    signal: AbortSignal.timeout(100000),
});
const result = await response.json();

console.log(result.organic);

import requests

response = requests.post(
    "https://api.serper.live/v1/search",
    headers={"Authorization": "Bearer sl_live_YOUR_TOKEN"},
    json={"query": "best coffee shops", "country": "TR"},
    timeout=100,
)
print(response.json()["organic"])

Живий пошук триває 10–60 секунд, бо справді завантажує Google. Дайте своєму HTTP-клієнту тайм-аут щонайменше 100 секунд.

Автентифікація

Кожен запит до /v1/search передає ваш токен у заголовку Authorization:

Authorization: Bearer sl_live_YOUR_TOKEN

• Токени починаються з sl_live_ і створюються в розділі API-токени. Створюйте окремий токен для кожного застосунку, щоб відкликати його, не зачіпаючи інших.
• Тримайте токени на своєму сервері. Ніколи не вбудовуйте їх у браузер, мобільний застосунок чи публічний репозиторій.
• Відкликаний токен перестає працювати одразу; історія його запитів лишається у вашому акаунті.

Пошук

POST https://api.serper.live/v1/search

Виконує один живий пошук Google і повертає органічні результати. Запит і відповідь у JSON; тіло запиту обмежене 16 КБ.

Тіло запиту

Відповідь

{
  "requestId": "0199860b-2f4e-7a1c-9b3d-5e6f70819a2b",
  "query": "best coffee shops",
  "country": "TR",
  "language": "en",
  "device": "desktop",
  "fetchedAt": "2026-09-28T14:00:00.000Z",
  "latencyMs": 18342,
  "price": 0.1,
  "currency": "USD",
  "organic": [
    {
      "position": 1,
      "title": "The 12 best coffee shops in town",
      "url": "https://example.com/guides/best-coffee-shops",
      "domain": "example.com",
      "snippet": "A curated list of specialty coffee shops, updated every month."
    },
    {
      "position": 2,
      "title": "Coffee shops near me",
      "url": "https://maps.example.org/coffee",
      "domain": "maps.example.org",
      "snippet": null
    }
  ]
}

Країни

GET https://api.serper.live/v1/countries

Публічний, токен не потрібен. Повертає ринки, відкриті просто зараз, типову мову Google для кожного і підтримувані пристрої.

curl https://api.serper.live/v1/countries

{
  "countries": [
    {
      "code": "TR",
      "defaultLanguage": "tr",
      "devices": [
        "desktop",
        "mobile"
      ]
    }
  ]
}

Зараз відкрито: Türkiye. Нові ринки з’являються тут і на сторінці цін у міру запуску. Запит для закритого ринку повертає 422 country_unavailable разом зі списком доступних кодів.

Тарифікація

На вашому акаунті є передплачений баланс у USD. Кожен запит резервує поточну ціну свого ринку до початку пошуку.

• Успішний пошук: зарезервована сума списується.
• Невдалий пошук, тобто будь-яка відповідь 5xx: резерв знімається автоматично. Ви ніколи не платите за результат, якого не отримали.
• Ціни можуть змінюватися з часом, але ціна, зарезервована для запиту, що вже виконується, не змінюється ніколи.
• Недостатньо коштів: 402 insufficient_balance. Поповніть баланс на сторінці Баланс; кошти доступні за кілька хвилин після підтвердження депозиту.

Кожен запит, його статус і вартість перелічені в історії запитів; кожна зміна балансу є в журналі на сторінці балансу.

Помилки

Помилки повертаються як JSON із машинозчитуваним кодом error, зрозумілим людині message і, якщо запит уже створено, його requestId:

{
  "error": "insufficient_balance",
  "message": "The balance does not cover one request",
  "requestId": "0199860b-2f4e-7a1c-9b3d-5e6f70819a2b"
}

Безпечні повторні запити

Необов’язково. Потрібно лише тоді, коли ваш клієнт може повторити запит, який обірвався.

Живий пошук триває до 90 секунд. Якщо за цей час з’єднання розірветься, ви не знатимете, чи пошук завершився і чи його тарифіковано. Заголовок Idempotency-Key дає змогу повторити запит, не заплативши двічі:

• Той самий ключ і те саме тіло: якщо перший пошук завершився, ви знову отримаєте ту саму відповідь із заголовком Idempotent-Replayed: true і без другого списання. Якщо він ще виконується, повторний запит дочекається його.
• Той самий ключ і інше тіло: 409 idempotency_conflict.
• Результати зберігаються 15 хвилин. Після цього повтор зі старим ключем повертає 409 idempotency_replay_unavailable; надішліть новий запит із новим ключем.
• Без заголовка кожен запит новий і тарифікується окремо.

curl -X POST https://api.serper.live/v1/search \
  -H "Authorization: Bearer sl_live_YOUR_TOKEN" \
  -H "Idempotency-Key: 0199860b-2f4e-7a1c-9b3d-5e6f70819a2b" \
  -H "Content-Type: application/json" \
  -d '{"query":"best coffee shops","country":"TR","limit":10}'

Ключ — будь-який рядок із 8–128 символів набору A-Za-z0-9._:-. Найпростіший вибір — новий UUID на кожен логічний запит; він має лишатися однаковим для всіх повторів цього запиту.

Обмеження і корисне

• query 2–120 символів, limit 1–10, тіло запиту до 16 КБ.
• Пошуки виконуються паралельно в межах потужності сервісу; понад неї ви отримаєте 503 busy. Повторюйте зі зростанням інтервалу.
• Живий пошук триває 10–60 секунд. Установіть тайм-аут клієнта щонайменше 100 секунд.
• Кожна відповідь має заголовок X-Request-Id. Зберігайте його в логах поруч із requestId з тіла.
• Нічого не кешується: два однакові запити — це два живі пошуки і два списання. Якщо повторно використовуєте результати, кешуйте на своєму боці.