Documentation API — GEO Audit

Vue d'ensemble

L'API expose plusieurs niveaux d'usage : audits consolidés (GEO + SEO + LLM live), audits par dimension (catégories SEO/GEO), modules unitaires (lancer un seul check : Core Web Vitals, backlinks, hallucination cross-LLM…), et endpoints spécialisés (Citation Tracker multi-LLM, Fan-out Coverage, prefill brand, exports HTML/PDF).

Architecture stateless one-shot : chaque appel est indépendant, pas de DB, cache mémoire opportuniste pour les API externes coûteuses (PSI, SERP, AIO).

URL de base

Basehttps://z10cj0y7ypqclpq79g8l2a8s.chris-ia.com

Tous les endpoints sont préfixés par /api. En développement local : http://localhost:3000.

Authentification

Aucune clé d'API requise pour l'usage public. Rate limit appliqué par IP : 5 audits/min et 30 audits/h (configurable via RATE_LIMIT_PER_IP_PER_MINUTE/HOUR). Les clés tierces (OpenRouter, Moz, Google PSI, DataForSEO, Google Places) sont configurées côté serveur dans .env.local — voir Variables d'env.

SSRF guard actif Les URLs vers IPs privées (10.0.0.0/8, 192.168.0.0/16), loopback, link-local, ou métadata cloud (169.254.169.254) sont rejetées avec 400 SSRF_BLOCKED.

Démarrage rapide

1. Audit GEO basique (67 checks, ~10s)

curlcurl -X POST https://z10cj0y7ypqclpq79g8l2a8s.chris-ia.com/api/audit \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com"}'

2. Audit FULL (GEO + SEO + LLM live + DataForSEO, ~90s)

curlcurl -X POST https://z10cj0y7ypqclpq79g8l2a8s.chris-ia.com/api/audit/full \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com"}'

3. Lancer UN seul module (ex: Core Web Vitals seul)

curlcurl -X POST https://z10cj0y7ypqclpq79g8l2a8s.chris-ia.com/api/audit/module/cwv \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com"}'

Tiers d'endpoints

Les endpoints sont classés par fonction et coût opérationnel.

CORE

Audit local 100% gratuit, pas de clé tierce requise. Crawl, parsing HTML, scoring déterministe.

LIVE LLM

Modules LLM cross-modèles (Gemini, GPT-4o, Claude, Perplexity) via OpenRouter. ~0.05$/run.

PREMIUM

Modules pro nécessitant Moz, Google PSI, DataForSEO, Places. ~0.10-0.20$/run.

EXPORT

Génération de livrables HTML standalone, PDF, plan markdown pour Claude Code.

Audit consolidé

Les endpoints qui orchestrent plusieurs modules pour produire un rapport complet (GEO + SEO + LLM + intégrations).

POST /api/audit/full premium

Audit FULL consolidé : GEO (67 checks) + SEO (74 checks) + Core Web Vitals (PSI/CrUX) + Backlinks (Moz/Common Crawl) + Visual GDPR + SXO Personas + Local SEO + DataForSEO (SERP/AIO/KW/Backlinks T3) + GEO Enrichments (Wikidata/PAA/Schema validator) + Content Gap + Tier 2 + Multi-page + AI Hallucination Check + Citation Tracker + Fan-out + Plan d'action priorisé + Score Visibilité IA + Executive Summary.

Body

Param	Type	Description
`url` required	string	URL absolue à auditer
`options.timeout`	number	Timeout crawl en ms (défaut 15000)
`options.skipLive`	bool	Désactive Citation/Fanout/SXO/Hallucination même si OPENROUTER_API_KEY présente
`options.skipVisual`	bool	Désactive Playwright/Browserless
`options.promptCount`	5-15	Nombre de prompts Citation Tracker (défaut 8)
`options.enablePlacesLookup`	bool	Active appel Google Places (payant)

Réponse (résumé)

