History of courtlistener_citations
The changes to the source code of this entry in the repository, newest first, each with the differences it made to the entry's files. They are also listed on GitLab.
[entries] Add the date when each entry was added, and remove icon_hash beff7c9
The dates are those of the commits that first added the entries' files (2020-08-11 for the entries of the initial commit); renamed entries keep the date of their first name. Changed: none
diff --git a/entries/courtlistener_citations/__init__.py b/entries/courtlistener_citations/__init__.py
index 6170af8..bddfe80 100644
--- a/entries/courtlistener_citations/__init__.py
+++ b/entries/courtlistener_citations/__init__.py
@@ -37,7 +37,7 @@ tags = ['Informational', 'Citation', 'Legal', 'Weighted', 'Metadata']
url = ['https://www.courtlistener.com/help/api/bulk-data/',
'https://com-courtlistener-storage.s3-us-west-2.amazonaws.com/list.html?prefix=bulk-data/']
citation = [('Free Law Project, "CourtListener bulk legal data." (2026)', 'https://www.courtlistener.com/help/api/bulk-data/')]
-icon_hash = None
+date_added = '2026-10-27'
upstream_license = ('Public Domain Mark 1.0', 'https://creativecommons.org/publicdomain/mark/1.0/')
upstream_prefix = 'https://com-courtlistener-storage.s3-us-west-2.amazonaws.com/bulk-data'
# The releases of the citation map, by date (the bucket also has three empty
[entries] Prefix the properties in the descriptions with (Node), (Edge) or (Graph) bc3dbbd
The lists of properties at the end of the descriptions marked edge properties with "Edge" but left node properties unmarked, or grouped them in "Nodes: `a`, ...; `b`, ..." items, so the kind of a property was often unclear. Every item now starts with (Node), (Edge) or (Graph), followed by the property names, a colon and the explanation, one item per property or group of properties; qualifications (kinds of nodes, networks) follow the names in parentheses. Properties that were only named got a short explanation, and a few items that named the wrong kind of property were corrected.
diff --git a/entries/courtlistener_citations/__init__.py b/entries/courtlistener_citations/__init__.py
index c7e0486..6170af8 100644
--- a/entries/courtlistener_citations/__init__.py
+++ b/entries/courtlistener_citations/__init__.py
@@ -31,8 +31,8 @@ Only the opinions that cite or are cited by another one are included. The data i
The networks have the following properties:
-- `opinion_id`: the CourtListener identifier of the opinion.
-- Edge `depth`: the number of times the citing opinion cites the cited one."""
+- (Node) `opinion_id`: the CourtListener identifier of the opinion.
+- (Edge) `depth`: the number of times the citing opinion cites the cited one."""
tags = ['Informational', 'Citation', 'Legal', 'Weighted', 'Metadata']
url = ['https://www.courtlistener.com/help/api/bulk-data/',
'https://com-courtlistener-storage.s3-us-west-2.amazonaws.com/list.html?prefix=bulk-data/']
[entries] Remove unneeded code from the entries 2c69f19
Unneeded "global files" statements, unused imports and variables, f-strings without placeholders, duplicate keys in foodweb_little_rock (keeping the order and the values used), and the second definition of get_lines() in twitter_higgs. Nothing changes in the networks or descriptions. Changed: none
diff --git a/entries/courtlistener_citations/__init__.py b/entries/courtlistener_citations/__init__.py
index dfd1778..c7e0486 100644
--- a/entries/courtlistener_citations/__init__.py
+++ b/entries/courtlistener_citations/__init__.py
@@ -71,7 +71,6 @@ def header_and_quote(name, fname):
@coerce_props()
@annotate()
def parse(alts=None):
- global files
name = __name__.split(".")[-1]
for fname, alt, fmt in files:
if alts is not None and alt not in alts:
[entries] New entry: courtlistener_citations d4ccc75
diff --git a/entries/courtlistener_citations/__init__.py b/entries/courtlistener_citations/__init__.py
new file mode 100644
index 0000000..dfd1778
--- /dev/null
+++ b/entries/courtlistener_citations/__init__.py
@@ -0,0 +1,112 @@
+#! /usr/bin/env python
+# -*- coding: utf-8 -*-
+#
+# Copyright (C) 2026 Tiago de Paula Peixoto <tiago@skewed.de>
+#
+# This program is free software: you can redistribute it and/or modify it under
+# the terms of the GNU Affero General Public License as published by the Free
+# Software Foundation, either version 3 of the License, or (at your option) any
+# later version.
+#
+# This program is distributed in the hope that it will be useful, but WITHOUT
+# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
+# FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License for more
+# details.
+#
+# You should have received a copy of the GNU Affero General Public License along
+# with this program. If not, see <http://www.gnu.org/licenses/>.
+
+
+
+import bz2
+import pandas
+
+from .. import *
+
+
+title = "US court opinion citations (CourtListener, 2022-2026)"
+description = """A directed network of citations between the opinions of US federal and state courts, from the "citation map" of the bulk data of CourtListener, the legal research platform of the Free Law Project, in all its releases available, from 30 September 2022 to 30 September 2026. CourtListener extracts the citations from the texts of the opinions, and resolves them to the opinions they refer to. Each node is an opinion (a majority opinion, a concurrence, a dissent, etc.; the opinions of a case are grouped in "clusters" by CourtListener), and a directed edge from opinion A to opinion B means that A cites B.
+
+Only the opinions that cite or are cited by another one are included. The data identify the opinions only by their CourtListener identifiers (the opinion with identifier `<id>` can be looked up with the CourtListener API, at `https://www.courtlistener.com/api/rest/v4/opinions/<id>/`); the metadata of the opinions (their cases, courts and dates) are left out, since mapping the opinions to their cases requires the bulk file of the opinions, which also contains their full texts (55 GB, compressed). The bulk data are released at irregular intervals (monthly in some periods, quarterly in others), each release containing all the citations known at the time, so that each release is a snapshot of the whole citation network. There is one network per release, named by its date (from `2022-09-30` to `2026-09-30`, 34 networks; the dates are those of the files, which are not always regular): the network of each release contains only its own opinions and citations, and the opinions are identified by the same CourtListener identifiers in all releases. The storage of the bulk data also has three empty files of earlier dates (2022-08-03, 2022-08-31 and 2024-03-01), which are left out. The number of citations grows from 28.9 million (3.5 million opinions) in `2022-09-30` to 78.4 million (8.1 million opinions) in `2026-09-30`; most of the growth happened between the releases `2025-04-30` (37.1 million) and `2025-07-02` (70.1 million). (The number does not always grow: e.g. `2025-10-09` has fewer citations than `2025-09-04`.)
+
+The networks have the following properties:
+
+- `opinion_id`: the CourtListener identifier of the opinion.
+- Edge `depth`: the number of times the citing opinion cites the cited one."""
+tags = ['Informational', 'Citation', 'Legal', 'Weighted', 'Metadata']
+url = ['https://www.courtlistener.com/help/api/bulk-data/',
+ 'https://com-courtlistener-storage.s3-us-west-2.amazonaws.com/list.html?prefix=bulk-data/']
+citation = [('Free Law Project, "CourtListener bulk legal data." (2026)', 'https://www.courtlistener.com/help/api/bulk-data/')]
+icon_hash = None
+upstream_license = ('Public Domain Mark 1.0', 'https://creativecommons.org/publicdomain/mark/1.0/')
+upstream_prefix = 'https://com-courtlistener-storage.s3-us-west-2.amazonaws.com/bulk-data'
+# The releases of the citation map, by date (the bucket also has three empty
+# placeholder files, of 2022-08-03, 2022-08-31 and 2024-03-01, left out)
+releases = ['2022-09-30', '2022-10-31', '2022-11-30', '2022-12-31', '2023-01-31',
+ '2023-02-28', '2023-03-31', '2023-04-30', '2023-05-31', '2023-07-31',
+ '2023-08-31', '2023-12-04', '2024-03-11', '2024-05-06', '2024-08-13',
+ '2024-08-15', '2024-08-31', '2024-09-30', '2024-10-31', '2024-11-30',
+ '2024-12-31', '2025-01-31', '2025-02-28', '2025-03-31', '2025-04-30',
+ '2025-07-02', '2025-09-04', '2025-10-09', '2025-10-31', '2025-12-02',
+ '2025-12-31', '2026-03-31', '2026-06-30', '2026-09-30']
+files = [(f'citation-map-{d}.csv.bz2', d, None) for d in releases]
+
+def fetch_upstream(force=False):
+ return fetch_upstream_files(__name__.split(".")[-1], upstream_prefix, files,
+ force)
+
+def header_and_quote(name, fname):
+ """The number of lines before the header of the bzip2-compressed CSV file
+ `fname`, and the quote character of its values."""
+ with open_upstream_file(name, fname, "rb") as f, bz2.open(f) as bf:
+ for skip in range(10):
+ if bf.readline().startswith(b"id,depth,"):
+ break
+ else:
+ raise ValueError(f"no header in {fname}")
+ first = bf.readline()
+ return skip, ("`" if first.startswith(b"`") else '"')
+
+@cache_network()
+@coerce_props()
+@annotate()
+def parse(alts=None):
+ global files
+ name = __name__.split(".")[-1]
+ for fname, alt, fmt in files:
+ if alts is not None and alt not in alts:
+ continue
+ # "id,depth,cited_opinion_id,citing_opinion_id"; the values are
+ # unquoted, or quoted with " or ` depending on the release, and the
+ # header is preceded by a stray line ("SET") in one release
+ skip, quote = header_and_quote(name, fname)
+ citing, cited, depth = [], [], []
+ with open_upstream_file(name, fname, "rb") as f:
+ for chunk in pandas.read_csv(f, compression="bz2", chunksize=10**7,
+ skiprows=skip, quotechar=quote,
+ usecols=["depth", "cited_opinion_id",
+ "citing_opinion_id"],
+ dtype="int32"):
+ citing.append(chunk["citing_opinion_id"].values)
+ cited.append(chunk["cited_opinion_id"].values)
+ depth.append(chunk["depth"].values)
+ citing = numpy.concatenate(citing)
+ cited = numpy.concatenate(cited)
+ depth = numpy.concatenate(depth)
+ # the opinions that appear, numbered in the order of their ids
+ present = numpy.zeros(max(citing.max(), cited.max()) + 1, dtype="bool")
+ present[citing] = True
+ present[cited] = True
+ ids = numpy.flatnonzero(present)
+ index = numpy.cumsum(present, dtype="int32") - 1
+ del present
+ citing = index[citing]
+ cited = index[cited]
+ del index
+ g = Graph(directed=True)
+ g.add_vertex(len(ids))
+ g.vp.opinion_id = g.new_vp("int64_t", vals=ids)
+ g.add_edge_list(numpy.column_stack([citing, cited]))
+ del citing, cited
+ g.ep.depth = g.new_ep("int", vals=depth)
+ yield alt, g