API

Klinio artık kendi kodunuzda.

Sitedeki aramaların aynısını başlatın, geçmişinizi listeleyin ve şirketleri JSON olarak alın. API hesabınızın kredilerini kullanır; günlük ücretsiz krediler de dahil.

Taban URLhttps://klinio.io/api/v1

API anahtarlarınız

Anahtar hesabınız adına çalışır. Onu sunucunuzda tutun; asla bir web sayfasına ya da uygulamaya koymayın.

  1. 1Ne ve nerede (query ve location) ile ya da Klinio'nun okuduğu bir bağlantıyla arama başlatın: Google ya da Google Haritalar araması, Clutch dizini veya şirket web siteleri.
  2. 2Durumunu kontrol edin. Çoğu arama birkaç dakikada biter; şirketler bulundukça gelir.
  3. 3Şirketleri okuyun: web sitesi, e‑postalar ve telefonlar.
# 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"

Geçmişiniz de API'de.

Sitede, Chrome eklentisinde ya da API ile başlattığınız her arama aynı geçmişte toplanır. Listeleyin, süzün ve herhangi bir aramanın şirketlerini results_url adresinden okuyun.

source
Aramanın yapıldığı yer. linkedin_list eklentiden gönderilen bir LinkedIn listesi, websites bir web siteleri listesi, merged ise sitede birleştirdiğiniz listelerdir.google_mapsgoogle_searchclutchlinkedinlinkedin_listwebsitesmerged
status
Aramanın durumu. Her birinin anlamı aşağıda.queuedrunningcompletedstoppedfailed
origin
Nerede başlattığınız: klinio.io'da, Chrome eklentisinde ya da API ile.siteextensionapi
q
Aramanın adında ya da sözcüklerinde geçen metin. Büyük-küçük harf ve Türkçe karakter fark etmez: sisli, Şişli'yi de bulur.
sinceuntil
Aramanın başladığı zamana göre: since o andan itibaren, until o ana kadar. Bir tarih (2026-11-01) ya da ISO 8601 zamanı gönderin; until'deki tarih o günü de kapsar.
limitcursor
Sayfa başına 1-100 arama (belirtmezseniz 20). Sonraki sayfa için next_cursor değerini cursor olarak gönderin; total, süzgeçlere uyan bütün aramaları sayar.
# 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 · Yanıt
{
  "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…"
}

Uç noktalar

Anahtarınızı Authorization başlığında Bearer kl_live_… olarak, istek gövdesini JSON olarak gönderin. Her yanıt JSON'dur.

  • POST/searches

    Arama başlatır. query ve location (ne ve nerede: Google Haritalar araması) ya da link (bir arama bağlantısı ya da web siteleri) veya websites (liste) gönderin. İsterseniz limit (1-500 şirket) ve country (iki harf, google.com arama bağlantısı için) ekleyin.

  • GET/searches

    Geçmişiniz: sitede, eklentide ya da API ile başlatılan bütün aramalar, en yenisi önce. source, status, origin, q, since ve until ile süzebilirsiniz.

  • GET/searches/{id}

    Tek bir arama: durumu ve şimdiye kadar kaç şirket bulduğu.

  • GET/searches/{id}/results

    Bulduğu şirketler, 100'er 100'er (limit en fazla 500). only=contacts yalnızca e‑postası ya da telefonu olanları bırakır; next_cursor sonraki sayfayı getirir.

  • DELETE/searches/{id}

    Sırada bekleyen ya da süren bir aramayı durdurur. Bulduklarına dokunulmaz.

  • GET/account

    Planınız ve kalan kredileriniz.

GET /searches/{id} · Yanıt
{
  "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 · Yanıt
{
  "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
}

Bir aramanın durumu

  • queuedSırasını bekliyor.
  • runningŞirketleri buluyor ve sitelerini okuyor.
  • completedBitti. Her şirket kontrol edildi.
  • stoppedSizin tarafınızdan durduruldu. Bulduklarına dokunulmadı.
  • failedTamamlanamadı. Nedeni failure alanında.

Krediler ve sınırlar

  • Bir kredi, e‑postası ya da telefonu bulunan bir şirkettir; sitedekiyle aynı. Hiçbir şey bulunamayan şirketler ücretsizdir.
  • Ücretsiz hesap günlük kredilerini, paket ise bakiyesini kullanır. Kredi kalmadıysa yeni arama 402 döner.
  • Hesap başına aynı anda en fazla 3 arama sırada ya da sürüyor olabilir; anahtar başına dakikada 120 istek.
  • API tarayıcıdan çağrılamaz: CORS başlığı göndermez, böylece anahtar sunucunuzda kalır.

Hatalar

Hata, HTTP durum koduyla ve bir JSON gövdesiyle döner: error.code ve error.message.

  • 400invalid_requestGövde ya da bir parametre geçersiz.
  • 400invalid_linkKlinio bu bağlantıyı okumuyor.
  • 400mixed_inputAynı istekte bir arama bağlantısı ve web siteleri.
  • 400unsupported_google_tabŞirket listelemeyen bir Google sekmesi, Görseller ya da Haberler gibi.
  • 401unauthorizedAnahtar yok, yanlış ya da iptal edilmiş.
  • 402insufficient_creditsYeni bir arama için kredi kalmadı.
  • 403source_disabledBu site şu an kapalı.
  • 404not_foundBu hesapta böyle bir arama yok.
  • 409not_runningArama ne sırada ne de sürüyor.
  • 429too_many_runningAynı anda sırada ya da süren çok fazla arama var.
  • 429rate_limitedBu dakika içinde çok fazla istek.