Documentazione · Riferimento API · versione 1

Riferimento API SERP: GET /search e GET /credits

Q: Cosa succede quando finisco i crediti?

La ricerca successiva restituisce 402 insufficient_credits e non consuma nulla. Acquista un altro pack dal tuo saldo sulla pagina dei prezzi; la tua chiave resta attiva e le ricerche riprendono subito.

Ogni parametro, valore predefinito e codice di errore della API SerpCrypto, versione 1. URL di base: https://serpcrypto.com/api/v1. Tutte le richieste usano HTTPS; tutte le risposte sono JSON in UTF-8.

Ultimo aggiornamento: 22 ottobre 2026 · 7 min di lettura

Risposta rapida

Quali parametri accetta l'endpoint di ricerca di SerpCrypto?

GET https://serpcrypto.com/api/v1/search accetta un parametro obbligatorio, q, e nove facoltativi: engine, gl, hl, location, google_domain, device, page, safe e period. SerpCrypto restituisce JSON e addebita 1 credito per ogni ricerca andata a buon fine su tutti i 6 motori; gli errori sono gratuiti. I pack partono da 7,50 USD per 10.000 ricerche, pagabili in criptovalute senza KYC.

Come faccio l'autenticazione?

Invia la tua chiave in uno dei due modi. Il modo consigliato è l'header Authorization: Bearer YOUR_KEY. L'altro è il parametro query api_key=YOUR_KEY, comodo per un test rapido in una scheda del browser.

Una chiave mancante, errata o revocata restituisce 401 invalid_api_key e non costa nulla. Chiavi API che puoi creare e revocare in qualsiasi momento dalla tua dashboard, così puoi dare a ogni script o server la propria chiave e revocarne una senza toccare le altre.

Esegui una ricerca

GET/api/v1/search

Esegue una ricerca sul motore scelto e restituisce la pagina dei risultati in JSON. Una ricerca andata a buon fine usa 1 credito, qualunque sia il motore; un errore non ne usa nessuno. I parametri vanno nella query string, con URL encoding. L'esempio chiede a Google i torrefattori di caffè ad Austin, Texas; ID, conteggi e risultati sono illustrativi.

Autenticazione: chiave API nell'header Authorization: Bearer API_KEY.

Parametri

Nome	In	Tipo	Obbligatorio	Descrizione
`q`	query	string	Sì	La query di ricerca, come la digiterebbe una persona. Gli operatori di ricerca come le virgolette o `site:` fanno parte della query.
`engine`	query	string	No	`google` (predefinito), `google_news`, `google_images`, `google_maps`, `google_shopping` o `bing`.
`gl`	query	string	No	Paese dei risultati: codice ISO 3166-1 alpha-2 in minuscolo, come `us`, `de` o `br`. Predefinito `us`.
`hl`	query	string	No	Lingua dell'interfaccia, come `en`, `de` o `pt-BR`. Predefinito `en`.
`location`	query	string	No	Luogo a livello di città, scritto `City, Region, Country`, come `Austin, Texas, United States`. Vedi locations.
`google_domain`	query	string	No	Dominio Google da usare per la ricerca, ad esempio `google.de`. Predefinito: il dominio del paese `gl`. Ignorato quando `engine=bing`.
`device`	query	string	No	`desktop` (predefinito) o `mobile`.
`page`	query	integer	No	Pagina di risultati da 1 (predefinito) a 10. Ogni pagina è una ricerca separata e usa 1 credito.
`safe`	query	string	No	`active` filtra i risultati espliciti; `off` (predefinito) no.
`period`	query	string	No	Solo risultati dall'ultima ora (`h`), giorno (`d`), settimana (`w`), mese (`m`) o anno (`y`).
`api_key`	query	string	No	La tua chiave, se non invii l'header `Authorization`.

Risposta `200`