JSON 200 OK{
  "id": "uuid",
  "url": "https://example.com",
  "timestamp": "2026-05-08T...",
  "duration_ms": 87432,
  "geo": { "score": 72, "grade": "B" },
  "seo": { "score": 81, "grade": "B+" },
  "visibility": { "score": 76, "grade": "B" },
  "geo_audit": { /* full GEO audit */ },
  "seo_audit": { /* full SEO audit */ },
  "live": {
    "prefill": { "brand": "Example", "niche": "…" },
    "citation": { "citationFrequency": 42, "shareOfVoice": 28, "models": [...] },
    "fanout": { "overallCoverage": 65, "gaps": [...] },
    "cwv": { "psi": {...}, "cruxMobile": {...} },
    "backlinks": { "moz": {...}, "commonCrawl": {...} },
    "sxo": { "pageType": {...}, "personaReport": {...} },
    "local": { "nap": {...}, "businessType": {...} },
    "dataforseo": { "serp": {...}, "keywords": [...], "aiOverviews": {...} },
    "geoEnrichments": { "wikidata": {...}, "schemaValidator": {...} },
    "contentGap": { "coverageScore": 58, "gaps": [...] },
    "tier2": { "outranking": {...}, "jsRendering": {...} },
    "multipage": { "totalCrawled": 42, "siteHealthScore": 73 },
    "aiHallucination": { "score": 85, "grade": "B", "findings": [...] },
    "errors": [...]
  },
  "action_plan": [{ "priority": 1, "source": "hallucination", ... }],
  "cost": { "totalUsd": 0.18, "byModule": {...} },
  "ai_visibility": { "score": 68, "grade": "B", "components": {...} },
  "executive_summary": { "verdict": "…", "topPriorities": [...] }
}

POST /api/audit/full/stream SSE

Identique à /api/audit/full mais retourne un flux Server-Sent Events. Émet des événements de progression : plan (liste des modules), module:start, module:done, module:skip, warning, et result final. Idéal pour UI temps réel.

Format des événements

SSEevent: plan
data: {"modules":[{"id":"crawl","label":"Crawl","enabled":true},...]}

event: module:start
data: {"id":"cwv","at":1715189000000}

event: module:done
data: {"id":"cwv","durationMs":4521,"ok":true,"summary":"Lighthouse mobile=72 · INP=needs-improvement"}

event: result
data: { /* CombinedAuditResponse complet */ }

POST /api/audit/quick core

Audit GEO rapide ~3s : score global, grade, top fixes prioritaires uniquement. Pas de modules live. Idéal pour widget badge ou intégration légère.

JSON 200{
  "score": 68,
  "grade": "B",
  "topFixes": [{ "category": "citability", "impact": "high", ... }]
}

Audit GEO

POST /api/audit core

Audit GEO complet : 67 checks répartis en 8 catégories (citabilité, technique, schema, contenu E-E-A-T, brand, accessibilité, réputation, plateformes IA).

Body{ "url": "https://example.com", "options": { "timeout": 15000 } }

GET /api/audit/:id core

Récupère un audit précédemment généré (cache mémoire, TTL 1h).

Audits GEO par catégorie

Lance uniquement la catégorie ciblée — utile pour itérer sur une dimension précise.

POST /api/audit/citability core

Citabilité IA : answer-blocks (extractables par LLM), self-containment, FAQ, glossaires, listes structurées.

POST /api/audit/technical core

Technique IA : robots.txt, llms.txt, sitemap, HTTPS, redirections, headers, accessibilité aux bots IA (GPTBot, ClaudeBot, PerplexityBot…).

POST /api/audit/schema core

Schema.org JSON-LD : Organization, Article, FAQ, Product, LocalBusiness, sameAs, breadcrumbs.

POST /api/audit/content core

Contenu E-E-A-T : profondeur, dates, auteur, sources, multi-format (texte/image/vidéo), structure H1-H6.

POST /api/audit/brands core

Brand presence : Wikipedia, YouTube, Reddit, Crunchbase, sameAs JSON-LD.

POST /api/audit/platforms core

