# Ricette curl e jq per la web search API

> Web search API con curl e jq: cerca, elenca le fonti, salva le pagine come Markdown, filtra notizie, leggi URL note. Senza KYC.

- URL: https://llmwebsearch.com/it/docs/curl/
- Ultimo aggiornamento: 2026-10-22
- Editore: LLMWebSearch (https://llmwebsearch.com)

Ogni funzione dell'API funziona da terminale. Queste ricette usano `curl` per chiamarla e `jq` per modellare il JSON: utili per testare una query prima di scriverne il codice, per gli shell script e per i cron job.

**Risposta rapida — Come si usa una web search API dalla riga di comando?**

Invia un body JSON con `curl -d` a `https://llmwebsearch.com/api/v1/search`, la tua chiave in un header `Authorization: Bearer`, e passa la risposta a `jq`. **LLMWebSearch** restituisce risultati ordinati con le prime 3 pagine come Markdown, così una sola riga può elencare le fonti o salvare le pagine su file. Una ricerca costa 1 credito, da 1,20 USD/1K ricerche a ottobre 2026. Senza KYC; paghi in criptovalute.

## Come si configura il terminale una volta sola?

Esporta la chiave nella shell, così resta fuori dai comandi che digiti e fuori dalla cronologia. Le ricette qui sotto la leggono come `$LLMWEBSEARCH_API_KEY`. Ti serve anche `jq`, che la maggior parte dei package manager installa con quel nome.

Tutte le ricette presuppongono una shell POSIX come bash o zsh. Su Windows, Git Bash o WSL le eseguono senza modifiche.

*Imposta la chiave e controlla il saldo (gratis)*

```bash
export LLMWEBSEARCH_API_KEY="your-key"

curl -s "https://llmwebsearch.com/api/v1/credits" \
  -H "Authorization: Bearer $LLMWEBSEARCH_API_KEY" | jq .
```

## Come si elencano le fonti di una ricerca?

Esegui la ricerca con `read` impostato a `0` e stampa una riga per risultato: posizione, host e URL. Costa 1 credito e ti mostra, in un secondo, quali fonti tira fuori una domanda. È un buon modo per calibrare la formulazione di una query prima che la usi un agente.

*Una riga per risultato*

```bash
curl -s "https://llmwebsearch.com/api/v1/search" \
  -H "Authorization: Bearer $LLMWEBSEARCH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"q": "postgres connection pool size", "max_results": 10, "read": 0}' \
  | jq -r '.results[] | "\(.position)\t\(.host)\t\(.url)"'
```

## Come si salvano le pagine che sono state lette?

Tieni i risultati il cui `content_status` è `ok` e scrivi ogni `content` nel suo file. La ricetta qui sotto salva `01.md`, `02.md` e così via, ciascuno che inizia con il suo URL di origine. jq seleziona i risultati e il loop della shell scrive i file.

*Salva ogni pagina come Markdown*

```bash
curl -s "https://llmwebsearch.com/api/v1/search" \
  -H "Authorization: Bearer $LLMWEBSEARCH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"q": "postgres connection pool size", "read": 3}' > search.json

jq -r '.results[] | select(.content_status == "ok") | .position' search.json | while read -r pos; do
  jq -r --argjson p "$pos" '.results[] | select(.position == $p) | "Source: " + .url + "\n\n" + .content' \
    search.json > "$(printf '%02d' "$pos").md"
done
ls -1 ./*.md
```

## Come si cercano notizie da alcuni siti?

Aggiungi `topic`, `time_range` e `include_domains` al body. La ricetta tiene le notizie dell'ultima settimana su due domini e stampa la data accanto a ogni titolo, abbastanza per tenere d'occhio un argomento da un cron job.

*Notizie dell'ultima settimana da due domini*

```bash
curl -s "https://llmwebsearch.com/api/v1/search" \
  -H "Authorization: Bearer $LLMWEBSEARCH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"q": "database security release", "topic": "news", "time_range": "week", "include_domains": ["news.example.com", "example.org"], "read": 0}' \
  | jq -r '.results[] | "\(.published_at // "no date")  \(.title)  \(.url)"'
```

## Come si usa la forma GET?

Usa `curl -G` con `--data-urlencode` per la query, così spazi e simboli vengono codificati per te. Le liste come `include_domains` diventano un unico valore separato da virgole. GET è comodo per un test veloce; gli script che crescono dovrebbero passare a POST.

*GET /search*

```bash
curl -sG "https://llmwebsearch.com/api/v1/search" \
  -H "Authorization: Bearer $LLMWEBSEARCH_API_KEY" \
  --data-urlencode "q=pgbouncer transaction mode" \
  -d read=1 -d max_chars=3000 -d include_domains=example.com,example.org \
  | jq -r '.results[0].content // .results[0].snippet'
```

## Come si leggono URL che ho già?

Inviale a `/extract` come array JSON da 1 a 20 indirizzi. Leggere pagine di cui hai già gli URL costa 1 credito per ogni gruppo iniziato di 3 pagine restituite con contenuto, fino a 20 URL per chiamata; gli URL rifiutati o falliti non vengono contati. La ricetta stampa ogni URL con il suo stato e il conteggio delle parole, che mostra a colpo d'occhio quali pagine un sito ci ha permesso di leggere.

*POST /extract*

```bash
curl -s "https://llmwebsearch.com/api/v1/extract" \
  -H "Authorization: Bearer $LLMWEBSEARCH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"urls": ["https://docs.example.com/security/key-rotation", "https://example.com/changelog"]}' \
  | jq -r '"credits: \(.credits_used)", (.results[] | "\(.content_status)\t\(.word_count // 0)\t\(.url)")'
```

## Come vedo l'errore quando una chiamata fallisce?

Stampa lo status HTTP con `-w` e conserva il body: gli errori tornano come JSON con un `code` e un `message`. Uno script può poi diramare sullo status, per esempio aspettando e riprovando solo su `429`, `502` o `504`. Nessuno di questi errori consuma un credito.

*Status code e body dell'errore*

```bash
status=$(curl -s -o body.json -w '%{http_code}' "https://llmwebsearch.com/api/v1/search" \
  -H "Authorization: Bearer $LLMWEBSEARCH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"q": "test query"}')
if [ "$status" != "200" ]; then
  echo "HTTP $status: $(jq -r '.error.code + " - " + .error.message' body.json)"
fi
```

## curl: domande frequenti

### Perché il mio body JSON fallisce con invalid_parameter?

Di solito è un problema di quoting. Racchiudi il body tra apici singoli in bash così le virgolette doppie interne restano intatte, e controllalo con `echo '…' | jq .` prima di inviarlo.

### Posso passare la chiave nell'URL?

Sì, con `-d api_key=…` nella forma GET. L'header è più sicuro, perché la cronologia della shell e i log dei proxy registrano gli URL.

### Una chiamata curl fallita costa un credito?

No. Gli errori HTTP non usano mai crediti. Viene fatturata solo una ricerca che restituisce risultati, come mostra `credits_used`.

---

LLMWebSearch: LLMWebSearch è un'API di ricerca web per agenti AI che restituisce risultati classificati con il contenuto delle pagine principali in Markdown, pagata in criptovalute senza caricare documenti d'identità. I crediti prepagati da 1,20 USD/1K ricerche non scadono mai. Senza KYC — niente documento, niente selfie, niente documenti. Paghi in criptovalute.