{
  "search_metadata": {
    "id": "srch_7f3a9c2e41b8",
    "status": "success",
    "engine": "google",
    "created_at": "2026-10-22T09:14:05Z",
    "credits_used": 1
  },
  "search_parameters": {
    "engine": "google",
    "q": "coffee roasters",
    "gl": "us",
    "hl": "en",
    "location": "Austin, Texas, United States",
    "google_domain": "google.com",
    "device": "desktop",
    "page": 1
  },
  "search_information": {
    "total_results": 18600000,
    "query_displayed": "coffee roasters"
  },
  "local_results": [
    {
      "position": 1,
      "title": "Example Coffee Roasters",
      "address": "123 Example St, Austin, TX",
      "rating": 4.7,
      "reviews": 312,
      "type": "Coffee roasters"
    }
  ],
  "organic_results": [
    {
      "position": 1,
      "title": "The 12 best coffee roasters in Austin",
      "link": "https://www.example.com/austin/coffee-roasters",
      "displayed_link": "www.example.com › austin › coffee",
      "snippet": "From light Nordic roasts to dark espresso blends, these local roasters…",
      "date": "Sep 30, 2026"
    },
    {
      "position": 2,
      "title": "Example Roasting Co. | Fresh beans, roasted in Austin",
      "link": "https://www.example.org/",
      "displayed_link": "www.example.org",
      "snippet": "Small-batch coffee roasted every weekday and shipped the same day…"
    }
  ],
  "people_also_ask": [
    {
      "question": "What is the oldest coffee roaster in Austin?",
      "snippet": "…",
      "title": "Austin coffee history",
      "link": "https://www.example.net/austin-coffee-history"
    }
  ],
  "related_searches": [
    {
      "query": "coffee roasters near me"
    },
    {
      "query": "coffee roasters austin wholesale"
    }
  ],
  "pagination": {
    "current": 1,
    "next_page": 2
  }
}

Esempi di codice

curl

curl -sG "https://serpcrypto.com/api/v1/search" \
  -H "Authorization: Bearer $SERPCRYPTO_API_KEY" \
  --data-urlencode "q=coffee roasters" \
  --data-urlencode "location=Austin, Texas, United States" \
  -d gl=us -d hl=en -d device=desktop

Python

import os

import requests

r = requests.get(
    "https://serpcrypto.com/api/v1/search",
    params={
        "q": "coffee roasters",
        "location": "Austin, Texas, United States",
        "gl": "us",
        "hl": "en",
    },
    headers={"Authorization": "Bearer " + os.environ["SERPCRYPTO_API_KEY"]},
    timeout=60,
)
r.raise_for_status()
print(r.json()["organic_results"][0]["link"])

Node.js

const params = new URLSearchParams({
  q: "coffee roasters",
  location: "Austin, Texas, United States",
  gl: "us",
  hl: "en",
});
const res = await fetch("https://serpcrypto.com/api/v1/search?" + params, {
  headers: { Authorization: "Bearer " + process.env.SERPCRYPTO_API_KEY },
});
const data = await res.json();
console.log(data.organic_results?.[0]?.link);

Quali valori esistono per engine e cosa restituisce ciascuno?

La struttura (search_metadata, search_parameters, search_information) è la stessa su ogni engine. Un blocco compare solo quando la pagina lo mostra.

`engine`	Fonte	Blocchi principali nella risposta
`google`	Google Search	`ai_overview`, `organic_results`, `ads`, `people_also_ask`, `local_results`, `knowledge_graph`, `top_stories`, `inline_videos`, `shopping_results`, `related_searches`, `pagination`
`google_news`	Google News	`news_results`: titolo, link, fonte, data, snippet, miniatura
`google_images`	Google Images	`images_results`: URL originale e dimensioni, miniatura, pagina di origine
`google_maps`	Google Maps	`local_results`: nome, indirizzo, telefono, sito web, valutazione, recensioni, categoria, orari, coordinate
`google_shopping`	Google Shopping	`shopping_results`: titolo, prezzo, prezzo estratto, valuta, venditore, consegna, valutazione
`bing`	Bing	`organic_results`, `related_searches`

Leggi i tuoi crediti

GET/api/v1/credits

Restituisce i crediti rimasti sul tuo account, i crediti usati dalla mezzanotte UTC e il numero di ricerche che il tuo account può eseguire contemporaneamente. Questa chiamata è gratuita. I valori qui sotto sono esempi.

Autenticazione: chiave API nell'header Authorization: Bearer API_KEY.

Risposta `200`

{
  "credits_remaining": 84210,
  "credits_used_today": 1290,
  "concurrency_limit": 10
}

Esempi di codice

curl

curl -s "https://serpcrypto.com/api/v1/credits" \
  -H "Authorization: Bearer $SERPCRYPTO_API_KEY"

Python

import os

import requests

r = requests.get(
    "https://serpcrypto.com/api/v1/credits",
    headers={"Authorization": "Bearer " + os.environ["SERPCRYPTO_API_KEY"]},
    timeout=30,
)
r.raise_for_status()
print(r.json()["credits_remaining"])

