API REST de SEO per a desenvolupadors

L'API de SEO de MetricSpot llança la mateixa auditoria de 154 regles (on-page + llegibilitat per IA) que el nostre panell, per HTTP pla. Porta el teu propi llenguatge: curl, Node, Python, PHP, qualsevol cosa que parli HTTPS. Les mateixes claus Bearer funcionen també amb el nostre servidor MCP.

Prova l'API de SEO ara mateix, sense registre, sense token, només curl:

curl -s -X POST https://app.metricspot.com/api/public/audit \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com"}' | jq .total_score

Sense targeta. Resultats en 30 segons.

Prova cada crida des del navegador

Referència OpenAPI 3.1 amb exemples de petició en directe per als 12 endpoints.

Obre la referència de l'API →

Autenticació amb un token Bearer

Cada endpoint autenticat accepta un token a la capçalera Authorization: Authorization: Bearer ms_live_xxx. Genera una clau a app.metricspot.com/settings/api-keys (fins a 10 per compte). Les crides autenticades amb token requereixen el pla Pro i consumeixen la teva quota de 5.000 al mes. L'endpoint d'auditoria anònima funciona sense clau, limitat a 1 auditoria per IP cada 24 hores. Les mateixes claus ms_live_ funcionen tant en aquesta API REST com en el servidor MCP de MetricSpot.

curl

Endpoint anònim, sense token. Retorna el sobre complet de l'auditoria en línia.

curl -X POST https://app.metricspot.com/api/public/audit \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com"}'

Node (fetch)

Funciona a Node 18+, Bun, Deno i navegadors moderns. Sense dependències.

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 és equivalent: canvia httpx.post per 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

Extensió cURL estàndard, disponible a qualsevol instal·lació de PHP des de la 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);

Dotze endpoints, tot el motor d'auditoria

Cada endpoint executa la mateixa auditoria de 154 regles i els mateixos 15 mòduls de puntuació que app.metricspot.com. JSON entra, JSON surt. L'endpoint de prova anònima no requereix clau; els altres onze accepten un token Bearer del teu panell.

POST /api/public/audit
Sense auth

Auditoria anònima

Llança una auditoria puntual de SEO i llegibilitat per IA sobre qualsevol URL pública. Retorna puntuacions a 15 mòduls i 154 checks, més troballes accionables. Sense compte. Limitada a 1 auditoria per IP cada 24 hores.

POST /api/audits
Bearer requerit

Encuar auditoria completa

Encua una auditoria completa de SEO i llegibilitat per IA. Inclou Core Web Vitals des de Google PageSpeed Insights i trànsit orgànic si tens GA4 i Google Search Console connectats. Respon a l'instant amb audit_id i status: queued.

GET /api/audits/:id
Bearer requerit

Obtenir auditoria

Recupera per id una auditoria ja encuada. Retorna les puntuacions dels 15 mòduls (0-100), la puntuació total, cada troballa amb severitat i text de recomanació, i els enllaços als informes HTML i PDF.

GET /api/audits
Bearer requerit

Llistar auditories

Llista les auditories del compte, més recents primer, deduplicades per URL. Retorna audit_id, url, status, total_score, has_ga, has_gsc i created_at. Límit per defecte 24, màxim 100.

DELETE /api/audits/:id
Bearer requerit

Esborrar auditories per URL

Esborra totes les auditories que coincideixin amb la URL de l'audit_id donat. Retorna 204 en cas d'èxit.

PATCH /api/audits/reorder
Bearer requerit

Reordenar auditories

Fixa la posició de visualització de les auditories al dashboard. Body: { "url_order": ["https://a.com", "https://b.com", ...] } (màxim 200 URLs). Retorna 204.

GET /api/audits/history
Bearer requerit

Historial d'auditories

Retorna fins a 50 auditories històriques per a una URL. Útil per seguir l'evolució de la puntuació al llarg del temps. Query: ?url=<url-codificada>.

GET /api/audits/usage
Bearer requerit

Consum d'auditories

Retorna la quota d'auditories del mes en curs: audits_remaining, audits_used, plan_limit i reset_at.

