# Riferimento API SERP: GET /search e GET /credits > API SERP di SerpCrypto: parametri di GET /search, motori, valori predefiniti, blocchi di risposta, errori e GET /credits, con curl, Python e Node.js. - URL: https://serpcrypto.com/it/docs/search/ - Ultimo aggiornamento: 2026-10-22 - Editore: SerpCrypto (https://serpcrypto.com) 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. **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](https://serpcrypto.com/it/docs/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` ```json { "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 } } ``` *curl* ```bash 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* ```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* ```javascript 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` ```json { "credits_remaining": 84210, "credits_used_today": 1290, "concurrency_limit": 10 } ``` *curl* ```bash curl -s "https://serpcrypto.com/api/v1/credits" \ -H "Authorization: Bearer $SERPCRYPTO_API_KEY" ``` *Python* ```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* ```javascript 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](https://serpcrypto.com/it/docs/errors/) 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](https://serpcrypto.com/it/pricing/). ## 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](https://serpcrypto.com/it/pricing/); 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. --- SerpCrypto: SerpCrypto è un'API SERP per sviluppatori e agenti AI che restituisce i risultati di ricerca di Google e Bing in JSON, con pagamento in criptovalute e senza caricare documenti d'identità. I crediti di ricerca prepagati a partire da 0,30 USD/1K ricerche non scadono mai. Senza KYC — niente documento, niente selfie, niente documenti. Paghi in criptovalute.