@macalc/aeo-score

Score the AEO (Answer Engine Optimization) readiness of any HTML page on a 0–100 scale — how easily AI answer engines (ChatGPT, Perplexity, Google AI Overviews, Claude) can read, trust and cite it.

Zero dependencies. Works in Node.js (≥18) and any bundler. Same scoring engine that powers the free web tool at lescreavores.fr/outils/audit-aeo-gratuit.

Why AEO?

Classic SEO optimizes for blue links. AEO optimizes for being quoted inside an AI answer. The signals differ: machine-readable structure, an answer-first block, question headings, FAQ markup, a clear publishing entity and freshness. This library scores a page against those signals.

Install

npm install @macalc/aeo-score

Usage

import { scoreHtml } from "@macalc/aeo-score";

const html = await fetch("https://example.com/article").then((r) => r.text());
const result = scoreHtml(html, { url: "https://example.com/article" });

console.log(result.score);   // e.g. 72
console.log(result.verdict); // "Good — clear optimizations can win more citations."
console.table(result.subScores);
result.issues.forEach((i) => console.log(`[${i.severity}] ${i.label} → ${i.fix}`));

Result shape

{
  "scannedUrl": "https://example.com/article",
  "score": 72,
  "verdict": "Good — clear optimizations can win more citations.",
  "subScores": {
    "crawlabilite": { "value": 28, "max": 30, "label": "AI crawlability" },
    "structure":    { "value": 27, "max": 35, "label": "Answer structure" },
    "confiance":    { "value": 17, "max": 35, "label": "Trust & E-E-A-T" }
  },
  "issueCount": 4,
  "issues": [
    {
      "id": "no-author",
      "severity": "low",
      "module": "confiance",
      "label": "No identifiable author on the page.",
      "fix": "Show an author with a link to their profile page: a strong E-E-A-T signal."
    }
  ],
  "checkedAt": "2026-06-16T10:00:00.000Z"
}

Scoring model

| Module | Max | What it checks | |---|---|---| | AI crawlability | 30 | Indexable (no noindex), valid JSON-LD, lang, canonical | | Answer structure | 35 | Single H1, clean heading hierarchy, answer-first block, question headings, FAQ | | Trust & E-E-A-T | 35 | Publishing entity, content type, FAQ/HowTo schema, date, author, external sources |

A score ≥ 80 means the page is well armed to be cited; < 40 means AI engines can barely use it. Every lost point comes with an actionable fix.

API

• scoreHtml(html, { url }) → result object.
• scoreSnapshot(snapshot) → score a snapshot you built yourself.
• buildSnapshot(html, { url }) → extract the raw signals.
• verdictFor(score) → the verdict string for a 0–100 score.

CI example

Fail a build when a page drops below a citability threshold:

import { scoreHtml } from "@macalc/aeo-score";
const { score } = scoreHtml(renderedHtml, { url });
if (score < 70) process.exit(1);

About

Built and maintained by Les Créavores, a French web agency specialised in SEO and AEO. See our pricing barometer dataset (CC-BY, DOI 10.5281/zenodo.20690911) and the free AEO audit tool.

License

MIT © Les Créavores