# European Court of Human Rights - Case Law Search (HUDOC) (`legaltech/tedh`) Actor

Search ECHR judgments and decisions in HUDOC (official): full text with AND/OR/NOT, filters by state, article, violation, importance; headnote and operative part.

- **URL**: https://apify.com/legaltech/tedh.md
- **Developed by:** [Miguel González](https://apify.com/legaltech) (community)
- **Features:** Limited permissions
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $1.00 / 1,000 results

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.
Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

### European Court of Human Rights - Case Law Search (HUDOC)

Searches the case law of the European Court of Human Rights (ECHR, Strasbourg) in HUDOC, the Court's official database: judgments of the Grand Chamber, Chambers and Committees, admissibility decisions, legal summaries (Case-Law Information Note), communicated cases, advisory opinions, Committee of Ministers resolutions and Commission reports. Full-text search with AND/OR/NOT (also Y/O/NO and ET/OU/SAUF), exact phrases, -word exclusion, \* wildcard and parentheses; direct lookup by application number, ECLI or HUDOC item id; filters by respondent state, Convention articles invoked, articles violated, importance level (key cases, levels 1-3), court formation, language (English, French and official translations into Spanish, Italian, German, Turkish…) and dates. Returns the case title, application numbers, ECLI, respondent states, date, formation, importance, articles, violations and non-violations, the Court's conclusion, domestic law at issue, case law cited and, by reading each document, the official headnote, the operative part (FOR THESE REASONS…), relevant passages and optional full text.

### Use cases

- Find the leading ECHR case law on an issue (e.g. Roma evictions, data retention, prison conditions) filtered to key cases.
- List every judgment against a state that found a violation of a given article (e.g. Spain, Article 8).
- Retrieve a judgment by its application number or ECLI and get its operative part.
- Get the official Spanish (or other) translation of a judgment.
- Build datasets of violations by state, article and year.

### How to use (guide for AI agents)

- `searchTerms` search the full text. The Court publishes in English and French, so write terms in English (or French with `language: "FRE"`). Use quotes for phrases: `"forced eviction"`; unquoted words are combined with AND.
- `articles` and `violatedArticles` use HUDOC notation: `"8"`, `"6-1"` (Article 6 § 1), `"14+8"` (Article 14 taken with Article 8), `"P1-1"` (Article 1 of Protocol No. 1). `"Art. 8"`, `"6.1"` and `"6 § 1"` are converted. Matching is exact: `"8"` never returns Article 18, and `"3"` never returns 5-3 or 13.
- `importance`: `"1"` = key cases (published in the Reports), `"2"` = level 1 (high), `"3"` = level 2, `"4"` = level 3 (mostly Committee judgments applying settled case law). Use `["1", "2"]` for the leading case law.
- `respondentStates`: ISO codes (ESP, FRA, ITA, TUR…) — pick by title.
- `caseIds`: `"36760/06"`, `"ECLI:CE:ECHR:2012:0117JUD003676006"` or `"001-117763"`. An application number returns the documents of the case in the selected language and types; an ECLI returns that document in the selected language (all available languages if that one does not exist); an item id returns that exact document.
- `language: "SPA"` returns official Spanish translations (about 1,300, mostly cases against Spain); `"ANY"` searches all languages.
- Relevance order uses the HUDOC ranking. Without search terms, results are sorted newest first.
- Every result includes `searchTerm` and `rank`; `passages` holds the paragraphs where the search terms appear, ready for LLM analysis. `headnote` is the Registry's keyword summary (judgments since about 2021); `operativePart` is the ruling.
- `formations` covers judgments and decisions alike (`CHAMBER` does not include the Grand Chamber).
- Many judgments exist in only one official language: the English entry of a French-only judgment has no document. The actor then reads the original and adds `textItemId`, `textLanguage` and `textUrl`; `headnote`, `operativePart` and `text` are in that language. `textAvailable: false` means no text could be read.
- `includeText: false` returns metadata only (much faster for statistics).

### Input example

```json
{
    "searchTerms": ["(eviction OR demolition) AND Roma"],
    "respondentStates": ["ESP", "FRA", "ITA", "BGR"],
    "violatedArticles": ["8"],
    "importance": ["1", "2", "3"],
    "dateFrom": "2010-01-01",
    "maxResults": 20
}
```

### Output example (abridged)

```json
{
    "searchTerm": null,
    "caseIdQuery": "8122/24",
    "rank": 1,
    "itemId": "001-253230",
    "title": "CASE OF F.W. v. SPAIN",
    "applicationNumbers": ["8122/24"],
    "ecli": "ECLI:CE:ECHR:2026:1105JUD000812224",
    "respondentStates": ["Spain"],
    "decisionDate": "2026-11-05",
    "documentType": "Judgments",
    "formation": "Chamber",
    "importance": "Level 2 (medium)",
    "language": "ENG",
    "articles": ["8", "8-1", "8-2", "14", "14+8"],
    "violations": [],
    "nonViolations": ["8", "8-1", "14", "14+8"],
    "conclusion": "No violation of Article 8 - Right to respect for private and family life...",
    "separateOpinions": false,
    "citedCases": ["Strand Lobben and Others v. Norway [GC], no. 37283/13, 10 September 2019", "..."],
    "headnote": ["Art 8 • Family life • Declaration of the applicant's children as being in a situation of neglect and their subsequent placement in care • ...", "Art 14 (+ Art 8) • Discrimination • ..."],
    "operativePart": "FOR THESE REASONS, THE COURT, UNANIMOUSLY,\n1. Declares the application admissible;\n2. Holds that there has been no violation of Article 8 of the Convention;\n3. Holds that there has been no violation of Article 14 taken in conjunction with Article 8 of the Convention.",
    "textAvailable": true,
    "url": "https://hudoc.echr.coe.int/eng?i=001-253230",
    "pdfUrl": "https://hudoc.echr.coe.int/app/conversion/pdf/?library=ECHR&id=001-253230&filename=CASE_OF_F.W._v._SPAIN.pdf"
}
```

### Notes and limits

- The Court's official languages are English and French; translations exist only for a selection of cases. Search terms in Spanish only find the Spanish translations (`language: "SPA"` or `"ANY"`).
- The headnote only exists in judgments published since about 2021; older documents return an empty `headnote`.
- Translations are published as PDF; their text is extracted from the PDF. `operativePart` is detected in English, French, Spanish, Italian, Turkish, Ukrainian, Polish and Russian; translations that are only summaries (most German and Portuguese ones) have none.
- `passages` need the search terms to be in the language of the text: none are returned when an English search lands on a French-only judgment.
- If one search fails (source unavailable), the others still run; the run fails only when every search failed.
- The actor reads documents at a moderate pace (two at a time) to respect the source.

### Source

Only official sources are used (courts, ministries or the open data published by the courts themselves). Data come from HUDOC (hudoc.echr.coe.int), the official database of the European Court of Human Rights. Results are returned as published by the source.

### Proxy

No proxy is needed: the source is an official open service. If it starts blocking, enable `proxyConfiguration` (Apify RESIDENTIAL (FR) recommended, or your own `proxyUrls`). Requests then go through a sticky session (same IP, own cookies) with a Chrome TLS fingerprint (impit), and the IP is rotated on 403/429 or network errors.

# Actor input Schema

## `searchTerms` (type: `array`):

One search per item, full text of the documents (English or French; translations in other languages are searched in their language). Syntax: words (implicit AND), "exact phrase", AND / OR / NOT (also Y / O / NO and ET / OU / SAUF), -word, \* wildcard and parentheses. Example: (eviction OR demolition) AND Roma.

## `caseIds` (type: `array`):

Direct lookup: application number (36760/06), ECLI (ECLI:CE:ECHR:2012:0117JUD003676006) or HUDOC item id (001-117763). An application number uses the document type and language filters; an ECLI returns that document in the selected language (every available language if there is none); an item id returns that exact document.

## `documentTypes` (type: `array`):

Collections of HUDOC to search. Default: judgments.

## `formations` (type: `array`):

Applies to judgments and to decisions. Empty = all.

## `respondentStates` (type: `array`):

Empty = all states.

## `articles` (type: `array`):

Articles examined in the case, in HUDOC notation: "8", "6-1" (Article 6 § 1), "14+8" (Article 14 taken with 8), "P1-1" (Protocol 1, Article 1). "Art. 8", "6.1" or "6 § 1" are also accepted. Exact match: "8" does not return Article 18. Several = any of them.

## `violatedArticles` (type: `array`):

Only cases where the Court found a violation of these articles (same format: "8", "6-1", "P1-1"). Exact match: "6" finds violations recorded under Article 6 as a whole, "6-1" under Article 6 § 1.

## `importance` (type: `array`):

HUDOC importance levels. Key cases and level 1 are the ones that develop the case law. Empty = all.

## `language` (type: `string`):

Language of the documents. The Court publishes in English and French; other languages are official translations, available for a selection of cases.

## `dateFrom` (type: `string`):

Earliest decision date (YYYY-MM-DD).

## `dateTo` (type: `string`):

Latest decision date (YYYY-MM-DD).

## `sortOrder` (type: `string`):

Relevance uses the HUDOC ranking. Without search terms, newest first.

## `maxResults` (type: `integer`):

Maximum documents per search term (and per case identifier, up to 50).

## `includeText` (type: `boolean`):

Opens each document to extract the official headnote (Art 8 • Family life • …), the operative part (FOR THESE REASONS…) and relevant passages. When a judgment exists only in the other official language (about a third of the English entries are French-only), the text is read from that original and textLanguage says so. Disable for metadata only (much faster).

## `passages` (type: `integer`):

Paragraphs where the search terms appear. 0 = none.

## `includeFullText` (type: `boolean`):

Adds the full text of each document (large output).

## `proxyConfiguration` (type: `object`):

Optional. The source usually works without a proxy. If it blocks, use Apify RESIDENTIAL (FR) or your own proxyUrls; requests then use sticky sessions, IP rotation and a Chrome TLS fingerprint.

## Actor input object example

```json
{
  "searchTerms": [
    "(eviction OR demolition) AND Roma"
  ],
  "documentTypes": [
    "JUDGMENTS"
  ],
  "language": "ENG",
  "sortOrder": "relevance",
  "maxResults": 20,
  "includeText": true,
  "passages": 3,
  "includeFullText": false,
  "proxyConfiguration": {
    "useApifyProxy": false
  }
}
```

# Actor output Schema

## `results` (type: `string`):

Dataset of HUDOC documents returned by the search, one item per result. Main fields: searchTerm, title, applicationNumbers, ecli, respondentStates, decisionDate, formation, importance, violations, nonViolations, conclusion, headnote, operativePart, passages, url. See the dataset schema for the full list of fields.

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "searchTerms": [
        "(eviction OR demolition) AND Roma"
    ],
    "proxyConfiguration": {
        "useApifyProxy": false
    }
};

// Run the Actor and wait for it to finish
const run = await client.actor("legaltech/tedh").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "searchTerms": ["(eviction OR demolition) AND Roma"],
    "proxyConfiguration": { "useApifyProxy": False },
}

# Run the Actor and wait for it to finish
run = client.actor("legaltech/tedh").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "searchTerms": [
    "(eviction OR demolition) AND Roma"
  ],
  "proxyConfiguration": {
    "useApifyProxy": false
  }
}' |
apify call legaltech/tedh --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,legaltech/tedh"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/gCIsTNaEMPF0vAeMN/builds/yvckcQW0gZE15NRRg/openapi.json
