API

Klinio, depuis votre propre code.

Lancez les mêmes recherches que sur le site, consultez votre historique et récupérez les entreprises en JSON. L’API utilise les crédits de votre compte, y compris les crédits quotidiens gratuits.

URL de basehttps://klinio.io/api/v1

Vos clés d’API

Une clé agit au nom de votre compte. Gardez-la sur votre serveur, jamais dans une page web ni une application.

  1. 1Lancez une recherche avec quoi et où (query et location), ou avec un lien que Klinio sait lire : une recherche Google ou Google Maps, un annuaire Clutch ou des sites d’entreprises.
  2. 2Suivez-la. La plupart des recherches se terminent en quelques minutes ; les entreprises apparaissent au fur et à mesure.
  3. 3Lisez les entreprises : site web, e‑mails et téléphones.
# 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"

Votre historique est aussi dans l’API.

Chaque recherche lancée sur le site, dans l’extension Chrome ou avec l’API rejoint le même historique. Listez-le, filtrez-le et lisez les entreprises de n’importe quelle recherche via son results_url.

source
Où la recherche a été faite. linkedin_list est une liste LinkedIn envoyée depuis l’extension, websites une liste de sites web, merged des listes fusionnées sur le site.google_mapsgoogle_searchclutchlinkedinlinkedin_listwebsitesmerged
status
Où en est la recherche. Chaque statut est expliqué plus bas.queuedrunningcompletedstoppedfailed
origin
Où vous l’avez lancée : sur klinio.io, dans l’extension Chrome ou avec l’API.siteextensionapi
q
Un texte du nom ou des mots de la recherche. Majuscules et accents ne comptent pas : cafe trouve aussi Café.
sinceuntil
Selon le début de la recherche : since à partir de ce moment, until jusqu’à lui. Envoyez une date (2026-11-01) ou une heure ISO 8601 ; une date dans until inclut toute la journée.
limitcursor
De 1 à 100 recherches par page (20 par défaut). Renvoyez next_cursor dans cursor pour la page suivante ; total compte toutes les recherches qui correspondent.
# 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 · Réponse
{
  "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…"
}

Points d’accès

Envoyez votre clé dans l’en-tête Authorization sous la forme Bearer kl_live_…, et les corps de requête en JSON. Chaque réponse est en JSON.

  • POST/searches

    Lance une recherche. Envoyez query et location (quoi et où : une recherche Google Maps), ou link (un lien de recherche, ou des sites), ou websites (une liste). En option, limit (de 1 à 500 entreprises) et country (deux lettres, pour un lien de recherche google.com).

  • GET/searches

    Votre historique : chaque recherche lancée sur le site, dans l’extension ou avec l’API, de la plus récente à la plus ancienne. Filtrez-le avec source, status, origin, q, since et until.

  • GET/searches/{id}

    Une recherche : son statut et le nombre d’entreprises trouvées jusqu’ici.

  • GET/searches/{id}/results

    Les entreprises trouvées, 100 à la fois (limit jusqu’à 500). only=contacts garde celles qui ont un e‑mail ou un téléphone ; next_cursor donne la page suivante.

  • DELETE/searches/{id}

    Arrête une recherche en attente ou en cours. Ce qu’elle a trouvé reste.

  • GET/account

    Votre offre et les crédits qu’il vous reste.

GET /searches/{id} · Réponse
{
  "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 · Réponse
{
  "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
}

Le statut d’une recherche

  • queuedAttend son tour.
  • runningTrouve des entreprises et lit leurs sites.
  • completedTerminée. Chaque entreprise a été vérifiée.
  • stoppedArrêtée par vous. Ce qu’elle a trouvé reste.
  • failedN’a pas pu aboutir. failure en donne la raison.

Crédits et limites

  • Un crédit correspond à une entreprise avec un e‑mail ou un téléphone, comme sur le site. Les entreprises sans résultat ne coûtent rien.
  • Un compte gratuit utilise ses crédits quotidiens, un pack son solde. Sans crédit, une nouvelle recherche répond 402.
  • Jusqu’à 3 recherches en attente ou en cours en même temps par compte, et 120 requêtes par minute et par clé.
  • Un navigateur ne peut pas appeler l’API : elle n’envoie aucun en-tête CORS, la clé reste donc sur votre serveur.

Erreurs

Une erreur répond avec son statut HTTP et un corps JSON : error.code et error.message.

  • 400invalid_requestLe corps ou un paramètre n’est pas valide.
  • 400invalid_linkKlinio ne lit pas ce lien.
  • 400mixed_inputUn lien de recherche et des sites dans la même requête.
  • 400unsupported_google_tabUn onglet Google qui ne liste pas d’entreprises, comme Images ou Actualités.
  • 401unauthorizedLa clé manque, est fausse ou révoquée.
  • 402insufficient_creditsPlus de crédits pour une nouvelle recherche.
  • 403source_disabledCe site est désactivé pour le moment.
  • 404not_foundAucune recherche de ce type sur ce compte.
  • 409not_runningLa recherche n’est ni en attente ni en cours.
  • 429too_many_runningTrop de recherches en attente ou en cours en même temps.
  • 429rate_limitedTrop de requêtes cette minute.