POST /api/audits/:id/pdf
Bearer requerit

Renderitzar PDF amb marca

Llança el render d'un PDF amb marca per a una auditoria completada. Body: { "language": "en", "brand_id": 42 } (tots dos opcionals). Retorna 201 amb { pdf: { id, status: "pending" } }. Combina amb GET /api/pdfs/:id per fer polling.

GET /api/pdfs/:id
Bearer requerit

Comprovar estat del PDF

Retorna { pdf: { id, status, download_url } }. Si Accept: application/pdf i l'estat és ready, retorna directament el binari del PDF.

GET /api/pdfs/:id/download
Bearer requerit

Descarregar PDF

Descàrrega directa d'un PDF completat amb Content-Disposition: attachment.

GET /api/audits/:id/report
Bearer requerit

Previsualitzar informe HTML

Renderitza l'informe d'auditoria com a HTML amb marca (la mateixa plantilla a partir de la qual es genera el PDF). Útil per encastar-lo en un iframe de portal de client abans de descarregar el PDF. Query: ?lang=en&brand_id=42.

API REST o servidor MCP: quin encaixa amb el teu stack

Totes dues interfícies parlen amb el mateix motor d'auditoria, amb les mateixes claus i les mateixes dades. Tria REST si escrius HTTP pla des de CI, scripts o eines no-code; tria MCP si un agent d'IA necessita descobrir i encadenar eines pel seu compte.

Cas d'ús Auditoria SEO manual Altres APIs de SEO MCP de MetricSpot API REST de MetricSpot
CI/CD a cada PR No és viable a ritme de PR Possible però car per crida, JSON trencadís Excessiu: MCP brilla amb agents interactius, no amb jobs headless Un curl en un GitHub Action, comenta el delta de puntuació al PR
Eines no-code (Zapier, n8n, Make) Exportació i copiar i enganxar manuals Bloc HTTP a mida, camps mapejats a mà, fràgil davant canvis d'esquema Sense suport MCP a plataformes no-code majoritàries avui Bloc HTTP estàndard amb Bearer, resposta JSON que mapeja netament
Stack polígloth (Go, Ruby, Java) No aplicable Cal un SDK per llenguatge, sovint mantingut per la comunitat Les llibreries client MCP existeixen sobretot per a TypeScript i Python Qualsevol llenguatge amb client HTTPS funciona des del primer dia
Jobs interns programats Hores al mes, fàcils de saltar-se Preu per crida, sovint per keyword o per domini Funciona, però un subprocés stdio és incòmode dins de cron HTTPS pla des de cron, Kubernetes CronJob o Lambda
Fluxos amb agents d'IA Humà a cada bucle Els agents poden trucar a REST, però necessiten wrappers escrits a mà Pensat per a això: descripcions i esquemes autodescoberts Possible, però hauràs d'escriure tu mateix el codi d'enganxina de l'agent
PDF amb marca al teu SaaS Exportació i rebrand manuals Normalment només al pla més car Disponible via get_audit_pdf, dissenyat per a fluxos d'agent POST /api/audits/:id/pdf i després GET /api/pdfs/:id, incrusta'l a la teva UI

Com es compara l'API de SEO de MetricSpot amb DataForSEO i Serpstack

DataForSEO és un marketplace complet de dades SEO; Serpstack és una API d'scraping de SERPs; MetricSpot és una API enfocada en auditoria on-page i llegibilitat per IA. Mateix trio de lletres, forma de valor diferent. Tria la que coincideix amb la feina que estàs fent de debò.

