API

Klinio прямо из вашего кода.

Запускайте те же поиски, что и на сайте, просматривайте историю и получайте компании в JSON. API расходует кредиты вашего аккаунта, включая бесплатные ежедневные.

Базовый URLhttps://klinio.io/api/v1

Ваши ключи API

Ключ действует от имени вашего аккаунта. Храните его на сервере, никогда не вставляйте в веб-страницу или приложение.

  1. 1Запустите поиск, указав что и где (query и location), или по ссылке, которую читает Klinio: поиск Google или Google Карт, каталог Clutch либо сайты компаний.
  2. 2Проверяйте статус. Большинство поисков завершается за несколько минут; компании появляются по мере нахождения.
  3. 3Получите компании: сайт, email и телефоны.
# 1. Start a search
curl -X POST https://klinio.io/api/v1/searches \
  -H "Authorization: Bearer $KLINIO_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "web design agencies", "location": "Ankara", "limit": 50}'

# 2. Check on it (status: queued, running, completed)
curl https://klinio.io/api/v1/searches/SEARCH_ID \
  -H "Authorization: Bearer $KLINIO_KEY"

# 3. Read the companies with an email or phone
curl "https://klinio.io/api/v1/searches/SEARCH_ID/results?only=contacts" \
  -H "Authorization: Bearer $KLINIO_KEY"

Ваша история тоже есть в API.

Каждый поиск, запущенный на сайте, в расширении Chrome или через API, попадает в одну историю. Получайте её списком, фильтруйте и читайте компании любого поиска по его results_url.

source
Источник поиска. linkedin_list: список LinkedIn из расширения; websites: список сайтов; merged: списки, объединённые на сайте.google_mapsgoogle_searchclutchlinkedinlinkedin_listwebsitesmerged
status
Состояние поиска. Что значит каждое, описано ниже.queuedrunningcompletedstoppedfailed
origin
Где вы его запустили: на klinio.io, в расширении Chrome или через API.siteextensionapi
q
Текст в названии или словах поиска. Регистр букв не важен.
sinceuntil
По времени начала поиска: since с этого момента, until до него. Передайте дату (2026-11-01) или время в ISO 8601; дата в until включает весь день.
limitcursor
От 1 до 100 поисков на странице (по умолчанию 20). Для следующей страницы передайте next_cursor в cursor; total считает все подходящие поиски.
# Your whole history, newest first: site, extension and API
curl "https://klinio.io/api/v1/searches?limit=100" \
  -H "Authorization: Bearer $KLINIO_KEY"

# Finished Google Maps searches since 1 November
curl -G https://klinio.io/api/v1/searches \
  -d source=google_maps -d status=completed -d since=2026-11-01 \
  -H "Authorization: Bearer $KLINIO_KEY"

# Searches with "agency" in their name
curl -G https://klinio.io/api/v1/searches -d q=agency \
  -H "Authorization: Bearer $KLINIO_KEY"
GET /searches · Ответ
{
  "data": [{
    "id": "8f2d41c7-3b9e-4c55-a1d0-6e7b2c9f0a13",
    "status": "completed",
    "source": "google_search",
    "query": "web design agency ankara",
    "link": "https://www.google.com/search?q=web+design+agency+ankara&gl=tr",
    "limit": 100,
    "origin": "site",
    "created_at": "2026-11-07T10:19:07.805Z",
    "finished_at": "2026-11-07T10:31:42.118Z",
    "companies": { "found": 71, "with_contacts": 65, "checking": 0 },
    "failure": null,
    "results_url": "/api/v1/searches/8f2d41c7-3b9e-4c55-a1d0-6e7b2c9f0a13/results"
  }],
  "total": 61,
  "next_cursor": "WyIyMDI2LTExLTA3IDEwOjE5OjA3Ljgw…"
}

Эндпоинты

