Riferimento API

Questa pagina fornisce il riferimento completo dell'interfaccia a riga di comando per tutti e tre gli script di GEO Optimizer, lo schema JSON completo dell'output di geo_audit.py e un workflow GitHub Actions pronto all'uso per l'auditing GEO automatizzato.

geo_audit.py

Esegue un audit completo di conformità GEO su un URL di destinazione e restituisce un punteggio da 0 a 100.

Flag

Flag	Tipo	Obbligatorio	Default	Descrizione
--url	string	Sì	--	URL del sito web da analizzare
--format	string	No	text	Formato di output: text o json
--output	string	No	stdout	Percorso del file in cui scrivere i risultati
--verbose	flag	No	off	Mostra i dati grezzi dettagliati per ogni controllo

Esempi

# Audit testuale base
./geo scripts/geo_audit.py --url https://example.com

# Output JSON per uso programmatico
./geo scripts/geo_audit.py --url https://example.com --format json

# Debug verbose
./geo scripts/geo_audit.py --url https://example.com --verbose

# Salva il report JSON su file
./geo scripts/geo_audit.py --url https://example.com --format json --output audit.json

# Combinazione: JSON verbose su file
./geo scripts/geo_audit.py --url https://example.com --format json --verbose --output debug-report.json

Schema dell'output JSON

Quando viene usato --format json, l'output segue questa struttura:

{
  "url": "https://example.com",
  "timestamp": "2026-02-24T10:30:00.000Z",
  "score": 82,
  "band": "good",
  "checks": {
    "robots_txt": {
      "score": 18,
      "max": 20,
      "passed": true,
      "details": {
        "found": true,
        "citation_bots_ok": true,
        "bots_allowed": ["OAI-SearchBot", "ClaudeBot", "PerplexityBot", "Googlebot"],
        "bots_blocked": [],
        "bots_missing": ["GPTBot"]
      }
    },
    "llms_txt": {
      "score": 14,
      "max": 20,
      "passed": true,
      "details": {
        "found": true,
        "word_count": 1247,
        "has_h1": true,
        "section_count": 4,
        "link_count": 2
      }
    },
    "schema_jsonld": {
      "score": 20,
      "max": 25,
      "passed": false,
      "details": {
        "schemas_found": ["WebSite", "FAQPage"],
        "schemas_missing": ["WebApplication"],
        "website_valid": true,
        "faqpage_valid": true,
        "webapp_valid": false
      }
    },
    "meta_tags": {
      "score": 18,
      "max": 20,
      "passed": true,
      "details": {
        "title": "Example Corp - Data Analytics Platform",
        "title_length": 42,
        "description": "Enterprise solutions for real-time data analytics and business intelligence.",
        "description_length": 73,
        "has_canonical": true,
        "has_og_title": true,
        "has_og_description": true,
        "has_og_image": false,
        "has_og_url": true
      }
    },
    "content": {
      "score": 12,
      "max": 15,
      "passed": true,
      "details": {
        "has_h1": true,
        "h1_text": "Enterprise Data Analytics",
        "heading_count": 12,
        "word_count": 2840,
        "stat_references": 8,
        "external_links": 0
      }
    }
  },
  "recommendations": [
    "Add WebApplication JSON-LD schema for tool/utility pages",
    "Add external citation links to authoritative sources",
    "Include og:image meta tag for social sharing",
    "Explicitly allow GPTBot in robots.txt"
  ]
}

Fasce di punteggio

Fascia	Intervallo	Valore JSON
Eccellente	91--100	"excellent"
Buono	71--90	"good"
Base	41--70	"foundation"
Critico	0--40	"critical"

---

generate_llms_txt.py

Genera automaticamente un file /llms.txt dalla sitemap di un sito web.

Flag

Flag	Tipo	Obbligatorio	Default	Descrizione
--base-url	string	Sì	--	URL radice del sito web
--output	string	No	stdout	Percorso del file in cui salvare il llms.txt generato
--sitemap	string	No	auto-detect	URL della sitemap manuale
--site-name	string	No	--	Nome personalizzato del sito per l'intestazione
--description	string	No	--	Descrizione del sito (mostrata come blockquote)
--fetch-titles	flag	No	off	Recupera i titoli effettivi delle pagine tramite richieste HTTP
--max-per-section	int	No	20	Numero massimo di URL per categoria

Esempi

# Rilevamento automatico della sitemap e output su stdout
./geo scripts/generate_llms_txt.py --base-url https://example.com

# Tutte le opzioni con file di output
./geo scripts/generate_llms_txt.py \
  --base-url https://example.com \
  --site-name "Example Corp" \
  --description "Enterprise data analytics" \
  --fetch-titles \
  --max-per-section 15 \
  --output public/llms.txt

# Sitemap manuale
./geo scripts/generate_llms_txt.py \
  --base-url https://example.com \
  --sitemap https://example.com/post-sitemap.xml \
  --output llms.txt

---

schema_injector.py

Genera, valida, analizza e inietta dati strutturati JSON-LD nei file HTML.

Flag

Flag	Tipo	Obbligatorio	Default	Descrizione
--file	string	Dipende	--	File HTML da analizzare o modificare
--analyze	flag	No	off	Analizza gli schema esistenti (sola lettura)
--inject	flag	No	off	Inietta lo schema generato nel file
--type	string	No	--	Tipo di schema: website, webapp, faq, article, organization, breadcrumb
--name	string	No	--	Nome del sito o dell'applicazione
--url	string	No	--	URL del sito
--description	string	No	--	Testo descrittivo
--author	string	No	--	Nome dell'autore
--logo-url	string	No	--	URL dell'immagine del logo
--faq-file	string	No	--	File JSON contenente le voci FAQ
--auto-extract	flag	No	off	Rileva automaticamente il contenuto FAQ dall'HTML
--astro	flag	No	off	Output snippet compatibile con Astro
--no-backup	flag	No	off	Salta la creazione del backup .bak
--no-validate	flag	No	off	Salta la validazione dello schema prima dell'iniezione
--verbose	flag	No	off	Mostra il JSON completo dello schema durante l'analisi

