API

Klinio, dal tuo codice.

Avvia le stesse ricerche del sito, consulta la tua cronologia e ricevi le aziende in JSON. L’API usa i crediti del tuo account, compresi quelli giornalieri gratuiti.

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

Le tue chiavi API

Una chiave agisce come il tuo account. Tienila sul tuo server, mai in una pagina web o in un’app.

  1. 1Avvia una ricerca con cosa e dove (query e location), oppure con un link che Klinio sa leggere: una ricerca di Google o Google Maps, una directory Clutch o siti aziendali.
  2. 2Controlla a che punto è. Quasi tutte le ricerche finiscono in pochi minuti; le aziende compaiono man mano che vengono trovate.
  3. 3Leggi le aziende: sito web, email e telefoni.
# 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"

Anche la tua cronologia è nell’API.

Ogni ricerca che avvii sul sito, nell’estensione di Chrome o con l’API finisce nella stessa cronologia. Elencala, filtrala e leggi le aziende di qualsiasi ricerca dal suo results_url.

source
Dove è stata fatta la ricerca. linkedin_list è una lista LinkedIn inviata dall’estensione, websites un elenco di siti web, merged liste che hai unito sul sito.google_mapsgoogle_searchclutchlinkedinlinkedin_listwebsitesmerged
status
A che punto è la ricerca. Ogni stato è spiegato più sotto.queuedrunningcompletedstoppedfailed
origin
Dove l’hai avviata: su klinio.io, nell’estensione di Chrome o con l’API.siteextensionapi
q
Testo nel nome o nelle parole della ricerca. Maiuscole e accenti non contano: cafe trova anche Café.
sinceuntil
In base a quando è iniziata la ricerca: since da quel momento, until fino ad allora. Invia una data (2026-11-01) o un orario ISO 8601; una data in until include l’intera giornata.
limitcursor
Da 1 a 100 ricerche per pagina (20 se non indichi nulla). Per la pagina successiva rimanda next_cursor come cursor; total conta tutte le ricerche che corrispondono.
# 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 · Risposta
{
  "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…"
}

Endpoint

Invia la chiave nell’intestazione Authorization come Bearer kl_live_… e i corpi delle richieste in JSON. Ogni risposta è JSON.

  • POST/searches

    Avvia una ricerca. Invia query e location (cosa e dove: una ricerca su Google Maps), oppure link (un link di ricerca o dei siti) o websites (un elenco). Facoltativi: limit (da 1 a 500 aziende) e country (due lettere, per un link di ricerca google.com).

  • GET/searches

    La tua cronologia: ogni ricerca avviata sul sito, nell’estensione o con l’API, dalla più recente. Filtrala con source, status, origin, q, since e until.

  • GET/searches/{id}

    Una ricerca: il suo stato e quante aziende ha trovato finora.

  • GET/searches/{id}/results

    Le aziende trovate, 100 alla volta (limit fino a 500). only=contacts tiene quelle con email o telefono; next_cursor porta alla pagina successiva.

  • DELETE/searches/{id}

    Ferma una ricerca in coda o in corso. Ciò che ha trovato resta.

  • GET/account

    Il tuo piano e i crediti rimasti.

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

Lo stato di una ricerca

  • queuedAspetta il suo turno.
  • runningTrova aziende e legge i loro siti.
  • completedFinita. Ogni azienda è stata controllata.
  • stoppedFermata da te. Ciò che ha trovato resta.
  • failedNon è riuscita a finire. failure dice perché.

Crediti e limiti

  • Un credito è un’azienda con email o telefono, come sul sito. Le aziende senza risultati non costano nulla.
  • Un account gratuito usa i crediti giornalieri, un pacchetto il suo saldo. Senza crediti, una nuova ricerca risponde 402.
  • Fino a 3 ricerche in coda o in corso alla volta per account e 120 richieste al minuto per chiave.
  • I browser non possono chiamare l’API: non invia intestazioni CORS, così la chiave resta sul tuo server.

Errori

Un errore risponde con il suo stato HTTP e un corpo JSON: error.code ed error.message.

  • 400invalid_requestIl corpo o un parametro non è valido.
  • 400invalid_linkKlinio non legge questo link.
  • 400mixed_inputUn link di ricerca e dei siti nella stessa richiesta.
  • 400unsupported_google_tabUna scheda di Google che non elenca aziende, come Immagini o Notizie.
  • 401unauthorizedLa chiave manca, è sbagliata o revocata.
  • 402insufficient_creditsNessun credito per una nuova ricerca.
  • 403source_disabledQuesto sito per ora è disattivato.
  • 404not_foundNessuna ricerca così su questo account.
  • 409not_runningLa ricerca non è in coda né in corso.
  • 429too_many_runningTroppe ricerche in coda o in corso alla volta.
  • 429rate_limitedTroppe richieste in questo minuto.