Accedi Prova gratuita
Deutsch English Español Français Italiano Português 日本語
Prova gratuita Accedi
  • Per iniziare
  • Avvio rapido
  • Informazioni
  • Limiti di chiamata
  • Versioni di Google
  • Elenco delle versioni
  • SERP
  • Query di ricerca su Google
  • Query di Google Maps
  • ID della query
  • Recupero delle SERP
  • URL di richiamo
  • Stato di elaborazione delle SERP
  • Cronologia delle query
  • Fatturazione
  • Credito residuo
  • Metodi di pagamento

Documentazione API di Semscraper

Avvio rapido

Tre passaggi per ottenere la tua prima SERP Google in JSON.

  1. Crea il tuo account: 1.000 SERP sono gratuite, senza carta di credito. Poi copia la tua chiave dal menu Chiavi API del tuo account. Va inviata nell'header Authorization: Bearer di ogni chiamata. Crea un account gratuito
  2. Invia le tue parole chiave con POST /v1/serp, fino a 1.000 per chiamata. La risposta restituisce l'identificativo e il costo di ogni SERP: è l'unico momento in cui ti viene addebitato.
    Inviare una parola chiave
    curl -X POST https://api.semscraper.com/v1/serp \
  -H "Authorization: Bearer LA_TUA_CHIAVE_API" \
  -H "Content-Type: application/json" \
  -d '[{"search_engine": "google_search", "keyword": "ricetta crepes", "device": "desktop", "location": "it", "language": "it", "depth": 1}]'
  3. Recupera il risultato con GET /v1/serp e l'identificativo ricevuto: sostituisci SERP_ID con il valore del campo data[0].id restituito nel passaggio precedente.La raccolta è asincrona: finché lo stato è pending o processing, riprova un po' più tardi. Il recupero non viene mai addebitato.
    Recuperare la SERP
    curl "https://api.semscraper.com/v1/serp?ids=SERP_ID&output=json" \
  -H "Authorization: Bearer LA_TUA_CHIAVE_API"

Per ricevere un avviso senza interrogare l'API, aggiungi un callback_url alle tue richieste. Per centinaia di migliaia di parole chiave, consulta la Bulk SERP API.

Informazioni

Limiti di chiamata

Limite al numero di chiamate API
GET : 500 chiamate al minuto
POST : 500 chiamate al minuto

Versioni di Google

Elenco delle versioni

Ottenere i parametri località e lingua necessari per recuperare le SERP di Google.
get
https://api.semscraper.com/v1/serp/google/location
Autorizzazioni : Bearer {api_key}
  • Richiesta
  • Risposta positiva
