# 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://it.publicwww.com/docs/api/clusters/).

URL di base `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](https://it.publicwww.com/docs/api/requests/), [formati](https://it.publicwww.com/docs/api/formats/). |
| `/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](https://it.publicwww.com/docs/api/clusters/). |
| `/mcp` | POST | Il [server MCP](https://it.publicwww.com/docs/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](https://api.publicwww.com/openapi.json), 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 chiedi a `/v1/search` un `per_page` elevato, fino a `max_per_page` in `/v1/account`; la risposta arriva in streaming man mano che viene prodotta.

Header dei limiti: `X-Requests-*` contano le richieste al minuto, `X-RateLimit-*` le ricerche al giorno, `X-Snippets-*` le richieste con snippet al giorno; quali risposte li portano è spiegato nei [limiti](https://it.publicwww.com/docs/api/limits/).

I totali di una ricerca sono anche negli header, in ogni formato: `X-Total-Results`, `X-Returned-Results`, `X-Truncated` e `X-Index-Complete`; CSV, TSV e TXT non hanno posto per loro nel corpo, quindi lì si trovano solo negli header ([formati](https://it.publicwww.com/docs/api/formats/)).

## Cosa garantisce

- **I risultati non vengono mai ridotti di nascosto.** Quando la quota giornaliera si esaurisce, il sito torna silenziosamente ai limiti del piano gratuito; l'API risponde invece `429 quota_exceeded`, non con una risposta ridotta che sembra completa.
- **Una risposta incompleta è segnalata come tale**: `truncated` nel corpo e `X-Truncated` negli header, in ogni formato.
- **I siti senza posizione lo dichiarano**: `rank: null` e `ranked: 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](https://it.publicwww.com/profile/api), oppure lascia che un'applicazione lo ottenga per te tramite [OAuth 2.1](https://it.publicwww.com/docs/api/authentication/#oauth). Sul sito web un account gratuito ha ricerche e cluster entro i propri limiti; i piani sono nei [prezzi](https://it.publicwww.com/prices.html).

L'API è per il tuo codice - uno script, un server, un'applicazione. Una pagina web non può chiamarla dal browser: il browser blocca queste chiamate, e il token resterebbe in vista nella pagina.

## Nel dettaglio

- [Autenticazione](https://it.publicwww.com/docs/api/authentication/) - il token in un header, e OAuth 2.1.
- [Inviare richieste](https://it.publicwww.com/docs/api/requests/) - `/v1/search`: la query e i suoi parametri, via GET o POST.
- [Formati di risposta](https://it.publicwww.com/docs/api/formats/) - JSON, NDJSON, XML, CSV, TSV e testo semplice, da scegliere con `format=`.
- [Quote e limiti di frequenza](https://it.publicwww.com/docs/api/limits/) - ricerche al giorno, richieste al minuto e gli header che le riportano.
- [Errori](https://it.publicwww.com/docs/api/errors/) - la stessa struttura e un codice stabile per ogni errore.
- [Cluster](https://it.publicwww.com/docs/api/clusters/) - elenchi salvati di siti web: creare, combinare, estrarre valori, creare firme.
- [Esempi di codice](https://it.publicwww.com/docs/api/examples/) - la stessa ricerca in diversi linguaggi, con paginazione e attesa quando viene richiesta.
- [Google Sheets](https://it.publicwww.com/docs/api/sheets/) - una formula e un menu che portano le ricerche in un foglio di calcolo.
- [Clay](https://it.publicwww.com/docs/api/clay/) - PublicWWW tramite l'HTTP API di Clay con il tuo token.
- [I vecchi URL di esportazione](https://it.publicwww.com/docs/api/legacy/) - download con `?export=`, invariati.

Source: https://it.publicwww.com/docs/api/
