Cendoj Toolkit

CENDOJ Toolkit

Search and download Spanish court decisions from CENDOJ (Centro de Documentación Judicial del Consejo General del Poder Judicial) for personal use only.

⚠️ LEGAL NOTICE — READ BEFORE USING

CENDOJ's official legal notice (verbatim from their portal):

> Las resoluciones que componen esta base de datos se difunden a efectos de conocimiento y consulta > de los criterios de decisión de los Tribunales, en cumplimiento de la competencia otorgada al > Consejo General del Poder Judicial por el art. 560.1.10º de la Ley Orgánica del Poder Judicial. > > El usuario de la base de datos podrá consultar los documentos siempre que lo haga para su uso > particular. > > No está permitida la utilización de la base de datos para usos comerciales, ni la descarga > masiva de información. La reutilización de esta información para la elaboración de bases de > datos o con fines comerciales debe seguir el procedimiento y las condiciones establecidas por el > CGPJ a través de su Centro de Documentación Judicial.

Permitted use cases (uso particular):

• Defending your own legal case (employee/citizen looking up case law for your dispute)
• Academic research on jurisprudence (with citation, non-commercial)
• Personal legal study or preparation
• Lawyer preparing defense for a specific client case

Forbidden use cases:

• Building commercial legal databases
• Aggregating CENDOJ content for resale or commercial AI training
• Indiscriminate bulk downloading
• Republishing CENDOJ content as a competing service

If you intend a commercial use, you must request formal authorization from CGPJ (see ).

Robots.txt compliance

CENDOJ robots.txt () sets:

User-agent: *
Crawl-delay: 5

This skill enforces Crawl-delay: 5 (5 seconds between requests) as the non-negotiable minimum. Do not lower this without explicit CGPJ authorization.

Prerequisites

| Tool | Min Version | Purpose | Install | | --------------------------- | ----------- | ---------------------------------- | ------------------------------------------------------- | | Python | >= 3.10 | Run scripts | brew install python or mise install python | | playwright | latest | Form-based search (CENDOJ uses JS) | pip install playwright && playwright install chromium | | requests | latest | PDF download | pip install requests | | pdfminer.six or docling | latest | PDF → text/markdown conversion | pip install pdfminer.six or pip install docling |

Install all dependencies:

pip install playwright requests pdfminer.six
playwright install chromium

Capabilities

This skill provides three composable scripts:

1. cendoj_search.py — Search by free text

Performs a free-text search on CENDOJ via Playwright (the search form is JS-driven, plain HTTP POST doesn't work reliably). Returns a JSON inventory of all results with ECLI codes + reference IDs needed for PDF download.

python scripts/cendoj_search.py --query "Avincis" --output results.json

Output JSON schema (one entry per result):

[
  {
    "title": "STSJ Galicia, a 06 de febrero de 2026 - ROJ: STSJ GAL 1040/2026",
    "ecli": "ECLI:ES:TSJGAL:2026:1040",
    "tribunal": "TSJ Galicia",
    "city": "Coruña (A)",
    "date_iso": "2026-02-06",
    "resolution_number": "572/2026",
    "appeal_number": "3429/2025",
    "ponente": "EVA MARIA DOVAL LORENTE",
    "summary": "DESPIDO DISCIPLINARIO",
    "reference": "a73e3b3c0538644fa0a8778d75e36f0d",
    "optimize": "20260316",
    "open_document_url": "https://www.poderjudicial.es/search/AN/openDocument/a73e3b3c0538644fa0a8778d75e36f0d/20260316",
    "pdf_url": "https://www.poderjudicial.es/search/contenidos.action?action=accessToPDF&publicinterface=true&tab=AN&reference=a73e3b3c0538644fa0a8778d75e36f0d&encode=true&optimize=20260316&databasematch=AN"
  }
]

2. cendoj_download.py — Download PDFs from inventory

Takes the JSON inventory produced by cendoj_search.py and downloads each PDF respecting Crawl-delay: 5 enforced minimum. Calculates SHA-256 for each downloaded file. Generates an INVENTARIO.md summary table.

python scripts/cendoj_download.py \
  --input results.json \
  --output-dir ./pdfs/ \
  --max-downloads 50 \
  --delay 5

Safety limits:

• --max-downloads defaults to 50 (hard maximum 200, configurable but printed warning)
• --delay defaults to 5 seconds (hard minimum 5, cannot be lowered)
• Existing files are skipped (idempotent re-runs)
• Each PDF is validated post-download (must be PDF magic bytes)

3. cendoj_pdf_to_md.py — Convert downloaded PDFs to markdown

Converts each PDF in a directory to markdown using pdfminer.six (default) or docling (with --engine docling). Preserves structure best-effort.

python scripts/cendoj_pdf_to_md.py \
  --input-dir ./pdfs/ \
  --output-dir ./markdown/ \
  --engine pdfminer

Full pipeline (recommended workflow)

# 1. Search
python scripts/cendoj_search.py --query "Avincis" --output results.json

# 2. Review results.json manually — confirm "uso particular" applies to your case

# 3. Download PDFs (respects 5s crawl-delay automatically)
python scripts/cendoj_download.py --input results.json --output-dir ./pdfs/

# 4. Convert to markdown
python scripts/cendoj_pdf_to_md.py --input-dir ./pdfs/ --output-dir ./markdown/

Verification of compliance

Every script execution:

1. Prints the CENDOJ legal notice as the first output
2. Asks explicit user confirmation before downloading (if --max-downloads > 10)
3. Logs all requests with timestamps for audit trail
4. Refuses to lower --delay below 5 seconds

URL patterns documented

For developers extending this skill or doing manual URL construction:

Search results format (from openDocument links in HTML)

https://www.poderjudicial.es/search/AN/openDocument/{REFERENCE}/{OPTIMIZE}

Where:

• {REFERENCE} = hex hash (16 or 32 chars depending on era of insertion)
• {OPTIMIZE} = YYYYMMDD (date inserted/last optimized in CENDOJ DB)

PDF direct download URL

https://www.poderjudicial.es/search/contenidos.action
  ?action=accessToPDF
  &publicinterface=true
  &tab=AN
  &reference={REFERENCE}
  &encode=true
  &optimize={OPTIMIZE}
  &databasematch=AN

Required HTTP headers (CENDOJ filters generic curl):

User-Agent: Mozilla/5.0 (...) [browser-like UA required]
Accept: application/pdf,*/*
Referer: https://www.poderjudicial.es/search/indexAN.jsp

Limitations

• The search form is JS-driven; cannot use plain HTTP POST (need Playwright)
• The databasematch=AN parameter covers all jurisdictions (TS, AN, TSJ, AP, JSO). No separate

parameter set needed by jurisdiction

• Pre-2015 sentences have shorter 16-char references; same URL pattern applies
• ECLI codes are stable across CENDOJ updates; references may rotate (rare but documented)

References

• references/cendoj-legal-notice.md — full CENDOJ legal notice verbatim (ES)
• references/url-patterns.md — detailed URL pattern documentation
• references/compliance-checklist.md — pre-execution compliance checklist

License

MIT for the toolkit code. The downloaded CENDOJ content remains property of CENDOJ and is subject to their terms of use (uso particular only).

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: joserprieto
• Source: joserprieto/ai-skills
• License: MIT

Install and usage instructions live in the source repository linked above.