API di analisi SERP

Esegui analisi via API REST con la tua chiave.

Autenticazione

Crea una chiave nel tuo Il tuo account e inviala nell’header X-API-Key a ogni richiesta. Ogni analisi consuma 1 credito dal saldo tuo o del tuo team.

Avviare un’analisi

POST https://serptune.com/api/v1/analyze
X-API-Key: stk_xxxxxxxx.xxxxxxxx
Content-Type: application/json

{
  "url": "https://example.com/your-page",
  "query": "best running shoes",
  "country": "US",
  "language": "en",
  "report_locale": "it"
}

Risposta: { "uuid": "…", "status": "queued", "result_url": "https://serptune.com/api/v1/analysis?id=…" }

Recuperare il risultato

GET https://serptune.com/api/v1/analysis?id=<uuid>
X-API-Key: stk_xxxxxxxx.xxxxxxxx

Interroga ogni pochi secondi finché status non è completed. Il campo report contiene allora il JSON completo: sintesi esecutiva, azioni prioritizzate e le sezioni gap semantico, gap UX e prontezza AI.

Risposta:

{
  "uuid": "3f8a1c7e-5b42-4d19-9e6f-0a2b8c4d1e35",
  "status": "completed",
  "url": "https://example.com/your-page",
  "query": "best running shoes",
  "country": "US",
  "language": "en",
  "created_at": "2026-10-12 09:14:02",
  "completed_at": "2026-10-12 09:15:41",
  "error": null,
  "report": { … }
}

Stati dell’analisi

status passa per queued e running, poi si ferma su uno di tre valori terminali: completed, failed o canceled. Interrompi il polling su tutti e tre — su failed e canceled il campo error riporta il motivo e report resta null.

Limiti di frequenza

Fino a 60 richieste all’ora per account e 3 analisi in corso contemporaneamente. Oltre uno dei due limiti l’endpoint risponde 429: attendi e riprova.

Errori

401 — chiave API non valida o revocata
402 — crediti insufficienti
404 — id analisi inesistente
405 — metodo HTTP errato (analyze accetta solo POST)
422 — dati non validi (url, query, country, language)
429 — troppe richieste, riprova più tardi

Crea chiave API