Què compares DataForSEO Serpstack API de SEO MetricSpot
Feina principal que resol Marketplace massiu de dades: SERPs, paraules clau, backlinks, on-page Fa scraping de l'HTML de les SERPs de Google sota demanda Llança una auditoria completa on-page + llegibilitat per IA sobre una URL, retorna scores i correccions
Què obtens d'una crida JSON específic per endpoint; l'auditoria on-page retorna ~30 etiquetes/problemes Resultats SERP, anuncis, consultes relacionades, sense avaluació on-page Score total, 15 mòduls (0-100), cada finding de les 154 regles, severitat i text de recomanació
Model de preus Per crida, varia per endpoint ($0,0006-$0,002 cadascuna), saldo prepagat Mensual per trams: 100 gratis / $30 per 5K / fins a $200 per 50K SERPs Pla $49/mes Pro = 5.000 crides API, sense matemàtiques per crida
Endpoint de prova anònim No, cal registre + dipòsit d'$1 100 crides/mes gratis amb registre + access key Sí, 1 auditoria/IP/24h sense cap registre, JSON complet
Comprovacions de llegibilitat per IA / era LLM No estan al mòdul on-page No aplica (només SERPs) Mòdul dedicat: llms.txt, schema per a IA, contingut citable, claredat semàntica
PDF amb marca blanca No disponible No disponible POST /api/audits/:id/pdf retorna un PDF amb el teu logo i colors
Servidor MCP per a agents IA Sense MCP oficial Sense MCP oficial Sí, mateixes claus Bearer, mateix motor d'auditoria, compatible amb Claude Code, Cursor i ChatGPT
Estil d'autenticació HTTP Basic amb login + contrasenya (poc comú en stacks moderns) Clau API a la query string (?access_key=…) Capçalera estàndard Authorization: Bearer ms_live_xxx

Preus de l'API REST

L'API REST està inclosa al Pro 49 $/mes. Els comptes Pro tenen 5.000 crides API al mes contra qualsevol dels dotze endpoints autenticats amb token. L'endpoint d'auditoria anònima és gratuït per a tothom (limitat a 1 per IP cada 24 h). Els comptes Free i Starter poden consultar la documentació i generar tokens, però les crides autenticades amb token retornen 403 fins a passar a Pro. Les mateixes claus ms_live_ funcionen tant per a aquesta API REST com per al servidor MCP de MetricSpot, contra la mateixa quota mensual compartida.

Free

$0/mo

Prova la plataforma. Sense targeta, sense compromís.

  • ·10 auditories al mes (1 per lloc cada 24h)
  • ·Els deu mòduls de puntuació
  • ·Descàrrega PDF amb la nostra marca
  • ·Informes multilingües

Starter

$29/mo

Per a freelances amb informes mensuals.

  • ·Fins a 5 dominis monitoritzats
  • ·50 auditories al mes
  • ·Informes PDF totalment marca blanca
  • ·Kit de marca personalitzat (logo, color, peu de pàgina)

Pro

$49/mo

Per a agències, freelances i revenedors.

  • ·Tot el de Starter
  • ·Re-auditories programades (setmanal, quinzenal o mensual)
  • ·Informes comparatius amb competidors (fins a 3 competidors)
  • ·Dominis monitoritzats il·limitats

Veure límits i preus dels plans →

Què construeixen els desenvolupadors amb l'API REST

Patrons concrets que veiem en equips que ja són en producció amb l'API. Cada exemple fa servir les mateixes eines i el mateix token Bearer.

  • •CI/CD: audita cada preview deploy en obrir un PR, comenta el delta de puntuació davant de main i trenca el build si la puntuació cau més de 5 punts.
  • •Zapier, n8n, Make: llança una auditoria quan entra un lead nou al teu CRM, envia la puntuació total i les 3 troballes principals a un canal de Slack i adjunta el PDF amb la teva marca.
  • •Monitoratge intern: programa una auditoria nocturna de les teves 50 URLs principals, aboca les puntuacions dels mòduls en un panell de Grafana i alerta quan cau una categoria.
  • •SaaS amb marca blanca: encua una auditoria a demanda de l'usuari, renderitza el PDF amb la teva marca i incrusta les troballes JSON a la teva pròpia UI sense allotjar el motor d'auditoria.
  • •Gates de QA: bloqueja un deploy si el mòdul de llegibilitat per IA baixa del llindar compromès amb el teu client, amb les regles fallades al log del build.
  • •Reports: llança GET /api/audits/history?url= després de cada auditoria per enviar una gràfica d'evolució de la puntuació al llarg del temps, acompanyada de l'últim PDF amb la teva marca.

