API

Klinio من شيفرتك مباشرة.

شغّل عمليات البحث نفسها التي في الموقع، واستعرض سجلّك، واحصل على الشركات بصيغة JSON. تستخدم الواجهة رصيد حسابك، بما فيه الرصيد اليومي المجاني.

عنوان URL الأساسيhttps://klinio.io/api/v1

مفاتيح API الخاصة بك

يعمل المفتاح باسم حسابك. احتفظ به على خادمك، ولا تضعه أبدًا في صفحة ويب أو تطبيق.

  1. 1ابدأ بحثًا بتحديد ماذا وأين (query وlocation)، أو برابط يقرؤه Klinio: بحث Google أو خرائط Google، أو دليل Clutch، أو مواقع شركات.
  2. 2تابع حالته. تنتهي معظم عمليات البحث خلال دقائق قليلة، وتظهر الشركات فور العثور عليها.
  3. 3اقرأ الشركات: الموقع والبريد الإلكتروني والهواتف.
# 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"

سجلّك موجود في الواجهة البرمجية أيضًا.

كل عملية بحث تبدأها في الموقع أو في إضافة Chrome أو عبر الواجهة البرمجية تُحفظ في السجل نفسه. اعرضه وصفِّه، واقرأ شركات أي بحث من results_url الخاص به.

source
مصدر البحث. linkedin_list قائمة من LinkedIn أُرسلت من الإضافة، وwebsites قائمة مواقع، وmerged قوائم دمجتها في الموقع.google_mapsgoogle_searchclutchlinkedinlinkedin_listwebsitesmerged
status
حالة البحث. معنى كل حالة موضّح في الأسفل.queuedrunningcompletedstoppedfailed
origin
أين بدأته: في klinio.io أو في إضافة Chrome أو عبر الواجهة البرمجية.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

    سجلّك: كل عمليات البحث التي بدأت في الموقع أو في الإضافة أو عبر الواجهة البرمجية، الأحدث أولًا. صفِّه بالمعاملات source وstatus وorigin وq وsince وuntil.

  • GET/searches/{id}

    بحث واحد: حالته وعدد الشركات التي وجدها حتى الآن.

  • GET/searches/{id}/results

    الشركات التي وجدها، 100 في كل مرة (limit حتى 500). يُبقي only=contacts الشركات التي لها بريد إلكتروني أو هاتف، ويجلب 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 السبب.

الرصيد والحدود

  • الرصيد الواحد شركة واحدة لها بريد إلكتروني أو هاتف، كما في الموقع. الشركات التي لم يُعثر لها على شيء مجانية.
  • يستهلك الحساب المجاني رصيده اليومي، وتستهلك الباقة رصيدها. عند نفاد الرصيد يجيب البحث الجديد بالرمز 402.
  • حتى 3 عمليات بحث في الانتظار أو قيد التشغيل في الوقت نفسه لكل حساب، و120 طلبًا في الدقيقة لكل مفتاح.
  • لا يستطيع المتصفح استدعاء الواجهة: فهي لا ترسل ترويسات CORS، لذا يبقى المفتاح على خادمك.

الأخطاء

يعود الخطأ برمز حالة HTTP وجسم JSON يحتوي على error.code وerror.message.

  • 400invalid_requestالجسم أو أحد المعاملات غير صالح.
  • 400invalid_linkلا يقرأ Klinio هذا الرابط.
  • 400mixed_inputرابط بحث ومواقع في الطلب نفسه.
  • 400unsupported_google_tabتبويب في Google لا يعرض شركات، مثل الصور أو الأخبار.
  • 401unauthorizedالمفتاح مفقود أو خاطئ أو ملغى.
  • 402insufficient_creditsلا يوجد رصيد لبحث جديد.
  • 403source_disabledهذا الموقع معطّل حاليًا.
  • 404not_foundلا يوجد بحث كهذا في هذا الحساب.
  • 409not_runningالبحث ليس في الانتظار ولا قيد التشغيل.
  • 429too_many_runningعمليات بحث كثيرة جدًا في الانتظار أو قيد التشغيل في الوقت نفسه.
  • 429rate_limitedطلبات كثيرة جدًا في هذه الدقيقة.