API
L'API esegue la stessa ricerca del sito web e restituisce i risultati come dati: JSON per impostazione predefinita, oppure XML, CSV, TSV, NDJSON e testo semplice. Una ricerca si limita a leggere; ciò che l'API crea, rinomina ed elimina sono i tuoi cluster.
https://api.publicwww.com
In un solo comando
Ricerche e cluster tramite l'API richiedono un piano a pagamento; il token di un
account gratuito legge solo /v1/account.
export PUBLICWWW_KEY=...
curl -H "Authorization: Bearer $PUBLICWWW_KEY" \
"https://api.publicwww.com/v1/search?query=%22angular.min.js%22&per_page=3"
{
"query": "\"angular.min.js\"",
"page": 1,
"per_page": 3,
"total": 70907,
"total_pages": 23636,
"returned": 3,
"truncated": false,
"index_complete": true,
"took_ms": 2,
"results": [
{ "domain": "imgbox.com", "url": "https://imgbox.com/", "rank": 4187, "ranked": true }
]
}
Endpoint
| Endpoint | Metodi | Cosa fa |
|---|---|---|
/v1/search |
GET, POST | Esegue una ricerca. Parametri, formati. |
/v1/account |
GET | Piano, quota e limiti. Non consuma nulla, non conta nel limite di frequenza e funziona con qualsiasi account. |
/v1/clusters |
GET, POST | Elenchi salvati di siti web: creali da una ricerca o da un elenco, combinali, estrai contatti e ID dal codice sorgente delle pagine, costruisci le firme. Cluster. |
/mcp |
POST | Il server MCP per assistenti e agenti AI: ricerca e cluster come strumenti, con lo stesso token. |
/ |
GET | L'API che descrive se stessa, codici di errore compresi. Non richiede chiave. |
/openapi.json |
GET | La stessa cosa come descrizione OpenAPI 3.1, da importare in Postman, n8n, Make, Power Automate e altri strumenti. Non richiede chiave. |
Non esiste un endpoint di esportazione separato. Per i grandi volumi si usa
/v1/search con un per_page elevato, fino a un limite che
dipende dal piano (max_per_page in /v1/account); la
risposta arriva in streaming man mano che viene prodotta.
Ogni risposta porta due gruppi di header dei limiti: X-Requests-* sono le richieste al minuto, X-RateLimit-* le ricerche al giorno - vedi i limiti.
Cosa garantisce
-
I risultati non vengono mai ridotti di nascosto. Quando la quota
giornaliera di un browser si esaurisce, il sito torna silenziosamente ai
limiti del piano gratuito e mostra meno risultati. Uno script non può
accorgersene, quindi qui diventa un errore:
429 quota_exceeded, non una risposta ridotta che sembra completa. -
Una risposta incompleta è segnalata come tale:
truncatednel corpo eX-Truncatednegli header, in ogni formato. -
I siti senza posizione lo dichiarano:
rank: nulleranked: false, mai un segnaposto interno che un client potrebbe scambiare per una posizione reale, molto alta. -
Meglio sentirsi dire di aspettare che essere fatti aspettare. Se le
richieste arrivano troppo in fretta, la risposta torna subito con un
Retry-After, invece di tenere aperta la connessione.
Ottenere una chiave
Crea un token nel tuo profilo, oppure lascia che
un'applicazione lo ottenga per te tramite
OAuth 2.1. Tramite l'API, le
ricerche e i cluster richiedono un piano a pagamento; sul sito web un account
gratuito li ha entro i propri limiti - vedi i prezzi. Gli script esistenti che
usano i vecchi URL ?export= continuano a funzionare senza modifiche:
vedi i vecchi URL di esportazione.
Nel dettaglio
- Autenticazione - il token in un header, e OAuth 2.1.
- Inviare richieste -
/v1/search: la query e i suoi parametri, via GET o POST. - Formati di risposta - JSON, NDJSON, XML, CSV, TSV e testo semplice, da scegliere con
format=. - Quote e limiti di frequenza - ricerche al giorno, richieste al minuto e gli header che le riportano.
- Errori - la stessa struttura e un codice stabile per ogni errore.
- Cluster - elenchi salvati di siti web: creare, combinare, estrarre valori, creare firme.
- Esempi di codice - la stessa ricerca in diversi linguaggi, con paginazione e attesa quando viene richiesta.
- Google Sheets - una formula e un menu che portano le ricerche in un foglio di calcolo.
- Clay - PublicWWW tramite l'HTTP API di Clay con il tuo token.
- I vecchi URL di esportazione - download con
?export=, invariati.