Inviare richieste

/v1/search accetta la stessa query che scriveresti nella casella di ricerca, più qualche parametro. Risponde sia a GET sia a POST; i parametri sono gli stessi in entrambi i casi.

Parametri

Nome	Predefinito	Significato
`query`	obbligatorio	La stringa di ricerca. Stessa sintassi del sito web: vedi sintassi delle query.
`page`	1	A partire da 1.
`per_page`	100	Fino al limite di righe del tuo piano, e lo stesso vale per `page × per_page`: un piano copre le prime N righe di una query e la paginazione non va oltre (`400 page_too_deep`); `/v1/account` lo riporta come `max_per_page`.
`snippets`	disattivato	`1` per includere il testo corrispondente. Consuma la quota degli snippet.
`format`	`json`	Uno dei sei: vedi formati di risposta.
`columns`	dipende dal formato	Sottoinsieme, separato da virgole, di `domain`, `url`, `rank`, `ranked`, `snippets`.
`delimiter`	`;` / tab	Per `csv` e `tsv`.
`header`	disattivato	`1` per aggiungere una riga di intestazione a `csv` e `tsv`.

GET

curl -H "Authorization: Bearer $KEY" \
     "https://api.publicwww.com/v1/search?query=%22angular.min.js%22&page=2&per_page=50"

Ricordati di codificare la query per l'URL. Virgolette, barre e + contano tutti.

POST

Gli stessi parametri in un corpo JSON. Usalo quando la query è lunga o ha più frasi: una query su più righe in un URL si scontra con i limiti di lunghezza di proxy e client molto prima che il server se ne preoccupi.

curl https://api.publicwww.com/v1/search \
     -H "Authorization: Bearer $KEY" \
     -H "Content-Type: application/json" \
     -d '{"query": ["\"angular.min.js\"", "\"bootstrap.min.css\""],
          "per_page": 50,
          "snippets": true}'

Un array di frasi significa tutte quante, esattamente come separarle con un a capo nella stringa query. Nell'esempio qui sopra 278 siti contengono la prima frase e 99 le contengono entrambe.

I tipi JSON vengono riconosciuti: true funziona dove la query string richiede 1. Quando un parametro è presente sia nell'URL sia nel corpo, vince il corpo.

La risposta

Campo	Significato
`total`	Quanti siti corrispondono, nell'intero indice. Un conteggio reale, non una stima.
`total_pages`	`total` diviso per `per_page`, arrotondato per eccesso.
`returned`	Quante righe contiene effettivamente questa pagina.
`truncated`	Se il limite di posizioni visibili del tuo piano ne ha tolta qualcuna.
`took_ms`	Quanto è durata la ricerca, in millisecondi.
`results`	Le righe.

Una riga

Campo	Significato
`domain`	Il sito.
`url`	La pagina in cui è stata trovata la corrispondenza, che per le ricerche con `depth:` non è la home page.
`rank`	Posizione in classifica: più è bassa, più il sito è popolare. `null` quando il sito non ha una posizione.
`ranked`	`false` esattamente quando `rank` è `null`.
`snippets`	Solo con `snippets=1`. Fino a cinque coppie `{"text", "match"}`, dove `match` è ciò che ha trovato corrispondenza e `text` è lo stesso con il contesto circostante.

Paginazione e grandi volumi

Sfoglia le pagine con page, oppure chiedi tutto in una volta con un per_page elevato, fino a max_per_page di /v1/account, che con un piano a pagamento è un milione. Non c'è un endpoint di esportazione separato; la risposta viene scritta man mano che viene costruita, quindi un milione di righe non significa anche un milione di righe tenute in memoria da qualche parte.

Successivo Formati di risposta