SimilarwebAPI | Documentazione API

SimilarwebAPI offre 27 endpoint di dati in sola lettura sotto /v1/similarweb. Usa lo stesso account, chiave API, credito e cronologia di utilizzo delle altre API RequestBeam. La disponibilità dipende da un gateway abilitato e dai permessi della chiave API; la documentazione non conferma la disponibilità in produzione.

Autenticazione

Invia la tua chiave API RequestBeam, non credenziali di terze parti:

http

Authorization: Bearer YOUR_API_KEY

Esempio di richiesta

Tutte le operazioni pubbliche usano GET con parametri di query e senza corpo della richiesta. Mantieni esattamente le maiuscole e minuscole documentate per percorsi e parametri.

Sono supportati solo dati mondiali (country=999). Gli altri valori di paese validi vengono sostituiti con 999 prima della richiesta al fornitore e restituiscono dati mondiali, non del paese indicato.

Negli endpoint che accettano date, un intervallo esplicito from/to valido e completo ha la precedenza. Se l'endpoint accetta latest, il valore fornito deve comunque superare le convalide esistenti del formato e dell'endpoint, ma viene ignorato nella selezione dell'intervallo e non inviato a Similarweb; non viene aggiunto alcun latest predefinito. Senza un intervallo esplicito, il comportamento esistente di latest, valori predefiniti e finestre resta invariato. Restano valide le restrizioni di History; gli endpoint che non accettano latest continuano a rifiutarlo.

bash

curl --get "https://api.apihop.ai/v1/similarweb/websites/incoming-referrals" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  --data-urlencode "key=example.com" \
  --data-urlencode "country=999" \
  --data-urlencode "page=1"

I referral in entrata usano un singolo nome host nel parametro minuscolo key, non keys. Questo key è un parametro di query applicativo per il sito di destinazione, non una credenziale API; è consentito solo nelle route GET Similarweb esplicitamente autorizzate. L’autenticazione API usa ancora Authorization e gli altri campi di credenziali nella query restano vietati. Le righe vengono restituite in Records, non in Data. Consulta il riferimento completo degli endpoint per i campi esatti di ogni operazione.

Copertura

Ricerca: suggerimenti di parole chiave, pagine in classifica, parole chiave dei siti, ricerca organica e a pagamento, parole chiave di marca.
Traffico dei siti: coinvolgimento, visite, geografia, distribuzione dei dispositivi, canali e traffico social.
Relazioni: backlink, referral in entrata, traffico in uscita e siti simili.
Cronologia: serie separate di visite mensili, frequenza di rimbalzo, durata delle visite e pagine per visita.

Risposte

Le risposte riuscite conservano il corpo JSON nativo, senza un nuovo involucro success/data. Nomi dei campi, campi sconosciuti, array vuoti e precisione numerica restano invariati. I diversi endpoint possono restituire Data, Records o un’altra struttura nativa; non presumere un campo universale per le righe.

Un risultato riuscito ma vuoto non significa che il dominio non abbia traffico. Le richieste fallite non devono essere trattate come dati vuoti. Conserva X-Request-Id e l’ora della richiesta per la diagnosi.

Fatturazione e paginazione

Il prezzo standard è $0.0005 per richiesta riuscita, oppure $0.50 per 1,000 richieste, per tutti i 27 endpoint. Si fattura per richiesta, non per riga; un risultato vuoto riuscito conta comunque come una richiesta. Ogni pagina successiva è una richiesta separata. I prezzi specifici dell’account hanno la precedenza, se configurati. Le richieste con parametri non validi, autorizzazione mancante o credito insufficiente non procedono come chiamate riuscite fatturabili. Le richieste fallite presso il fornitore a monte non vengono addebitate.

Prima di una chiamata, il tuo account deve avere almeno $0.10 disponibili, come richiesto dalla politica di credito minimo della piattaforma. La tariffa standard rimane $0.0005 per richiesta riuscita.

Usa solo i campi di paginazione documentati per l’endpoint selezionato. La numerazione parte generalmente da 1; i backlink usano Page e PageSize, mentre altre tabelle possono usare page, pageSize o rowsPerPage. Non inviare campi di dimensione pagina non supportati.

Errori

Gli errori della piattaforma hanno la struttura seguente; code è un codice applicativo della piattaforma, non uno stato HTTP:

json

{"success":false,"error":{"code":10000,"message":"Invalid request parameters"},"requestId":"..."}

Gli stati HTTP comuni includono 400 query non valida, 401 chiave API non valida, 402 credito insufficiente, 403 accesso al gateway negato, 429 limite di frequenza e 5xx errore temporaneo del fornitore o del servizio. Non ripetere richieste malformate senza modificarle.