Citations API

POST/api/echr

Query HUDOC (European Court of Human Rights) cases from PostgreSQL. Supports keyword search, article filters, respondent state, and citation network expansion. Requires at least one search criterion (keyword, ECLI, application number, or article).

Request parameters (inside `arguments`)

Field	Type	Notes
`degreesSource`	int	Required. 0 to 5.
`degreesTarget`	int	Required. 0 to 5.
`keywords`	string[]	Searches issue, docname/headnote, and full text.
`ecli`	string[]	Exact ECLI identifiers.
`application_number`	string[]	HUDOC application numbers.
`respondent_state`	string[]	ISO-3 country codes (e.g., `"GRC"`, `"RUS"`).
`document_type`	string[]	`HEJUD`, `HEDEC`, `HECOM`, `HEINF`, `HECJUD`, `HECDEC`, `HECCOM`, `HECINF`.
`language`	string[]	ISO-3 language codes (e.g., `"ENG"`, `"FRE"`).
`importance`	int	1 to 4 (lower = more important).
`date_judgment_start`	string	`YYYY-MM-DD`. Must not be in the future.
`date_judgment_end`	string	`YYYY-MM-DD`. Must not be in the future.
`date_decision_start`	string	`YYYY-MM-DD`. Must not be in the future.
`date_decision_end`	string	`YYYY-MM-DD`. Must not be in the future.
`article_violated`	string[]	Violated ECHR article numbers.
`article_applied`	string[]	Applied ECHR article numbers.
`article_non_violated`	string[]	Non-violated article numbers.
`article_violated_mode`	string	`"AND"` or `"OR"` (default: `"OR"`). Combine violated articles.
`article_applied_mode`	string	`"AND"` or `"OR"` (default: `"OR"`).
`article_non_violated_mode`	string	`"AND"` or `"OR"` (default: `"OR"`).
`articles_mode`	string	`"AND"` or `"OR"` (default: `"OR"`). Combine across article types.
`attributesToFetch`	string	`"MINIMAL"`, `"ALL"`, `"NETWORKSTATS"`, `"QUERYHANDLER"`.
`onlyCaseIds`	boolean	Return IDs only (no case data).
`isSubgraph`	boolean	Restrict edges to result nodes.
`pageSize`	int	Optional. 1 to 1000 when cursor pagination is requested.
`cursor`	string	Cursor token from previous response.

Response node fields (`nodes[].data`)

Field	Description
`isResult`	`"True"` for search results, `"False"` for expanded nodes.
`dataset`	Always `"ECHR"`.
`ecli`	ECLI identifier.
`itemid`	HUDOC item ID.
`application_number`	Application number.
`date_judgment`	Judgment date.
`date_decision`	Decision date.
`respondent_state`	Respondent country.
`document_type`	HUDOC document type.
`language`	Primary language code.
`languages`	Map of available language versions (`{"ENG": "itemid", ...}`).
`importance`	Case importance level (1-4).
`article_violated`	Violated articles.
`article_applied`	Applied articles.
`keywords`	HUDOC keywords.
`title`	Case title.
`conclusion`	Case conclusion text.
`cites` / `cited_by`	Citation references.

Duplicate ECLIs across languages are deduplicated (English preferred). A languages map is built before dedup so all available versions are preserved.

Examples

Keywords only

{
  "arguments": {
    "keywords": ["Armenia"],
    "degreesSource": 1,
    "degreesTarget": 1,
    "attributesToFetch": "MINIMAL"
  }
}

Article filter with respondent state

{
  "arguments": {
    "article_violated": ["6", "8"],
    "article_violated_mode": "OR",
    "respondent_state": ["GRC"],
    "degreesSource": 1,
    "degreesTarget": 1,
    "pageSize": 100
  }
}

Response

{
  "nodes": [
    {
      "id": "ECLI:CE:ECHR:2019:...",
      "data": {
        "isResult": "True",
        "dataset": "ECHR",
        "ecli": "ECLI:CE:ECHR:2019:...",
        "date_judgment": "2019-03-14",
        "respondent_state": "GRC",
        "document_type": "HEJUD",
        "article_violated": "6",
        "importance": 2,
        "languages": { "ENG": "001-...", "FRE": "001-..." },
        "cites": ["ECLI:CE:ECHR:2015:..."],
        "cited_by": []
      }
    }
  ],
  "edges": [...],
  "message": "",
  "limits": {
    "queryResultLimit": 10000,
    "responseNodeLimit": 5000,
    "responseEdgeLimit": 30000,
    "pageSizeDefault": 1000,
    "pageSizeMax": 1000
  },
  "graph": {
    "paginationRequested": false,
    "graphComplete": true,
    "statisticsSafe": true,
    "partialReasons": []
  }
}

POST/api/echr/text

Fetch full-text judgments for ECHR cases by ECLI identifier. Supports single or batch retrieval. Use JSON body.

Parameters

Field	Type	Notes
`ecli`	string \| string[]	Required. String or array in JSON body.
`language`	string	Optional. ISO language code (e.g., `ENG`, `FRE`).

Response fields

Field	Description
`ecli`	The requested ECLI identifier.
`itemid`	Item identifier for the requested language.
`full_text`	Complete judgment text.
`full_text_available`	Boolean flag indicating whether full text is present.
`language`	Language code of the text (e.g., `"ENG"`).

Single ECLI returns one object. Multiple ECLIs return an array of objects.
If full text is missing, full_text is null and a message is included.
If language is omitted, the endpoint prefers ENG, then FRE, then any other language.
If language is omitted, the response includes a languages map keyed by ISO code.

Examples

POST (batch)

{
  "ecli": [
    "ECLI:CE:ECHR:2000:1026JUD003098596",
    "ECLI:CE:ECHR:2005:0315JUD007009801"
  ],
  "language": "ENG"
}

Response (single)

{
  "ecli": "ECLI:CE:ECHR:2000:1026JUD003098596",
  "itemid": "001-0001",
  "full_text": "THIRD SECTION CASE OF...",
  "full_text_available": true,
  "language": "ENG"
}

Response (all languages)

{
  "ecli": "ECLI:CE:ECHR:2000:1026JUD003098596",
  "default_language": "ENG",
  "languages": {
    "ENG": { "itemid": "001-0001", "full_text": "...", "full_text_available": true },
    "FRE": { "itemid": "001-0002", "full_text": null, "full_text_available": false, "message": "Full text not available for this ECLI." }
  }
}

Request parameters (inside arguments)

Response node fields (nodes[].data)

Examples

Parameters

Response fields

Examples

Request parameters (inside `arguments`)

Response node fields (`nodes[].data`)