seo/
google-organic-serp

Recupera in tempo reale una pagina di risultati di Google per una query e un mercato, con URL di destinazione, titoli, posizioni in classifica, tipi di elemento e dettagli dei risultati in record normalizzati.

Google Organic SERP API

Istantanea SERP in tempo reale
Scelta del dispositivo
Elementi di risultato misti
0,1 crediti per risultato
Pronto
Pronto

Inserisci i parametri e invia una richiesta. Qui compariranno lo stato dell’attività e i risultati normalizzati.

README

A cura di SocQ · Aggiornato il

Google Organic SERP

Le pagine dei risultati organici di Google combinano link in classifica con altri elementi visibili come featured snippet, domande, risultati locali e video. Destinazioni, posizioni, tipi di elemento e dettagli di presentazione supportano istantanee del posizionamento, analisi del layout e confronti tra dispositivi o mercati.

Funzionalità della Google Organic SERP API

  • Istantanea di mercato per una singola queryRisolve una query di ricerca con impostazioni esplicite di mercato, lingua e desktop o mobile, per una pagina di risultati puntuale e confrontabile.
  • Campi di posizione e destinazioneRestituisce, quando disponibili, URL di destinazione, titoli visualizzati, posizioni di gruppo, posizioni assolute e numeri di pagina dei risultati di ricerca in campi normalizzati.
  • Copertura mista degli elementi della SERPConserva i link organici e gli altri tipi di risultato restituiti, con extra.type che identifica il tipo di elemento rappresentato da ogni record.
  • Contesto completo dell’elementoMantiene in extra l’intero oggetto specifico dell’elemento, così domini, snippet, breadcrumb, immagini e attributi dei risultati ricchi restano disponibili quando presenti.

Parametri della Google Organic SERP API

ParametriObbligatorioDescrizione
queryObbligatorioQuery di ricerca obbligatoria non vuota. Un’attività accetta una sola query.
location_codeFacoltativoCodice numerico positivo del mercato. Il Playground usa per impostazione predefinita 2840, cioè gli Stati Uniti.
location_nameFacoltativoNome facoltativo del mercato di ricerca, alternativo a location_code. Se compilato, ha la precedenza su location_code.
language_codeFacoltativoCodice della lingua di ricerca, da 2 a 10 caratteri. Il Playground usa per impostazione predefinita en.
languageFacoltativoNome facoltativo della lingua di ricerca, alternativo a language_code. Se compilato, ha la precedenza su language_code.
deviceFacoltativoContesto del dispositivo di ricerca: desktop o mobile.
results_limitFacoltativoProfondità di posizionamento richiesta da 1 a 700. È un tetto e non garantisce lo stesso numero di elementi appiattiti.

Come usare la Google Organic SERP API

Invia una query con impostazioni di mercato basate su codici e una profondità limitata, poi leggi ogni elemento normalizzato della SERP dall’attività asincrona completata.

  1. Scegli una query non vuota, un location_code, un language_code, un device e un results_limit da 1 a 200.
  2. Invia con POST il payload a /v1/seo/google-organic-serp e salva il task_id restituito.
  3. Interroga /v1/tasks/{task_id} finché l’attività non ha successo o restituisce un errore.
  4. Leggi data.results.items, poi richiedi il next_cursor restituito finché has_more resta true.
curl -X POST "https://api.socq.ai/v1/seo/google-organic-serp" \
  -H "Authorization: Bearer $SOCQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"keyword research","location_code":2840,"language_code":"en","device":"desktop","results_limit":10}'

# Poll GET /v1/tasks/{task_id}
# Read data.results.items and follow next_cursor while has_more is true

Casi d’uso della Google Organic SERP API

  • Istantanee del posizionamento attuale: Usa gli URL di destinazione con rank.group, rank.absolute, rank.page e collected_at per registrare dove compaiono le pagine restituite per una query definita.
  • Confronto tra dispositivi e mercati: Invia query abbinate con valori controllati di device, location_code e language_code per confrontare destinazioni e posizioni dei risultati tra contesti diversi.
  • Analisi del layout della SERP: Esamina extra.type e i campi specifici dell’elemento per distinguere i link in classifica da domande, snippet, risultati locali, video e altre funzionalità restituite della pagina.

Consigli degli esperti per la Google Organic SERP API

  • Mantieni invariati query, location_code e language_code quando confronti desktop e mobile, così il dispositivo resta l’unica variabile prevista.
  • Usa un results_limit non superiore a 200, anche se la validazione della route accetta valori più grandi, perché la profondità dei risultati avanzati in tempo reale è limitata a 200.
  • Distingui in base a extra.type prima di leggere le chiavi specifiche dell’elemento e metti in conto che url e i valori di rank possano mancare per gli elementi che non li espongono.
  • Considera rank.page come numero della pagina dei risultati di ricerca; usa next_cursor a parte per paginare i record dei risultati salvati di SocQ.
  • Salva extra come oggetto flessibile, perché le chiavi disponibili variano in base al tipo di elemento della SERP e possono evolvere.

Oltre alla Google Organic SERP API, usa queste API quando ti serve un altro tipo di dati pubblici di SEO.

  • Keyword Difficulty API — Confronta la difficoltà di posizionamento organico per un gruppo di parole chiave inviato, restituendo ogni parola chiave disponibile con il suo punteggio normalizzato.
  • Keyword Overview API — Arricchisce un gruppo di parole chiave inviato con domanda, concorrenza a pagamento, difficoltà, ricerche mensili e contesto dell’intento, se disponibili.
  • Keyword Search Volume API — Misura parole chiave note con volume di ricerca, CPC, concorrenza a pagamento e cronologia mensile delle ricerche, se disponibili.
  • Related Keywords API — Segue i percorsi delle ricerche correlate a partire da una query di partenza con controlli di profondità, misurazioni delle parole chiave, contesto dell’intento e righe di origine complete, se disponibili.
  • Search Intent API — Classifica l’intento di ricerca primario e secondario per un gruppo di parole chiave inviato, conservando le probabilità di origine e i record completi.
  • Google News API — Recupera gli articoli di Google News per una query, notizie principali prima, con titolo, testata, link diretto all’articolo, estratto e ora di pubblicazione.

Esplora altre piattaforme

Combina i dati di SEO con i dati pubblici delle altre piattaforme social supportate.

Google Organic SERP API — FAQ

Google Organic SERP API è un’interfaccia programmatica che recupera in tempo reale una pagina di risultati di Google a partire da una query, un codice di mercato, un codice lingua e un dispositivo. Restituisce destinazioni, titoli, posizioni in classifica, tipi di elemento e dettagli completi specifici di ogni elemento in forma normalizzata.

Il Playground accetta una query obbligatoria più location_code, language_code, device e results_limit. Usa selettori di mercato e lingua basati su codici per evitare combinazioni ambigue con le alternative basate sui nomi.

No. Una pagina di risultati avanzati in tempo reale può contenere link organici, featured snippet, domande, risultati locali, video e altri elementi visibili; controlla extra.type per ogni record.

Sì. Alcuni elementi della pagina dei risultati non espongono un URL di destinazione o tutti i valori di posizione, quindi i client dovrebbero trattare url, rank.group, rank.absolute e rank.page come nullable.

Ogni elemento SERP normalizzato restituito costa 0,1 crediti SocQ. Un insieme di risultati vuoto non comporta addebiti sui risultati e la profondità della richiesta è una stima, non un numero di risultati garantito.