Compatibilité 5 plateformes IA : ChatGPT/GPTBot, Claude/ClaudeBot, Perplexity, Google AI, Bing Chat. Détection blocage Cloudflare AI.

POST /api/audit/crawlers core

Test d'accès par user-agent IA (probes réels avec UA bot) — détecte les blocages 403, contenu tronqué, captchas.

Endpoints spécialisés GEO

POST /api/audit/llmstxt core

Audit dédié des fichiers llms.txt et llms-full.txt : présence, format, sections, conformité au standard llms.txt 0.9.

POST /api/audit/schema/generate core

Génère du JSON-LD prêt à coller à partir du contenu de la page : Organization, Article, FAQ, BreadcrumbList. Détection auto du type de page.

Audit SEO

POST /api/seo-audit core

Audit SEO classique : 74 checks répartis en 9 catégories (on-page, technical, performance, content E-E-A-T, structured data, crawlability, mobile UX, authority, AI readiness).

Body{ "url": "https://example.com", "options": { "categories": ["onpage", "technical_seo"] } }

Audits SEO par catégorie

Endpoint	Catégorie	Couvre
`POST /api/seo-audit/on-page`	On-Page	title, meta, H1-H6, alt, anchors, canonicals
`POST /api/seo-audit/technical`	Technical SEO	HTTPS, redirections, status codes, robots, headers
`POST /api/seo-audit/content`	Content E-E-A-T	profondeur, expertise, autorité, fraîcheur
`POST /api/seo-audit/structured-data`	Structured Data	JSON-LD, microdata, RDFa, sameAs
`POST /api/seo-audit/performance`	Performance	poids HTML, ressources, LCP/CLS hints (sans CrUX)
`POST /api/seo-audit/crawlability`	Crawlability	sitemap, robots, internal linking, depth
`POST /api/seo-audit/mobile`	Mobile & UX	viewport, font-size, tap targets, responsive
`POST /api/seo-audit/authority`	Authority	liens sortants, backlinks (si Moz/CC), trust signals
`POST /api/seo-audit/ai-readiness`	AI Readiness	llms.txt, FAQ, citability blocks, schema

Modules unitaires

Endpoint dynamique permettant de lancer UN seul module (Core Web Vitals, Backlinks, Hallucination, Citation Tracker, etc.) sans relancer tout l'audit FULL. Utilisé par la sidebar UI « Modules d'audit ».

GET /api/audit/module core

Catalogue des 18 modules disponibles avec leur statut ready/missing selon les variables d'environnement configurées côté serveur.

JSON 200{
  "modules": [
    { "id": "cwv", "label": "Core Web Vitals", "group": "Crawl & basics",
      "requires": ["GOOGLE_API_KEY"], "ready": true, "missing": [], "etaSec": 15,
      "costHint": "≈ 0.001$" },
    ...
  ],
  "envAvailable": { "OPENROUTER_API_KEY": true, "MOZ_API_KEY": true, ... },
  "totalModules": 18,
  "readyCount": 15
}

POST /api/audit/module/:moduleId unitaire

Lance UN module isolé. Charge UNIQUEMENT les prérequis nécessaires (crawl, prefill brand) pour ce module — pas d'audit complet.

Modules supportés