Escriure HTTP pla des d'un script o un runner de CI és un camí. Si condueixes l'auditoria des d'un agent d'IA (Claude Code, Cursor, ChatGPT, Gemini), el nostre servidor MCP de SEO exposa les mateixes eines sobre Model Context Protocol amb esquemes autodescoberts: mateix motor, mateixes claus, sense codi d'enganxina.

Preguntes freqüents

L'API REST és gratis?

L'endpoint d'auditoria anònima (POST /api/public/audit) és gratuït i no requereix compte, limitat a 1 auditoria per IP cada 24 hores. Els onze endpoints autenticats amb token requereixen el pla Pro a 49 $/mes, que inclou 5.000 crides API al mes sense cost addicional.

En què es diferencia això del servidor MCP?

Mateix motor d'auditoria, mateixes 154 regles en 15 mòduls, mateixes claus Bearer. L'API REST és HTTP pla per a persones que escriuen codi: curl, fetch, requests, el que sigui. El servidor MCP parla Model Context Protocol perquè els agents d'IA (Claude Code, Cursor, ChatGPT, Gemini) descobreixin automàticament eines, esquemes i autenticació. Fes servir REST per a CI, scripts i no-code; fes servir MCP per a fluxos amb agents.

Puc fer-la servir amb eines no-code com Zapier?

Sí. Qualsevol plataforma no-code amb un bloc HTTP genèric funciona: Zapier (Webhooks by Zapier), n8n (HTTP Request node), Make (mòdul HTTP), Pipedream, Retool. Posa la URL a https://app.metricspot.com/api/audits, mètode POST, afegeix Authorization: Bearer ms_live_xxx a les capçaleres i envia {"url": "https://example.com"} com a JSON. La resposta mapeja netament a camps natius a totes les plataformes provades.

Quins llenguatges tenen SDK oficial?

Cap encara. L'únic necessari és un client HTTPS i parsing de JSON, que qualsevol llenguatge modern porta de sèrie. Un SDK prim de JavaScript i TypeScript és al roadmap; fins llavors, els quatre exemples de codi de dalt cobreixen el 90% de les integracions que veiem. Si vols un SDK en un llenguatge concret, obre una issue a github.com/MetricSpot.

Com m'autentico?

Envia Authorization: Bearer ms_live_xxx a cada crida autenticada. Els tokens porten el prefix ms_live_ i es mostren una sola vegada en crear-los; el panell guarda només un hash. Tracta'ls com qualsevol altre secret: no els pugis mai a git, rota'ls si els exposes, fes servir una clau per integració per poder revocar-les individualment. El panell limita cada compte a 10 claus actives.

D'on surten les claus API?

Genera-les a app.metricspot.com/settings/api-keys després de registrar-te a qualsevol pla, inclòs el Free. Cada clau es mostra una sola vegada; copia-la al teu gestor de secrets a l'instant. Les mateixes claus funcionen a l'API REST i al servidor MCP de MetricSpot, així que només gestiones un conjunt de credencials als dos camins d'integració.

Les dades són les mateixes que al panell de MetricSpot?

Sí. Cada endpoint passa pel mateix motor d'auditoria que mou app.metricspot.com: les mateixes 154 regles en 15 mòduls, les mateixes severitats, els mateixos textos de recomanació. El PDF de POST /api/audits/:id/pdf és el mateix que descarregues des del panell.

Quins són els límits d'ús?

L'endpoint anònim està limitat a 1 auditoria per IP cada 24 hores. L'accés a l'API requereix Pro 49 $/mes. Pro inclou 5.000 crides API al mes. Free i Starter no inclouen accés a l'API. L'endpoint anònim continua sent gratuït (1 per IP cada 24 h).

Què passa si supero les 5.000 crides en un mes?

L'endpoint retorna HTTP 429 amb el cos { error: "quota_exceeded", used: 5000, limit: 5000 }. La quota es reinicia a l'inici del següent mes natural. Si necessites una quota més alta, contacta'ns des del formulari de suport i muntem un tram personalitzat.

Deixa d'escriure informes SEO a mà.

Executa una auditoria, posa la teva marca al PDF, envia'l. En cinc minuts.

Comença la teva primera auditoria