Esempi

# Analizza quali schema esistono in un file
./geo scripts/schema_injector.py --file dist/index.html --analyze

# Genera uno schema WebSite su stdout
./geo scripts/schema_injector.py \
  --type website \
  --name "Example Corp" \
  --url https://example.com \
  --description "Enterprise analytics"

# Inietta uno schema Organization nell'HTML
./geo scripts/schema_injector.py \
  --file dist/about.html \
  --inject \
  --type organization \
  --name "Example Corp" \
  --url https://example.com \
  --logo-url https://example.com/logo.png

# FAQ con estrazione automatica
./geo scripts/schema_injector.py \
  --file dist/faq.html \
  --inject \
  --type faq \
  --auto-extract

# Snippet compatibile con Astro
./geo scripts/schema_injector.py \
  --type webapp \
  --name "GEO Audit Tool" \
  --url https://example.com/tools/audit \
  --astro

---

Integrazione CI/CD

Workflow GitHub Actions

Aggiungi l'auditing GEO automatizzato alla tua pipeline CI/CD. Questo workflow viene eseguito ad ogni push su main e interrompe la build se il punteggio GEO scende al di sotto di una soglia configurabile.

name: GEO Audit

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

env:
  GEO_MIN_SCORE: 70
  SITE_URL: https://example.com

jobs:
  geo-audit:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: '3.12'

      - name: Install GEO Optimizer
        run: |
          git clone https://github.com/auriti-web-design/geo-optimizer-skill.git /tmp/geo-optimizer
          cd /tmp/geo-optimizer
          python -m venv .venv
          source .venv/bin/activate
          pip install -r requirements.txt

      - name: Run GEO Audit
        id: audit
        run: |
          cd /tmp/geo-optimizer
          source .venv/bin/activate
          python scripts/geo_audit.py --url ${{ env.SITE_URL }} --format json --output /tmp/geo-report.json
          SCORE=$(python -c "import json; print(json.load(open('/tmp/geo-report.json'))['score'])")
          echo "score=$SCORE" >> $GITHUB_OUTPUT
          echo "GEO Score: $SCORE"

      - name: Check Score Threshold
        run: |
          if [ ${{ steps.audit.outputs.score }} -lt ${{ env.GEO_MIN_SCORE }} ]; then
            echo "::error::GEO score (${{ steps.audit.outputs.score }}) is below minimum threshold (${{ env.GEO_MIN_SCORE }})"
            exit 1
          fi
          echo "GEO score (${{ steps.audit.outputs.score }}) meets minimum threshold (${{ env.GEO_MIN_SCORE }})"

      - name: Upload Report
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: geo-audit-report
          path: /tmp/geo-report.json
          retention-days: 30

      - name: Comment on PR
        if: github.event_name == 'pull_request'
        uses: actions/github-script@v7
        with:
          script: |
            const fs = require('fs');
            const report = JSON.parse(fs.readFileSync('/tmp/geo-report.json', 'utf8'));
            const badge = report.score >= 91 ? '🟢' : report.score >= 71 ? '🟡' : report.score >= 41 ? '🟠' : '🔴';
            const body = `## GEO Audit Report ${badge}\n\n` +
              `**Score: ${report.score}/100** (${report.band})\n\n` +
              `| Section | Score |\n|---------|-------|\n` +
              `| robots.txt | ${report.checks.robots_txt.score}/${report.checks.robots_txt.max} |\n` +
              `| llms.txt | ${report.checks.llms_txt.score}/${report.checks.llms_txt.max} |\n` +
              `| JSON-LD | ${report.checks.schema_jsonld.score}/${report.checks.schema_jsonld.max} |\n` +
              `| Meta Tags | ${report.checks.meta_tags.score}/${report.checks.meta_tags.max} |\n` +
              `| Content | ${report.checks.content.score}/${report.checks.content.max} |\n\n` +
              (report.recommendations.length > 0 ?
                `**Recommendations:**\n${report.recommendations.map(r => `- ${r}`).join('\n')}` : '');
            github.rest.issues.createComment({
              issue_number: context.issue.number,
              owner: context.repo.owner,
              repo: context.repo.repo,
              body
            });

Utilizzo programmatico dell'output JSON

L'output JSON è progettato per l'elaborazione automatica. Puoi analizzarlo in qualsiasi linguaggio:

import json
import sys

with open("geo-report.json") as f:
    report = json.load(f)

# Condizionare il deploy al punteggio
if report["score"] < 70:
    print(f"GEO score too low: {report['score']}/100")
    sys.exit(1)

# Controllare sezioni specifiche
if not report["checks"]["robots_txt"]["details"]["citation_bots_ok"]:
    print("WARNING: Citation bots are not properly configured in robots.txt")

# Bash: estrarre il punteggio con jq
SCORE=$(jq '.score' geo-report.json)
BAND=$(jq -r '.band' geo-report.json)
echo "GEO Score: $SCORE ($BAND)"

---

Prossimo: Architettura -- i 9 metodi GEO di Princeton, l'algoritmo di scoring e l'ecosistema dei bot AI.