Status: 200 OK
{
    "status": "success",
    "request_ms": 17,
    "count": 372,
    "data": [
        {
            "location": "en",
            "language": "en",
            "host": "google.com",
            "name": "World Wide Web"
        },
        {
            "location": "fr",
            "language": "fr",
            "host": "google.fr",
            "name": "France"
        }
}

SERP

Query di ricerca su Google

Creazione di query per le SERP di Google Search
I dati devono essere inviati in un array JSON. Ogni elemento deve contenere i seguenti campi.
Limite
L'array JSON può contenere 1000 elementi, quindi è possibile creare 1000 scrapes di SERP con una sola chiamata.
post
https://api.semscraper.com/v1/serp
Autorizzazioni : Bearer {api_key}
Parametri
search_engine
Richiesto
string
Scelta del motore di ricerca :
Ricerca Google (valore: google_search)
keyword
Richiesto
string
Parole chiave da cercare sul motore di ricerca
device
Richiesto
string
Dispositivo:
Computer (valore: desktop)
Mobile (valore: mobile)
depth
Richiesto
integer
Profondità della pagina, recuperiamo le SERP di Google con paginazione. Questo parametro deve essere compreso tra 1 (circa 10 risultati) e 10 (circa 100 risultati).
location
Richiesto
string
Codice di localizzazione del motore di ricerca
language
Richiesto
string
Lingua dei motori di ricerca
geolocation
string
Geolocalizza una SERP di Google. Indica città, regione e paese separati da virgole (es.: Nice, Alpes-Maritimes, France) oppure una posizione GPS latitudine,longitudine in gradi decimali (es.: 43.7102,7.2620).
priority
integer
Utilizzato per dare priorità alle richieste, che vengono elaborate in ordine decrescente di priorità. Valore compreso tra 1 (basso) e 10 (alto).
callback_url
string
Consente di specificare un URL a cui inviare i risultati per la parola chiave una volta elaborati.
Tipi di blocchi dei risultati
Valori possibili del campo type. Un blocco è presente nella risposta solo se Google lo mostra per la parola chiave richiesta.
Risultati e annunci
organic
Risultato organico
Risultato organico standard della ricerca.
sitelinks
Sitelink
Link secondario associato a un risultato organico.
paid_top
Annuncio in alto
Annuncio a pagamento sopra i risultati organici.
paid_bottom
Annuncio in basso
Annuncio a pagamento sotto i risultati organici.
Blocchi arricchiti
featured_snippet
Snippet in primo piano
Estratto in evidenza sopra i risultati organici.
knowledge_graph
Knowledge panel
Elemento del pannello mostrato a destra della SERP.
images
Immagini
Miniatura del blocco immagini.
videos
Video
Video del blocco video.
top_stories
Notizie principali
Articolo del blocco Notizie principali.
shopping
Shopping
Prodotto del carosello di Google Shopping.
recipes
Ricette
Ricetta del blocco ricette.
local_pack
Local pack
Attività del local pack, proveniente da Google Maps.
visual_digest
Riepilogo visivo
Elemento del riepilogo visivo generato da Google.
Suggerimenti e approfondimenti
people_also_ask
Altre domande
Domanda del blocco Altre domande.
related_searches
Ricerche correlate
Ricerca correlata suggerita in fondo alla pagina.
find_results_on
Trova risultati su
Link del blocco Trova risultati su.
location_sites
Siti locali
Sito elencato in un blocco legato a una località.
AI Overview
ai_overview_citation
Citazione
Brand citato nel testo generato dall'IA.
ai_overview_citation_source
Fonte della citazione
Fonte di una citazione, visibile al passaggio del mouse su di essa.
ai_overview_panel
Pannello delle fonti
Sito elencato nel pannello laterale delle fonti.
  • Richiesta
  • Risposta positiva
  • Risposta all'errore
Status: 200 OK
{
    "status": "success",
    "request_ms": 40,
    "count": 1,
    "currency": "EUR",
    "total_cost": 0.0003,
    "data": [
        {
            "id": "SERP_ID",
            "status": "pending",
            "keyword": "example keyword",
            "device": "mobile",
            "location": "fr",
            "language": "fr",
            "depth": 1,
            "geolocation": false,
            "priority": 1,
            "callback_url": null,
            "cost": 0.0003,
            "_links": {
                "json": {
                    "href": "/serp?ids=SERP_ID&output=json",
                    "method": "GET",
                    "type": "application/json"
                },
                "html": {
                    "href": "/serp?ids=SERP_ID&output=html",
                    "method": "GET",
                    "type": "application/json"
                }
            }
        }
    ]
}
Status: 400 Bad Request
{
    "error": "Bad Request",
    "message": "DESCRIPTION_OF_ERROR",
    "code": 400
}

Query di Google Maps

Creazione di query per le SERP di Google Maps
I dati devono essere inviati in un array JSON. Ogni elemento deve contenere i seguenti campi.
Limite
L'array JSON può contenere 1000 elementi, quindi è possibile creare 1000 scrapes di SERP con una sola chiamata.
post
https://api.semscraper.com/v1/serp
Autorizzazioni : Bearer {api_key}
Parametri
search_engine
Richiesto
string
Scelta del motore di ricerca :
Google Maps (valore: google_maps)
keyword
Richiesto
string
Parole chiave da cercare sul motore di ricerca
depth
Richiesto
integer
Profondità della pagina, recuperiamo le SERP di Google con paginazione. Questo parametro deve essere compreso tra 1 (circa 10 risultati) e 10 (circa 100 risultati).
location
Richiesto
string
Codice di localizzazione del motore di ricerca
language
Richiesto
string
Lingua dei motori di ricerca
geolocation
string
Geolocalizza una SERP di Google. Indica città, regione e paese separati da virgole (es.: Nice, Alpes-Maritimes, France) oppure una posizione GPS latitudine,longitudine in gradi decimali (es.: 43.7102,7.2620). Con una posizione GPS puoi aggiungere un livello di zoom facoltativo (es.: 43.7102,7.2620,16z).
priority
integer
Utilizzato per dare priorità alle richieste, che vengono elaborate in ordine decrescente di priorità. Valore compreso tra 1 (basso) e 10 (alto).
callback_url
string
Consente di specificare un URL a cui inviare i risultati per la parola chiave una volta elaborati.
  • Richiesta
  • Risposta positiva
  • Risposta all'errore
Status: 200 OK
{
    "status": "success",
    "request_ms": 40,
    "count": 1,
    "currency": "EUR",
    "total_cost": 0.0003,
    "data": [
        {
            "id": "SERP_ID",
            "status": "pending",
            "keyword": "example keyword",
            "device": "mobile",
            "location": "fr",
            "language": "fr",
            "depth": 1,
            "geolocation": false,
            "priority": 1,
            "callback_url": null,
            "cost": 0.0003,
            "_links": {
                "json": {
                    "href": "/serp?ids=SERP_ID&output=json",
                    "method": "GET",
                    "type": "application/json"
                },
                "html": {
                    "href": "/serp?ids=SERP_ID&output=html",
                    "method": "GET",
                    "type": "application/json"
                }
            }
        }
    ]
}
Status: 400 Bad Request
{
    "error": "Bad Request",
    "message": "DESCRIPTION_OF_ERROR",
    "code": 400
}

ID della query

Elenco di identificatori (ID) per le SERP completate che non sono ancora state recuperate.
Questo metodo consente di ottenere gli ID di tutte le SERP già elaborate ma non ancora recuperate. È quindi possibile richiamare il metodo di recupero delle SERP utilizzando questi ID.
get
https://api.semscraper.com/v1/serp
Autorizzazioni : Bearer {api_key}
  • Richiesta
  • Risposta positiva
Status: 200 OK
{
    "status": "success",
    "request_ms": 40,
    "count": 2,
    "data": [
        {
            "id": "SERP_ID",
            "status": "done",
            "keyword": "example keyword",
            "device": "desktop",
            "location": "fr",
            "language": "fr",
            "depth": 5,
            "geolocation": false,
            "callback_url": "",
            "cost": 0.0011,
            "_links": {
                "json": {
                    "href": "/serp?ids=SERP_ID&output=json",
                    "method": "GET",
                    "type": "application/json"
                },
                "html": {
                    "href": "/serp?ids=SERP_ID&output=html",
                    "method": "GET",
                    "type": "application/json"
                }
            }
        },
        {
            "id": "SERP_ID",
            "status": "done",
            "keyword": "example keyword",
            "device": "mobile",
            "location": "fr",
            "language": "fr",
            "depth": 5,
            "geolocation": false,
            "callback_url": "",
            "cost": 0.0011,
            "_links": {
                "json": {
                    "href": "/serp?ids=SERP_ID&output=json",
                    "method": "GET",
                    "type": "application/json"
                },
                "html": {
                    "href": "/serp?ids=SERP_ID&output=html",
                    "method": "GET",
                    "type": "application/json"
                }
            }
        }
    ]
}

Recupero delle SERP

Recuperare le SERP di Google tramite i loro ID
Recuperare diverse SERP in un'unica chiamata (in formato JSON o HTML) fornendo diversi ID separati da una virgola.
Limite
È possibile specificare un massimo di 100 ID, consentendo di recuperare 100 SERP in un'unica chiamata.
get
https://api.semscraper.com/v1/serp?ids=id1,id2&output=json
Autorizzazioni : Bearer {api_key}
Parametri
ids
Richiesto
string
Elenco di ID separati da una virgola.
output
Richiesto
string
Scelta del formato di uscita :
JSON (valore: json)
HTML (valore: html)
Formato dei risultati
  • Google Search
  • Google Maps
type
string
Tipo di blocco dei risultati (organico, video, immagini, people_also_ask, local_pack...)
rank_type
integer
Posizione dell'elemento all'interno del proprio tipo di blocco (es.: terzo risultato organico = 3)
rank_serp
integer
Posizione assoluta nella SERP completa, considerando tutti i blocchi, in base alla posizione verticale effettiva sulla pagina (al pixel)
page
integer
Numero della pagina della SERP in cui compare l'elemento
pixel
integer
Posizione verticale dell'elemento sulla pagina, in pixel dalla parte superiore
domain
string
Dominio dell'URL
url
string
URL del risultato
title
string
Titolo visualizzato del risultato
description
string
Descrizione / estratto visualizzato del risultato
brand
string
Brand citato, oppure etichetta della fonte così come la mostra Google. Solo nei blocchi ai_overview_citation, ai_overview_citation_source e ai_overview_panel. In una citazione l'URL è spesso vuoto: il brand è quindi l'unica informazione dell'elemento.
visible
boolean
Indica se l'elemento è mostrato subito nell'AI Overview (true) o solo dopo averlo espanso (false). Solo nei blocchi AI Overview. Sempre false per ai_overview_citation_source, che compare al passaggio del mouse su una citazione.
rating
float
Valutazione media mostrata da Google (es.: 4.1). Solo nei blocchi organic e local_pack, null se il risultato non mostra stelle.
reviews
integer
Numero di recensioni su cui si basa la valutazione. Solo nei blocchi organic e local_pack, null se il risultato non mostra stelle.
price_range
string
Fascia di prezzo dell'attività così come la mostra Google (es.: «20–30 €»). Solo nel blocco local_pack, null se assente.
details
array
Informazioni mostrate sotto l'attività, nell'ordine e nella lingua di Google: prezzo, categoria, indirizzo, orari, servizi… Solo nel blocco local_pack. Né l'ordine né la presenza di ciascuna informazione sono garantiti.
serp_info.ai_overview
object
AI Overview della SERP, nell'oggetto serp_info (non in results). Contiene type, text e complete.
serp_info.ai_overview.type
string
Modalità di visualizzazione dell'AI Overview: sync (presente nella pagina fin dal caricamento), async (generato da Google al momento, dopo il caricamento della pagina) oppure none (nessun AI Overview).
serp_info.ai_overview.text
string
Testo generato dall'IA, in testo semplice (senza formattazione né link). null se la SERP non ha un AI Overview o se il testo non è stato letto.
serp_info.ai_overview.complete
boolean
True se l'AI Overview aveva terminato la generazione al momento dell'acquisizione. false se il testo è assente o potrebbe essere incompleto.
rank_type
integer
Posizione dell'elemento all'interno del proprio tipo di blocco (es.: terzo risultato organico = 3)
rank_serp
integer
Posizione assoluta nella SERP completa, considerando tutti i blocchi, in base alla posizione verticale effettiva sulla pagina (al pixel)
page
integer
Numero della pagina della SERP in cui compare l'elemento
pixel
integer
Posizione verticale dell'elemento sulla pagina, in pixel dalla parte superiore
title
string
Titolo visualizzato del risultato
cid
string
ID Google (CID) della scheda dell'istituto
reviews
integer
Numero di recensioni
rating
float
Valutazione media su 5
website
string
Sito web dell'istituto
type
string
Categoria della struttura (ad es.: Ristorante)
address
string
Indirizzo postale
status_label
string
Stato di apertura (ad es.: Aperto, Chiuso)
status_detail
string
Dettagli dello stato (ad es.: orari)
comment
string
Commento / estratto visualizzato
images
array
Elenco delle immagini della scheda
  • Richiesta
  • Risposta positiva
  • Risposta all'errore
Status: 200 OK
{
    "status": "success",
    "request_ms": 41,
    "count": 1,
    "data": [
        {
            "id": "SERP_ID",
            "status": "done",
            "keyword": "example keyword",
            "device": "desktop",
            "location": "fr",
            "language": "fr",
            "depth": 1,
            "geolocation": false,
            "priority": 1,
            "callback_url": "",
            "cost": 0.0003,
            "created_at": "2025-09-10T12:32:56Z",
            "scraped_at": "2025-09-10T12:33:02Z",
            "duration_ms": 5403,
            "serp_info": {
                "result_count": 1500000000,
                "ai_overview": {
                    "type": "async",
                    "text": "A keyword is a word or phrase that users type into a search engine to find information...",
                    "complete": true
                }
            },
            "results": [
                {
                    "type": "people_also_ask",
                    "items": [
                        {
                            "rank_type": 1,
                            "rank_serp": 4,
                            "page": 1,
                            "pixel": 806,
                            "domain": "guides.lib.uh.edu",
                            "url": "https://guides.lib.uh.edu/c.php?g\\x3d1249281",
                            "title": "What is a keyword example?",
                            "description": ""
                        },
                        {
                            "rank_type": 2,
                            "rank_serp": 5,
                            "page": 1,
                            "pixel": 858,
                            "domain": "toolsqa.com",
                            "url": "https://toolsqa.com/cucumber/data-driven-testing-using-examples-keyword/",
                            "title": "What is the example keyword used for?",
                            "description": ""
                        },
                        {
                            "rank_type": 3,
                            "rank_serp": 6,
                            "page": 1,
                            "pixel": 911,
                            "domain": "www.editage.com",
                            "url": "https://www.editage.com/insights/how-to-create-keywords-for-a-research-paper",
                            "title": "How do you write keywords examples?",
                            "description": ""
                        },
                        {
                            "rank_type": 4,
                            "rank_serp": 7,
                            "page": 1,
                            "pixel": 964,
                            "domain": "libguides.lvc.edu",
                            "url": "https://libguides.lvc.edu/c.php?g\\x3d1152118\\x26ampp\\x3d8409030",
                            "title": "What is an example of a keyword search?",
                            "description": ""
                        }
                    ]
                },
                {
                    "type": "videos",
                    "items": [
                        {
                            "rank_type": 1,
                            "rank_serp": 1,
                            "page": 1,
                            "pixel": 223,
                            "domain": "www.youtube.com",
                            "url": "https://www.youtube.com/watch?v=H-B5oFJjL8I",
                            "title": "What are Keywords and How to Choose Them? 1.1. SEO ...",
                            "description": ""
                        },
                        {
                            "rank_type": 2,
                            "rank_serp": 2,
                            "page": 1,
                            "pixel": 374,
                            "domain": "www.youtube.com",
                            "url": "https://www.youtube.com/watch?v=TTlEVVB75wo&pp=2AEAkAIB",
                            "title": "What Are Keywords? Everything You Need To Know (and more)",
                            "description": ""
                        },
                        {
                            "rank_type": 3,
                            "rank_serp": 3,
                            "page": 1,
                            "pixel": 526,
                            "domain": "www.youtube.com",
                            "url": "https://www.youtube.com/watch?v=OMJQPqG2Uas",
                            "title": "Keyword Research Tutorial: From Start to Finish",
                            "description": ""
                        }
                    ]
                },
                {
                    "type": "organic",
                    "items": [
                        {
                            "rank_type": 1,
                            "rank_serp": 8,
                            "page": 1,
                            "pixel": 1077,
                            "domain": "www.seoquantum.com",
                            "url": "https://www.seoquantum.com/en/blog/6-types-keywords-organic-seo",
                            "title": "The 6 Types of Keywords in Organic SEO",
                            "description": "2 mars 2024 — I will introduce you to 6 types of keywords that you absolutely need to know. We will start with the most common ones such as long-tail keywords and then move ...",
                            "rating": null,
                            "reviews": null
                        },
                        {
                            "rank_type": 2,
                            "rank_serp": 9,
                            "page": 1,
                            "pixel": 1223,
                            "domain": "storychief.io",
                            "url": "https://storychief.io/blog/seo-keyword-research-examples",
                            "title": "10 Clever SEO Keyword Research Examples",
                            "description": "Let's say you run a food blog. Some potential SEO keywords could be: quick weeknight dinners easy dinner recipes 30 minute meals one pot dinners",
                            "rating": null,
                            "reviews": null
                        },
                        {
                            "rank_type": 3,
                            "rank_serp": 10,
                            "page": 1,
                            "pixel": 1369,
                            "domain": "www.indeed.com",
                            "url": "https://www.indeed.com/career-advice/career-development/types-of-keywords",
                            "title": "19 Types of Keywords",
                            "description": "6 juin 2025 — 19 types of keywords and how to use them for marketing · 1. Market segment keywords · 2. Customer-defining keywords · 3. Product-defining ...",
                            "rating": null,
                            "reviews": null
                        },
                        {
                            "rank_type": 4,
                            "rank_serp": 11,
                            "page": 1,
                            "pixel": 1515,
                            "domain": "www.usg.edu",
                            "url": "https://www.usg.edu/galileo/skills/unit04/primer04_07.phtml",
                            "title": "Keyword Search",
                            "description": "In this case, the phrase alternative fuels and automobiles are the significant keywords.",
                            "rating": null,
                            "reviews": null
                        },
                        {
                            "rank_type": 5,
                            "rank_serp": 12,
                            "page": 1,
                            "pixel": 1639,
                            "domain": "guides.lib.uh.edu",
                            "url": "https://guides.lib.uh.edu/c.php?g=1249281",
                            "title": "What are keywords and why are they important? - Guides",
                            "description": "You probably used the title of the film and the word “showtimes” as your keywords to bring up the results you needed. Keywords in academic research are similar.",
                            "rating": null,
                            "reviews": null
                        },
                        {
                            "rank_type": 6,
                            "rank_serp": 13,
                            "page": 1,
                            "pixel": 1785,
                            "domain": "www.tactee.fr",
                            "url": "https://www.tactee.fr/seo/strategie-seo/keyword-seo/",
                            "title": "Qu'est ce qu'un keyword SEO ? [Définition & conseil]",
                            "description": "13 juil. 2024 — Commerciale : l'utilisateur compare des produits ou des services, par exemple « meilleur smartphone 2024 ». Identifier l'intention de recherche ...",
                            "rating": null,
                            "reviews": null
                        },
                        {
                            "rank_type": 7,
                            "rank_serp": 14,
                            "page": 1,
                            "pixel": 1931,
                            "domain": "backlinko.com",
                            "url": "https://backlinko.com/types-of-keywords",
                            "title": "10 Types of Keywords with Examples (+ How to Find Them)",
                            "description": "15 mai 2025 — 10 Types of Keywords with Examples (+ How to Find Them) · 1. Seed Keywords · 2. Informational Keywords · 3. Commercial Keywords · 4.",
                            "rating": null,
                            "reviews": null
                        },
                        {
                            "rank_type": 8,
                            "rank_serp": 15,
                            "page": 1,
                            "pixel": 2077,
                            "domain": "learn.microsoft.com",
                            "url": "https://learn.microsoft.com/en-us/dotnet/csharp/language-reference/keywords/",
                            "title": "C# Keywords and contextual keywords - C# reference",
                            "description": "17 avr. 2025 — For example, @if is a valid identifier, but if isn't because if is a keyword. The first table in this article lists keywords that are ...",
                            "rating": null,
                            "reviews": null
                        }
                    ]
                },
                {
                    "type": "local_pack",
                    "items": [
                        {
                            "rank_type": 1,
                            "rank_serp": 19,
                            "page": 1,
                            "pixel": 2520,
                            "domain": "lebistrotm.fr",
                            "url": "https://lebistrotm.fr/",
                            "title": "Le Bistrot M",
                            "description": "",
                            "rating": 4.6,
                            "reviews": 220,
                            "price_range": "20–30 €",
                            "details": [
                                "20–30 €",
                                "Restaurant",
                                "1 Pl. Xavier Taillade",
                                "Fermé",
                                "Ouvre à 18:30",
                                "Repas sur place",
                                "Aucun plat à emporter",
                                "Pas de livraison"
                            ]
                        },
                        {
                            "rank_type": 2,
                            "rank_serp": 20,
                            "page": 1,
                            "pixel": 2661,
                            "domain": "www.domainedesoliviers.fr",
                            "url": "http://www.domainedesoliviers.fr/",
                            "title": "Domaine des Oliviers",
                            "description": "",
                            "rating": 4.5,
                            "reviews": 1600,
                            "price_range": null,
                            "details": [
                                "Française",
                                "4 All. Paul Emile d'Allard",
                                "Fermé",
                                "Ouvre à 19:00",
                                "Hôtel discret avec piscine et restaurant"
                            ]
                        }
                    ]
                },
                {
                    "type": "images",
                    "items": [
                        {
                            "rank_type": 1,
                            "rank_serp": 16,
                            "page": 1,
                            "pixel": 2311,
                            "domain": "searchfacts.com",
                            "url": "https://searchfacts.com/what-are-keywords-in-seo/",
                            "title": "",
                            "description": ""
                        },
                        {
                            "rank_type": 2,
                            "rank_serp": 17,
                            "page": 1,
                            "pixel": 2311,
                            "domain": "backlinko.com",
                            "url": "https://backlinko.com/hub/seo/seo-keywords",
                            "title": "",
                            "description": ""
                        },
                        {
                            "rank_type": 3,
                            "rank_serp": 18,
                            "page": 1,
                            "pixel": 2311,
                            "domain": "ahrefs.com",
                            "url": "https://ahrefs.com/blog/what-are-keywords/",
                            "title": "",
                            "description": ""
                        }
                    ]
                }
            ]
        }
    ]
}
Status: 400 Bad Request
{
    "error": "InvalidParameter",
    "message": "DESCRIPTION_OF_ERROR",
    "code": 400
}

URL di richiamo

Recupero delle SERP tramite un URL di callback
È possibile ricevere il risultato di una SERP direttamente su un URL fornito al momento della creazione di una query. È sufficiente recuperare la chiave HMAC collegata alla chiave API utilizzata.
  • Codice
  • PHP
  • Python
  • Javascript
  • Ruby
  • Java
  • C#
  • GO
// 1) Read the raw body (JSON)
$raw = file_get_contents('php://input');

// 2) Retrieve the headers
$headers = function_exists('getallheaders') ? getallheaders() : [];
$signature = $headers['X-Signature'] ?? '';

// 3) (Optional) Verify the HMAC signature
$sharedSecret = 'HMAC_KEY';
$expected = hash_hmac('sha256', $raw, $sharedSecret);
if (!hash_equals($expected, $signature)) {
    http_response_code(401);
    header('Content-Type: text/plain; charset=utf-8');
    echo 'Invalid signature';
    exit;
}

// 4) Decode the JSON
$data = json_decode($raw, true);

if (json_last_error() !== JSON_ERROR_NONE) {
    http_response_code(400);
    header('Content-Type: text/plain; charset=utf-8');
    echo 'Invalid JSON';
    exit;
}

// 5) Process the data: a list holding the finished SERP
foreach ($data as $serp) {
    // $serp['id'], $serp['keyword'], $serp['results']...
}

// 6) Respond in JSON (optional, we log these responses for tracking purposes)
http_response_code(200);
header('Content-Type: application/json; charset=utf-8');
echo json_encode([
    'status' => 'ok',
    'received_at' => gmdate('c'),
    'echo' => array_column($data, 'id')
]);

Stato di elaborazione delle SERP

Stato attuale dell'elaborazione delle SERP
Visualizzare il numero di SERP in base al loro stato:
Completato e risultati recuperati dall'utente (status=done, fetched=true)
Completato e risultati non recuperati dall'utente (status=done, fetched=false)
In corso (stato=elaborazione)
In attesa (status=pending)
get
https://api.semscraper.com/v1/serp/status
Autorizzazioni : Bearer {api_key}
  • Richiesta
  • Risposta positiva
Status: 200 OK
{
    "status": "success",
    "request_ms": 54,
    "count": 4,
    "data": [
        {
            "status": "done",
            "fetched": true,
            "count": 5
        },
        {
            "status": "done",
            "fetched": false,
            "count": 1000
        },
        {
            "status": "processing",
            "count": 0
        },
        {
            "status": "pending",
            "count": 0
        }
    ]
}

Cronologia delle query

Elenca le tue query, dalla più recente alla meno recente, con la relativa configurazione (parola chiave, motore di ricerca, dispositivo, località, lingua, profondità…) e il relativo stato, senza il risultato della SERP.
Vengono restituite tutte le query dell'account, qualunque sia il loro stato e che siano già state recuperate o meno. Questa chiamata non le contrassegna come recuperate.

Per la paginazione, richiama l'endpoint con il parametro cursor uguale al next_cursor della risposta precedente, finché has_more vale true. Il link _links.next contiene l'URL già pronto. Per ottenere il risultato di una query, usa il suo link _links.json o _links.html.
Limite
10.000 query per chiamata
get
https://api.semscraper.com/v1/serp/list?date=2026-10-10&limit=1000
Autorizzazioni : Bearer {api_key}
Parametri
date
string
Giorno di creazione delle query, nel formato YYYY-MM-DD (es.: 2026-10-04). Senza questo parametro vengono restituite tutte le date.
status
string
Filtro sullo stato: pending, processing o done. Senza questo parametro vengono restituiti tutti gli stati.
limit
integer
Numero di query per pagina, da 1 a 10.000. Predefinito: 1.000.
cursor
string
Cursore di paginazione: il valore next_cursor della risposta precedente. Da omettere per la prima pagina.
  • Richiesta
  • Risposta positiva
  • Risposta all'errore
Status: 200 OK
{
    "status": "success",
    "request_ms": 38,
    "count": 2,
    "has_more": true,
    "next_cursor": "MTI4NDU2Nzg5",
    "data": [
        {
            "id": "SERP_ID",
            "search_engine": "google_search",
            "keyword": "example keyword",
            "device": "desktop",
            "location": "fr",
            "language": "fr",
            "depth": 1,
            "geolocation": null,
            "priority": 1,
            "callback_url": null,
            "status": "done",
            "fetched": false,
            "cost": 0.0003,
            "created_at": "2026-10-04 09:12:45",
            "updated_at": "2026-10-04 09:12:58",
            "_links": {
                "json": {
                    "href": "/v1/serp?ids=SERP_ID&output=json",
                    "method": "GET",
                    "type": "application/json"
                },
                "html": {
                    "href": "/v1/serp?ids=SERP_ID&output=html",
                    "method": "GET",
                    "type": "application/json"
                }
            }
        },
        {
            "id": "SERP_ID",
            "search_engine": "google_maps",
            "keyword": "example keyword",
            "device": null,
            "location": "fr",
            "language": "fr",
            "depth": 1,
            "geolocation": "Nice, Alpes-Maritimes, France",
            "priority": 1,
            "callback_url": "https://example.com/callback",
            "status": "pending",
            "fetched": false,
            "cost": 0.0003,
            "created_at": "2026-10-04 09:12:44",
            "updated_at": null,
            "_links": {
                "json": {
                    "href": "/v1/serp?ids=SERP_ID&output=json",
                    "method": "GET",
                    "type": "application/json"
                },
                "html": {
                    "href": "/v1/serp?ids=SERP_ID&output=html",
                    "method": "GET",
                    "type": "application/json"
                }
            }
        }
    ],
    "_links": {
        "next": {
            "href": "/v1/serp/list?date=2026-10-04&limit=1000&cursor=MTI4NDU2Nzg5",
            "method": "GET",
            "type": "application/json"
        }
    }
}
Status: 400 Bad Request
{
    "error": "InvalidParameter",
    "message": "Invalid format for parameter: date",
    "code": 400
}

Fatturazione

Credito residuo

Recupera il credito residuo
get
https://api.semscraper.com/v1/billing/credit
Autorizzazioni : Bearer {api_key}
  • Richiesta
  • Risposta positiva
Status: 200 OK
{
    "status": "success",
    "request_ms": 21,
    "count": 1,
    "data": [
        {
            "balance": 100.50
        }
    ]
}

Metodi di pagamento

Metodi di pagamento disponibili
get
https://api.semscraper.com/v1/billing/payment_methods
Autorizzazioni : Bearer {api_key}
  • Richiesta
  • Risposta positiva
Status: 200 OK
{
    "status": "success",
    "request_ms": 43,
    "count": 3,
    "data": [
        {
            "id": 1,
            "name": "Perso",
            "num": "-4242",
            "expiration": "1226",
            "type": "Visa",
            "master": false
        },
        {
            "id": 30,
            "name": "Pro",
            "num": "-4444",
            "expiration": "1227",
            "type": "Mastercard",
            "master": true
        }
    ]
}