--- name: cendoj-toolkit-joserprieto title: 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. author: joserprieto author_url: https://github.com/joserprieto/ai-skills/tree/main/skills/cendoj-toolkit license: MIT version: 0.1.0 execution_mode: open jurisdiction: es practice: litigation language: es sources: - title: Cendoj Legal Notice path: references/cendoj-legal-notice.md - title: Compliance Checklist path: references/compliance-checklist.md - title: Url Patterns path: references/url-patterns.md --- # 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: ```bash 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. ```bash python scripts/cendoj_search.py --query "Avincis" --output results.json ``` Output JSON schema (one entry per result): ```json [ { "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. ```bash 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. ```bash python scripts/cendoj_pdf_to_md.py \ --input-dir ./pdfs/ \ --output-dir ./markdown/ \ --engine pdfminer ``` ## Full pipeline (recommended workflow) ```bash # 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).