Node.js

const res = await fetch("https://serpcrypto.com/api/v1/credits", {
  headers: { Authorization: "Bearer " + process.env.SERPCRYPTO_API_KEY },
});
const { credits_remaining } = await res.json();
console.log(credits_remaining);

Quali errori può restituire l'API?

Ogni errore ha il body {"error": {"code": "…", "message": "…"}}. La pagina degli errori spiega ciascuno e mostra il codice di retry.

HTTP	`code`	Quando succede	Addebitato
400	`invalid_parameter`	Manca un parametro obbligatorio o un valore è fuori dall'elenco consentito	No
401	`invalid_api_key`	La chiave è mancante, sbagliata o revocata	No
402	`insufficient_credits`	Sul tuo account non restano crediti	No
429	`concurrency_limit`	Sul tuo account sono in esecuzione troppe ricerche contemporaneamente	No
502	`search_failed`	L'engine o la raccolta non è riuscito per questa richiesta; riprova	No
504	`search_timeout`	Nessuna risposta in tempo; riprova	No

Cosa viene addebitato, esattamente?

Una ricerca riuscita = un credito, su ogni engine, compresi Google Maps e Google Shopping.
Ogni pagina di risultati è una ricerca. Circa 10 risultati organici per pagina, come Google serve da quando ha smesso di rispettare num=100 a settembre 2025; ogni pagina in più costa un altro credito.
Gli errori sono gratuiti: ogni risposta con uno status HTTP diverso da 200 non usa crediti.
Leggere i tuoi crediti è gratuito.

I crediti di ricerca prepagati non scadono mai: le ricerche non utilizzate restano sul tuo account finché non le usi. I pack vanno da 7,50 USD per 10.000 ricerche a 0,30 USD/1K ricerche sul più grande; vedi prezzi.

Come devo codificare la query?

Invia q codificata per URL, come qualsiasi valore di query string: uno spazio diventa %20 o +, e le lettere accentate vengono codificate come UTF-8. curl lo fa con --data-urlencode, Python requests e httpx lo fanno con params=, mentre Node.js lo fa con URLSearchParams.

Scrivi la query esattamente come la digiterebbe una persona nella casella di ricerca. Le virgolette, il segno meno o site: restano dentro q; è l'engine a decidere come applicarli, come farebbe per un visitatore.

L'API è versionata?

Sì. La versione fa parte del path: /api/v1/. Nuovi campi o blocchi possono comparire nelle risposte della versione 1, quindi il tuo codice dovrebbe ignorare le chiavi che non conosce. Rimuovere o rinominare un campo arriverebbe con una nuova versione nel path, non come modifica a v1.

Domande di riferimento sull'API

Posso inviare una richiesta POST con un corpo JSON?

Non nella versione 1: entrambi gli endpoint accettano richieste GET con i parametri nella query string. Così ogni chiamata è facile da riprodurre con curl o in un browser e da registrare nei log senza il corpo.

Quanti risultati restituisce una ricerca?

Circa 10 risultati organici per pagina, come Google serve da quando ha smesso di rispettare num=100 a settembre 2025; ogni pagina in più costa un altro credito. Per raccogliere 30 risultati, richiedi page=1, page=2 e page=3: tre ricerche, tre crediti.

Cosa succede quando finisco i crediti?

La ricerca successiva restituisce 402 insufficient_credits e non consuma nulla. Acquista un altro pack dal tuo saldo sulla pagina dei prezzi; la tua chiave resta attiva e le ricerche riprendono subito.

Posso usare la stessa chiave da più server?

Sì. Una chiave non è legata a un indirizzo IP. Ciò che è limitato è il numero di ricerche in esecuzione contemporaneamente sull'account: concurrency_limit su GET /credits riporta la cifra.

Come faccio l'autenticazione?

Esegui una ricerca

Parametri

Risposta 200

Esempi di codice

Quali valori esistono per engine e cosa restituisce ciascuno?

Leggi i tuoi crediti

Risposta 200

Esempi di codice

Quali errori può restituire l'API?

Cosa viene addebitato, esattamente?

Come devo codificare la query?

L'API è versionata?

Domande di riferimento sull'API

Posso inviare una richiesta POST con un corpo JSON?

Quanti risultati restituisce una ricerca?

Cosa succede quando finisco i crediti?

Posso usare la stessa chiave da più server?

Pagine correlate

Risposta `200`

Risposta `200`