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Забагато запитів за цю хвилину.