moduleId	Tier	Description	Prérequis env
`crawl`	core	HTML + robots + llms.txt + sitemap + probes IA	—
`geo`	core	Audit GEO 67 checks	—
`seo`	core	Audit SEO 74 checks	—
`cwv`	premium	PSI v5 + CrUX 25 semaines (LCP, INP, CLS)	`GOOGLE_API_KEY`
`backlinks`	premium	Common Crawl + Moz API	`MOZ_API_KEY` (optionnel)
`hreflang`	core	Validation cross-page A↔B des return tags	—
`visual`	core	Screenshots multi-viewport + cookie banner GDPR	—
`prefill`	live	Extraction LLM brand/niche/concurrents	`OPENROUTER_API_KEY`
`sxo`	live	Page-type + 4 personas (Relevance × Clarity × Trust × Action)	`OPENROUTER_API_KEY`
`local`	premium	NAP + business profile + Google Places + 10 schemas	`GOOGLE_PLACES_API_KEY`
`dataforseo`	premium	SERP top 10 + KW data + AI Overviews + Backlinks T3	`DATAFORSEO_AUTH`
`geoEnrichments`	core	PAA + Featured Snippet + Wikidata + Schema validator	—
`contentGap`	premium	Crawl top 3 SERP + comparaison topics LLM	`OPENROUTER_API_KEY` + `DATAFORSEO_AUTH`
`tier2`	core	Outranking + JS rendering diff + Image deep + CRO	—
`multipage`	core	Sitemap parser ou BFS depth=2 (50 pages)	—
`aiHallucination`	premium	Cross-check 4 LLMs vs site officiel	`OPENROUTER_API_KEY`
`citation`	live	Citation Tracker multi-LLM (freq, SoV, sentiment)	`OPENROUTER_API_KEY`
`fanout`	live	Fan-out Coverage (décomposition de requête)	`OPENROUTER_API_KEY`

Body

Param	Type	Description
`url` required	string	URL absolue
`options.brand`	string	Évite un appel prefill pour les modules brand-aware
`options.niche`	string	Évite un appel prefill
`options.competitors`	array	Liste de domaines concurrents (citation, dataforseo)
`options.skipVisual`	bool	Pour module `visual`
`options.promptCount`	5-15	Pour module `citation`
`options.enablePlacesLookup`	bool	Pour module `local`

Réponse

JSON 200{
  "moduleId": "cwv",
  "ok": true,
  "durationMs": 4521,
  "prerequisites": [],         // modules exécutés en cascade
  "data": { /* payload spécifique au module */ }
}

Skip et erreurs Si une variable d'env manque, l'endpoint retourne {"ok":false, "skipped":"..."} en HTTP 200 (pas une erreur). En cas d'erreur réelle (timeout, API down) : {"ok":false, "error":"..."}.

LLM live

Endpoints dédiés aux modules LLM cross-modèles via OpenRouter (Gemini 2.5 Flash, GPT-4o mini, Claude Haiku 4.5, Perplexity Sonar).

POST /api/citation live

Citation Tracker multi-LLM. Pour chaque prompt et chaque modèle, mesure : citation de la marque (Y/N), share of voice vs concurrents, sentiment (positif/neutre/négatif), position dans la réponse.

Body

JSON{
  "brand": "Example Inc",            // requis
  "competitors": ["Acme", "Foobar"], // optionnel
  "prompts": ["meilleurs CRM 2026", ...],// requis (5-15)
  "models": ["google/gemini-2.5-flash", ...]// optionnel
}

Génération auto de prompts Si vous ne fournissez pas prompts, utilisez POST /api/citation/prefill pour les générer à partir de la niche.

POST /api/citation/prefill live

Prefill : extrait brand, niche, suggestedCompetitors à partir d'une URL via LLM. Utilisé pour pré-remplir les autres endpoints LLM.

Body

JSON{ "url": "https://example.com" }

Réponse

JSON 200{
  "url": "https://example.com",
  "brand": "Example Inc",
  "niche": "CRM SaaS B2B",
  "suggestedCompetitors": ["Salesforce", "HubSpot", "Pipedrive"],
  "extracted": { "title": ..., "organizationName": ... }
}

POST /api/fanout live

Fan-out Coverage : décompose une requête principale en 6 sous-requêtes via LLM, puis score la couverture du contenu pour chaque sous-requête. Identifie les gaps thématiques.

Body

JSON{
  "url": "https://example.com",
  "query": "meilleurs outils SEO 2026",
  "subqueryCount": 6
}

Exports

POST /api/audit/report export

Génère un rapport HTML standalone (CSS inline, fonts inline, livrable client premium). Sidebar sticky, recherche live, filtres par statut, sections collapsibles, scroll spy. Utilise un ExportPlanInput ou directement un CombinedAuditResponse.

Réponse

text/html<!DOCTYPE html>
<html>
  <!-- Rapport autonome (200-400 KB) -->
