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.
https://klinio.io/api/v1Le tue chiavi API
Una chiave agisce come il tuo account. Tienila sul tuo server, mai in una pagina web o in un’app.
- 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.
- 2Controlla a che punto è. Quasi tutte le ricerche finiscono in pochi minuti; le aziende compaiono man mano che vengono trovate.
- 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"{
"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
/searchesAvvia 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
/searchesLa 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}/resultsLe 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
/accountIl tuo piano e i crediti rimasti.
{
"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"
}{
"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.
- 400
invalid_requestIl corpo o un parametro non è valido. - 400
invalid_linkKlinio non legge questo link. - 400
mixed_inputUn link di ricerca e dei siti nella stessa richiesta. - 400
unsupported_google_tabUna scheda di Google che non elenca aziende, come Immagini o Notizie. - 401
unauthorizedLa chiave manca, è sbagliata o revocata. - 402
insufficient_creditsNessun credito per una nuova ricerca. - 403
source_disabledQuesto sito per ora è disattivato. - 404
not_foundNessuna ricerca così su questo account. - 409
not_runningLa ricerca non è in coda né in corso. - 429
too_many_runningTroppe ricerche in coda o in corso alla volta. - 429
rate_limitedTroppe richieste in questo minuto.