Передавайте ключ в заголовке Authorization как Bearer kl_live_…, а тела запросов в JSON. Каждый ответ приходит в JSON.

  • POST/searches

    Запускает поиск. Передайте query и location (что и где: поиск на Google Картах), либо link (ссылку на поиск или сайты), либо websites (список). По желанию limit (от 1 до 500 компаний) и country (две буквы, для ссылки на поиск google.com).

  • GET/searches

    Ваша история: все поиски, запущенные на сайте, в расширении или через API, сначала новые. Фильтры: source, status, origin, q, since и until.

  • GET/searches/{id}

    Один поиск: его статус и сколько компаний уже найдено.

  • GET/searches/{id}/results

    Найденные компании, по 100 за раз (limit до 500). only=contacts оставляет компании с email или телефоном; next_cursor даёт следующую страницу.

  • DELETE/searches/{id}

    Останавливает поиск в очереди или в работе. Найденное остаётся.

  • GET/account

    Ваш тариф и оставшиеся кредиты.

GET /searches/{id} · Ответ
{
  "id": "1c5c9560-8174-4745-88e0-5682394d69cd",
  "status": "running",
  "source": "google_maps",
  "query": "web design agencies in Ankara",
  "link": "https://www.google.com/maps/search/web+design+agencies+in+Ankara/",
  "limit": 50,
  "origin": "api",
  "created_at": "2026-11-07T15:58:23.257Z",
  "finished_at": null,
  "companies": { "found": 18, "with_contacts": 14, "checking": 4 },
  "failure": null,
  "results_url": "/api/v1/searches/1c5c9560-8174-4745-88e0-5682394d69cd/results"
}
GET /searches/{id}/results · Ответ
{
  "search_status": "completed",
  "data": [{
    "id": "b0a3e7c2-5d4f-4a8e-9c61-2f7d8e1a4b90",
    "company": "Bilgeweb Interactive",
    "website": "https://www.bilgeweb.com.tr",
    "emails": ["info@bilgeweb.com.tr"],
    "phones": ["+90 312 911 75 02"],
    "location": "Yenimahalle/Ankara, Türkiye",
    "industry": "Advertising agency",
    "source": "google_maps",
    "status": "done",
    "created_at": "2026-11-07T15:58:31.904Z"
  }],
  "next_cursor": null
}

Статус поиска

  • queuedЖдёт своей очереди.
  • runningНаходит компании и читает их сайты.
  • completedГотово. Все компании проверены.
  • stoppedОстановлен вами. Найденное остаётся.
  • failedНе удалось завершить. Причину укажет поле failure.

Кредиты и лимиты

  • Один кредит означает одну компанию с email или телефоном, как на сайте. Компании, для которых ничего не нашлось, бесплатны.
  • Бесплатный аккаунт тратит ежедневные кредиты, пакет тратит свой баланс. Без кредитов новый поиск отвечает 402.
  • До 3 поисков в очереди или в работе одновременно на аккаунт и 120 запросов в минуту на ключ.
  • Браузер не может вызвать API: оно не отправляет заголовки CORS, поэтому ключ остаётся на вашем сервере.

Ошибки

Ошибка приходит с HTTP-статусом и телом JSON: error.code и error.message.

  • 400invalid_requestТело запроса или параметр недопустимы.
  • 400invalid_linkKlinio не читает такую ссылку.
  • 400mixed_inputСсылка на поиск и сайты в одном запросе.
  • 400unsupported_google_tabВкладка Google без списка компаний, например «Картинки» или «Новости».
  • 401unauthorizedКлюча нет, он неверный или отозван.
  • 402insufficient_creditsНет кредитов для нового поиска.
  • 403source_disabledЭтот сайт сейчас отключён.
  • 404not_foundВ этом аккаунте нет такого поиска.
  • 409not_runningПоиск не в очереди и не в работе.
  • 429too_many_runningСлишком много поисков в очереди или в работе одновременно.
  • 429rate_limitedСлишком много запросов за эту минуту.