</html>

POST /api/audit/report-pdf export

Rend le rapport HTML en PDF via Playwright headless. Format A4, marges optimisées impression, page de garde, sommaire numéroté.

Réponse

application/pdf%PDF-1.7 ...

Variables d'environnement

Toutes les clés sont optionnelles — les modules concernés passent en mode dégradé (skip avec message d'info) si absentes.

Variable	Module	Coût
`OPENROUTER_API_KEY`	Citation, Fanout, SXO, Prefill, Hallucination, ContentGap	~0.001-0.05$/run
`GOOGLE_API_KEY`	PSI v5 + CrUX (Core Web Vitals)	Gratuit (quotas)
`MOZ_API_KEY`	Backlinks Tier 1 (DA, PA, Spam Score, linking domains)	2500 rows/mois free
`GOOGLE_PLACES_API_KEY`	Local SEO — NAP cross-platform	~0.025$/lookup
`DATAFORSEO_AUTH`	SERP, KW, AIO, Backlinks T3, Content Gap	~0.05-0.10$/run
`BROWSERLESS_URL` + `BROWSERLESS_TOKEN`	Visual screenshots si Playwright local indispo	~0.005$/screenshot
`RATE_LIMIT_PER_IP_PER_MINUTE`	Hardening (défaut 5)	—
`RATE_LIMIT_PER_IP_PER_HOUR`	Hardening (défaut 30)	—
`BUDGET_*_USD_PER_DAY`	Circuit breaker quotidien par API (PSI/MOZ/PLACES/OPENROUTER/DATAFORSEO)	—
`ALLOW_LOCALHOST_AUDIT`	Bypass SSRF guard pour dev local	—

Erreurs & rate limits

Codes HTTP

Code	Cause	Action
`400`	Body JSON invalide, URL malformée, SSRF blocked	Vérifier le format du body et l'URL
`429`	Rate limit dépassé (per-minute ou per-hour)	Voir headers `Retry-After`, `X-RateLimit-Reset`
`502`	Site cible inaccessible (timeout, DNS, 5xx)	Réessayer, vérifier disponibilité cible
`500`	Erreur serveur interne	Reporter avec le payload

Format d'erreur

JSON 4xx/5xx{
  "error": "Description lisible",
  "code": "SSRF_BLOCKED",    // optionnel
  "details": { ... }              // optionnel (Zod field errors)
}

Headers rate limit

HTTP 429X-RateLimit-Limit: 5
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1715189832
Retry-After: 47

Docker / déploiement

Image Docker

bashdocker build -t geo-audit-api .
docker run -p 3000:3000 \
  -e OPENROUTER_API_KEY=sk-or-... \
  -e GOOGLE_API_KEY=AIza... \
  -e MOZ_API_KEY=... \
  -e DATAFORSEO_AUTH=<base64-login:password> \
  geo-audit-api

Stack

Next.js 15.5 (App Router) + Turbopack
TypeScript 5.8 strict
React 19 + Tailwind CSS 4
Cheerio 1.0 (parsing HTML)
Zod 3.24 (validation runtime)
Vitest 3.2 (108 tests)
Playwright optionnel (visual capture)

GEO Audit API — Documentation

Vue d'ensemble

URL de base

Authentification

Démarrage rapide

1. Audit GEO basique (67 checks, ~10s)

2. Audit FULL (GEO + SEO + LLM live + DataForSEO, ~90s)

3. Lancer UN seul module (ex: Core Web Vitals seul)

Tiers d'endpoints

Audit consolidé

Body

Réponse (résumé)

Format des événements

Audit GEO

Audits GEO par catégorie

Endpoints spécialisés GEO

Audit SEO

Audits SEO par catégorie

Modules unitaires

Modules supportés

Body

Réponse

LLM live

Body

Body

Réponse

Body

Exports

Réponse

Réponse

Variables d'environnement

Erreurs & rate limits

Codes HTTP

Format d'erreur

Headers rate limit

Docker / déploiement

Image Docker

Stack