API REST SEO per sviluppatori
L'API SEO di MetricSpot lancia lo stesso audit a 154 regole (on-page + leggibilità IA) della nostra dashboard, via HTTP puro. Porta il tuo linguaggio: curl, Node, Python, PHP, qualsiasi cosa parli HTTPS. Le stesse chiavi Bearer funzionano anche con il nostro server MCP.
Prova l'API SEO subito, senza registrazione, senza token, solo curl:
curl -s -X POST https://app.metricspot.com/api/public/audit \
-H "Content-Type: application/json" \
-d '{"url":"https://example.com"}' | jq .total_scoreSenza carta. Risultati in 30 secondi.
Prova ogni chiamata dal browser
Riferimento OpenAPI 3.1 con esempi di richiesta live per tutti i 12 endpoint.
Autenticazione con token Bearer
Ogni endpoint autenticato accetta un token nell'header Authorization: Authorization: Bearer ms_live_xxx. Genera una chiave su app.metricspot.com/settings/api-keys (fino a 10 per account). Le chiamate autenticate con token richiedono il piano Pro e pesano sulla tua quota di 5.000 al mese. L'endpoint di audit anonimo funziona senza chiave, limitato a 1 audit per IP ogni 24 ore. Le stesse chiavi ms_live_ funzionano sia per questa API REST sia per il server MCP di MetricSpot.
curl
Endpoint anonimo, senza token. Restituisce la busta di audit completa inline.
curl -X POST https://app.metricspot.com/api/public/audit \
-H "Content-Type: application/json" \
-d '{"url":"https://example.com"}'Node (fetch)
Funziona in Node 18+, Bun, Deno e nei browser moderni. Senza dipendenze.
const res = await fetch("https://app.metricspot.com/api/audits", {
method: "POST",
headers: {
"Content-Type": "application/json",
"Authorization": "Bearer ms_live_xxx",
},
body: JSON.stringify({ url: "https://example.com" }),
});
const audit = await res.json();Python (httpx)
requests funziona allo stesso modo: sostituisci httpx.post con requests.post.
import httpx
res = httpx.post(
"https://app.metricspot.com/api/audits",
headers={"Authorization": "Bearer ms_live_xxx"},
json={"url": "https://example.com"},
)
audit = res.json()PHP
Estensione cURL standard, disponibile in ogni installazione di PHP dalla 4.0.
<?php
$ch = curl_init("https://app.metricspot.com/api/audits");
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"Authorization: Bearer ms_live_xxx",
],
CURLOPT_POSTFIELDS => json_encode(["url" => "https://example.com"]),
CURLOPT_RETURNTRANSFER => true,
]);
$audit = json_decode(curl_exec($ch), true);Dodici endpoint, tutto il motore di audit
Ogni endpoint esegue lo stesso audit a 154 regole e gli stessi 15 moduli di punteggio di app.metricspot.com. JSON in ingresso, JSON in uscita. L'endpoint anonimo di prova non richiede chiavi; gli altri undici accettano un token Bearer dalla tua dashboard.
/api/public/audit Audit anonimo
Lancia un audit SEO e di leggibilità per IA una tantum su qualsiasi URL pubblico. Restituisce punteggi su 15 moduli e 154 controlli, oltre a finding azionabili. Senza account. Limitato a 1 audit per IP ogni 24 ore.
/api/audits Metti in coda un audit completo
Mette in coda un audit SEO e di leggibilità per IA completo. Include Core Web Vitals da Google PageSpeed Insights e traffico organico se GA4 e Google Search Console sono collegati. Risponde subito con audit_id e status: queued.
/api/audits/:id Recupera audit
Recupera tramite id un audit già messo in coda. Restituisce i punteggi dei 15 moduli (0-100), il punteggio totale, ogni finding con severità e testo di raccomandazione, oltre ai link ai report HTML e PDF.
/api/audits Elenca audit
Elenca gli audit dell'account, dai più recenti, deduplicati per URL. Restituisce audit_id, url, status, total_score, has_ga, has_gsc, created_at. Limite predefinito 24, massimo 100.
/api/audits/:id Elimina audit per URL
Elimina tutti gli audit con lo stesso URL dell'audit_id indicato. Restituisce 204 in caso di successo.
/api/audits/reorder Riordina audit
Imposta la posizione di visualizzazione degli audit nella dashboard. Body: { "url_order": ["https://a.com", "https://b.com", ...] } (max 200 URL). Restituisce 204.
/api/audits/history Storico audit
Restituisce fino a 50 audit storici per un URL. Utile per seguire l'andamento del punteggio nel tempo. Query: ?url=<url-codificato>.
/api/audits/usage Consumo audit
Restituisce la quota audit del mese corrente: audits_remaining, audits_used, plan_limit, reset_at.
/api/audits/:id/pdf Renderizza PDF brandizzato
Avvia il rendering di un PDF brandizzato per un audit completato. Body: { "language": "en", "brand_id": 42 } (entrambi opzionali). Restituisce 201 con { pdf: { id, status: "pending" } }. Combina con GET /api/pdfs/:id per fare polling.
/api/pdfs/:id Polling stato PDF
Restituisce { pdf: { id, status, download_url } }. Se Accept: application/pdf e lo stato è ready, restituisce direttamente il binario del PDF.
/api/pdfs/:id/download Scarica PDF
Download diretto di un PDF completato con Content-Disposition: attachment.
/api/audits/:id/report Anteprima report HTML
Renderizza il report di audit come HTML brandizzato (lo stesso template da cui viene generato il PDF). Utile per incorporarlo in un iframe di portale cliente prima di scaricare il PDF. Query: ?lang=en&brand_id=42.
API REST o server MCP: cosa si adatta al tuo stack
Entrambe le interfacce parlano con lo stesso motore di audit, con le stesse chiavi e gli stessi dati. Scegli REST quando scrivi HTTP puro da CI, script o tool no-code; scegli MCP quando un agente IA deve scoprire e concatenare strumenti da solo.
| Caso d'uso | Audit SEO manuale | Altre API SEO | MCP di MetricSpot | API REST di MetricSpot |
|---|---|---|---|---|
| CI/CD su ogni PR | Non fattibile al ritmo dei PR | Possibile ma costoso per chiamata, JSON fragile | Esagerato: MCP brilla con agenti interattivi, non con job headless | Un curl in una GitHub Action, commenta il delta di punteggio sulla PR |
| Tool no-code (Zapier, n8n, Make) | Export e copia-incolla manuali | Blocco HTTP su misura, campi mappati a mano, fragile ai cambi di schema | Oggi nessun supporto MCP nelle piattaforme no-code mainstream | Blocco HTTP standard con Bearer, risposta JSON che mappa pulita |
| Stack poliglotta (Go, Ruby, Java) | Non applicabile | Serve un SDK per linguaggio, spesso community-driven | Le librerie client MCP esistono soprattutto per TypeScript e Python | Qualsiasi linguaggio con client HTTPS funziona dal primo giorno |
| Job interni pianificati | Ore al mese, facili da saltare | Prezzo per chiamata, spesso per keyword o per dominio | Funziona, ma un sottoprocesso stdio è scomodo dentro cron | HTTPS puro da cron, Kubernetes CronJob o Lambda |
| Workflow con agenti IA | Umano in ogni loop | Gli agenti possono chiamare REST, ma servono wrapper scritti a mano | Pensato per questo: descrizioni e schemi scoperti automaticamente | Possibile, ma il codice di collegamento dell'agente lo scrivi tu |
| PDF brandizzato nel tuo SaaS | Export e rebrand manuali | Di solito solo nel piano più caro | Disponibile via get_audit_pdf, pensato per i flussi degli agenti | POST /api/audits/:id/pdf e poi GET /api/pdfs/:id, integra nella tua UI |
Come l'API SEO di MetricSpot si confronta con DataForSEO e Serpstack
DataForSEO è un marketplace completo di dati SEO; Serpstack è un'API di scraping di SERP; MetricSpot è un'API focalizzata su audit on-page e leggibilità per IA. Stesso trio di lettere, forma di valore diversa. Scegli quella che corrisponde al lavoro che stai realmente facendo.
| Cosa confronti | DataForSEO | Serpstack | API SEO MetricSpot |
|---|---|---|---|
| Lavoro principale che risolve | Marketplace dati massiccio: SERP, keyword, backlink, on-page | Fa scraping dell'HTML delle SERP di Google su richiesta | Lancia un audit completo on-page + leggibilità IA su una URL, restituisce score e correzioni |
| Cosa ottieni da una chiamata | JSON specifico per endpoint; l'audit on-page restituisce ~30 tag/problemi | Risultati SERP, annunci, query correlate, nessuna valutazione on-page | Score totale, 15 moduli (0-100), ogni finding delle 154 regole, severità, testo di raccomandazione |
| Modello di prezzo | A chiamata, varia per endpoint ($0,0006-$0,002 ciascuna), saldo prepagato | Mensile a scaglioni: 100 gratis / $30 per 5K / fino a $200 per 50K SERP | Forfait $49/mese Pro = 5.000 chiamate API, senza calcoli per chiamata |
| Endpoint di prova anonimo | No, richiede registrazione + deposito di $1 | 100 chiamate/mese gratis con registrazione + access key | Sì, 1 audit/IP/24h senza alcuna registrazione, JSON completo |
| Check di leggibilità per IA / era LLM | Non nel modulo on-page | Non applicabile (solo SERP) | Modulo dedicato: llms.txt, schema per IA, contenuti citabili, chiarezza semantica |
| PDF white-label brandizzato | Non fornito | Non fornito | POST /api/audits/:id/pdf restituisce un PDF con il tuo logo e i tuoi colori |
| Server MCP per agenti IA | Nessun MCP ufficiale | Nessun MCP ufficiale | Sì, stesse chiavi Bearer, stesso motore di audit, compatibile con Claude Code, Cursor e ChatGPT |
| Stile di autenticazione | HTTP Basic con login + password (raro negli stack moderni) | Chiave API in query string (?access_key=…) | Header standard Authorization: Bearer ms_live_xxx |
Prezzi dell'API REST
L'API REST è inclusa nel Pro 49 $/mese. Gli account Pro ricevono 5.000 chiamate API al mese su uno qualsiasi dei dodici endpoint autenticati con token. L'endpoint di audit anonimo è gratuito per tutti (limitato a 1 per IP ogni 24 h). Gli account Free e Starter possono consultare la documentazione e generare token, ma le chiamate autenticate con token restituiscono 403 fino al passaggio a Pro. Le stesse chiavi ms_live_ funzionano sia per questa API REST sia per il server MCP di MetricSpot, sulla stessa quota mensile condivisa.
Free
$0/mo
Prova la piattaforma. Senza carta, senza impegno.
- ·10 audit al mese (1 per sito ogni 24h)
- ·Tutti e dieci i moduli di punteggio
- ·Download PDF con il nostro brand
- ·Report multilingua
Starter
$29/mo
Per freelance con report mensili.
- ·Fino a 5 domini monitorati
- ·50 audit al mese
- ·Report PDF completamente white-label
- ·Brand kit personalizzato (logo, colore, footer)
Pro
$49/mo
Per agenzie, freelance e rivenditori.
- ·Tutto incluso in Starter
- ·Re-audit pianificati (settimanale, quindicinale o mensile)
- ·Report comparativi con i concorrenti (fino a 3 concorrenti)
- ·Domini monitorati illimitati
Cosa costruiscono gli sviluppatori con l'API REST
Pattern concreti che vediamo nei team già in produzione con l'API. Ogni esempio usa gli stessi strumenti e lo stesso token Bearer.
- •CI/CD: audita ogni preview deploy all'apertura di una PR, pubblica un commento con il delta di punteggio rispetto a main, rompi la build se il punteggio cala di più di 5 punti.
- •Zapier, n8n, Make: avvia un audit quando arriva un nuovo lead nel tuo CRM, manda il punteggio totale e i 3 finding principali in un canale Slack, allega il PDF brandizzato.
- •Monitoraggio interno: pianifica un audit notturno dei tuoi 50 URL principali, invia i punteggi dei moduli a un pannello Grafana e alza un alert quando una categoria cala.
- •SaaS white-label: metti in coda un audit a richiesta dell'utente, renderizza il PDF brandizzato e incorpora i finding JSON nella tua UI senza ospitare il motore di audit.
- •Gate di QA: blocca un deploy se il modulo di leggibilità per IA scende sotto la soglia concordata con il cliente, con le regole fallite nel log di build.
- •Reportistica: chiama GET /api/audits/history?url= dopo ogni audit per consegnare un grafico dell'andamento del punteggio nel tempo insieme all'ultimo PDF brandizzato.
Scrivere HTTP puro da uno script o da un runner CI è una via. Se guidi l'audit da un agente IA (Claude Code, Cursor, ChatGPT, Gemini), il nostro server MCP SEO espone gli stessi strumenti via Model Context Protocol con schemi scoperti automaticamente: stesso motore, stesse chiavi, niente codice di collegamento.
Domande frequenti
L'API REST è gratuita?
L'endpoint di audit anonimo (POST /api/public/audit) è gratuito e non richiede un account, limitato a 1 audit per IP ogni 24 ore. Gli undici endpoint autenticati con token richiedono il piano Pro a 49 $/mese, che include 5.000 chiamate API al mese senza costi aggiuntivi.
Che differenza c'è con il server MCP?
Stesso motore di audit, stesse 154 regole su 15 moduli, stesse chiavi Bearer. L'API REST è HTTP puro per chi scrive codice a mano: curl, fetch, requests, quel che vuoi. Il server MCP parla Model Context Protocol così gli agenti IA (Claude Code, Cursor, ChatGPT, Gemini) scoprono in automatico strumenti, schemi e auth. REST per CI, script e no-code; MCP per i flussi con agenti.
Posso usarla con tool no-code come Zapier?
Sì. Qualsiasi piattaforma no-code con un blocco HTTP generico funziona: Zapier (Webhooks by Zapier), n8n (HTTP Request node), Make (modulo HTTP), Pipedream, Retool. Imposta l'URL su https://app.metricspot.com/api/audits, metodo POST, aggiungi Authorization: Bearer ms_live_xxx negli header e invia {"url": "https://example.com"} come JSON. La risposta mappa pulita sui campi nativi di tutte le piattaforme testate.
Quali linguaggi hanno SDK ufficiali?
Nessuno per ora. Tutto quello che serve è un client HTTPS e il parsing JSON, e ogni linguaggio moderno lo ha di serie. Un SDK snello in JavaScript e TypeScript è in roadmap; nel frattempo i quattro esempi di codice sopra coprono circa il 90% delle integrazioni che vediamo. Se vuoi un SDK in un linguaggio specifico, apri una issue su github.com/MetricSpot.
Come mi autentico?
Invia Authorization: Bearer ms_live_xxx in ogni chiamata autenticata. I token hanno il prefisso ms_live_ e vengono mostrati una volta sola alla creazione; la dashboard conserva solo un hash. Trattali come ogni altro segreto: mai committarli, ruotali se vengono esposti, una chiave per integrazione così puoi revocare in modo mirato. La dashboard limita ogni account a 10 chiavi attive.
Da dove arrivano le chiavi API?
Generale su app.metricspot.com/settings/api-keys dopo esserti iscritto a un qualsiasi piano, incluso il Free. Ogni chiave viene mostrata una volta sola; copiala subito nel tuo secret store. Le stesse chiavi funzionano per l'API REST e per il server MCP di MetricSpot, quindi gestisci un solo set di credenziali per entrambe le vie di integrazione.
I dati sono gli stessi della dashboard MetricSpot?
Sì. Ogni endpoint passa per lo stesso motore di audit che alimenta app.metricspot.com: le stesse 154 regole su 15 moduli, le stesse severità, gli stessi testi di raccomandazione. Il PDF da POST /api/audits/:id/pdf è lo stesso che scarichi dalla dashboard.
Quali sono i rate limit?
L'endpoint anonimo è limitato a 1 audit per IP ogni 24 ore. L'accesso all'API richiede Pro 49 $/mese. Pro include 5.000 chiamate API al mese. Free e Starter non includono l'accesso all'API. L'endpoint anonimo resta gratuito (1 per IP ogni 24 h).
Cosa succede se supero le 5.000 chiamate in un mese?
L'endpoint restituisce HTTP 429 con body { error: "quota_exceeded", used: 5000, limit: 5000 }. La quota si azzera all'inizio del mese di calendario successivo. Se ti serve una quota più alta, scrivici tramite il modulo di supporto e troviamo una fascia su misura.
Basta scrivere report SEO a mano.
Lancia un audit, applica il tuo brand al PDF, invialo al cliente. In cinque minuti.
Avvia il tuo primo audit