cendoj-toolkit

name	cendoj-toolkit
description	Use when the user needs to search and download court decisions from CENDOJ (Centro de Documentación Judicial del Consejo General del Poder Judicial), the Spanish official judicial database. Also when user says "buscar sentencias", "descargar sentencia CENDOJ", "jurisprudencia CENDOJ", "ECLI", or provides a poderjudicial.es URL. STRICTLY for personal/individual use (uso particular). Bulk downloads or commercial use are explicitly forbidden by CENDOJ legal notice and require formal authorization from CGPJ.
license	MIT
metadata	{"author":"Jose R. Prieto (hi [at] joserprieto [dot] es)","version":"0.1.0","last_verified":"2026-05-23","legal-notice":"Strict compliance with CENDOJ terms of use (uso particular only)"}

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 https://www.poderjudicial.es/cgpj/es/Servicios/Centro-de-Documentacion-Judicial).

Robots.txt compliance

CENDOJ robots.txt (https://www.poderjudicial.es/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).