Getting Started
CiteURL is an extensible tool to process legal citations in text and generate links to sites where you can view the cited language online. By default, it supports Bluebook-style citations to the following bodies of law, among others:
- most state and federal court cases
- the U.S. Code and Code of Federal Regulations
- the U.S. Constitution and all state constitutions
- codified laws for every state and territory except Arkansas, Georgia, Guam, and Puerto Rico
The full list is available here. You can also customize CiteURL to support more bodies of law by writing your own citation schemas in YAML format.
Installation
CiteURL has been tested with Python version 3.9, but earlier versions probably work. Install Python if you don't have it, then run this command:
python -m pip install citeurl
Frontends
Most of the documentation on this site concerns CiteURL as a Python library you can use in your own projects. But there are a few built-in ways to use it as well. These interfaces are simpler, so their documentation is contained below:
LawSearch
If you want to try out the citation lookup features without installing anything, you can use LawSearch, which is a JavaScript implementation of CiteURL that I maintain on my website.
LawSearch is mainly meant for end users who just want to look up laws, but it's also helpful as a developer tool to understand the basic process CiteURL uses to generate URLs from citations. Whenever LawSearch is run, it describes the process step-by-step in the developer console.
Command-Line Interface
Besides LawSearch, the next-simplest way to use CiteURL is via the citeurl
command.
To create a hyperlink for each citation in input.html
and save the result as output.html
, use a command like this:
citeurl -i input.html -o output.html
You can also pipe the output of a command into CiteURL, and read the output in a web browser:
curl https://www.courtlistener.com/opinion/109815/carey-v-piphus/ | citeurl -b
If you want to look up a single citation instead of processing a block of text, use the -l
option, like so:
citeurl -l "42 USC 1983"
If you want to return the top 10 authorities cited in a text, you can use this:
citeurl -i input.html -a 10
And if you want to use a your own set of citation schemas, you can use the -s
option, followed by the path to a YAML file. If you want to prevent loading CiteURL's default set of schemas, use -n
.
JavaScript Generator
Although CiteURL is primarily a Python program, its ability to look up the URL for a single citation has also been ported to JavaScript for use as a search engine. With the citeurl-makejs
command, you can export a script that supports any given set of citation schemas, for embedding in a website. Run citeurl-makejs -h
for more info.
Markdown Extension
CiteURL can also be used as an extension to Python-Markdown. You can load the extension as citeurl
, and it supports the following options:
custom_schemas
: A list of paths to YAML files containing custom citation schemas. Defaults to none.use_defaults
: Whether CiteURL should load the default citation schemas. Defaults toTrue
.attributes
: A dictionary of HTML attributes to give each hyperlink that CiteURL inserts into the text. Defaults to{'class': 'citation'}
.link_detailed_ids
: Whether to insert links for citations likeId. at 305
. Defaults toTrue
.link_plain_ids
: Whether to insert links for citations likeId.
. Defaults toFalse
.break_id_on_regex
: Anywhere this string (parsed as regex) appears in the text, chains of citations likeid.
will be interrupted. Note that this is based on the output HTML, not the original Markdown text. Defaults toL\. ?Rev\.|J\. ?Law|\. ?([Cc]ode|[Cc]onst)
GNOME Shell Search Provider
If you use the GNOME desktop environment, you can install my other project to look up citations right from your desktop!
Python Library
To use CiteURL as a Python library, you'll need to import the Citator class, which contains most of the important features. Then, instantiate a citator to recognize citations:
from citeurl import Citator
citator = Citator()
After that, you can feed text to the citator to return Citation objects:
text = """
Federal law provides that courts should award prevailing civil
rights plaintiffs reasonable attorneys fees, see 42 USC § 1988(b),
and, by discretion, expert fees, see id. at (c). This is because
the importance of civil rights litigation cannot be measured by a
damages judgment. See Riverside v. Rivera, 477 U.S. 561 (1986).
But Evans v. Jeff D. upheld a settlement where the plaintiffs got
everything they wanted, on the condition that they waive attorneys
fees. 475 U.S. 717 (1986). This ruling lets savvy defendants
create a wedge between plaintiffs and their attorneys, discouraging
civil rights suits and undermining the court's logic in Riverside,
477 U.S. at 574-78.
"""
citations = citator.list_citations(text)
Once you have a list of citations, you can get information about them:
for citation in citations:
print(citation.text + ' --- ' + str(citation.schema) + ' --- ' + citation.URL
# 42 USC § 1988(b) --- United States Code --- https://www.law.cornell.edu/uscode/text/42/1988#b
# id. at (c) --- United States Code --- https://www.law.cornell.edu/uscode/text/42/1988#c
# 477 U.S. 561 --- Caselaw Access Project --- https://cite.case.law/us/477/561
# 475 U.S. 717 --- Caselaw Access Project --- https://cite.case.law/us/475/717
# 477 U.S. at 574-78 --- Caselaw Access Project --- https://cite.case.law/us/477/561#p574
You can also use insert_links() to insert the citations back into the source text as hyperlinks:
from citeurl import insert_links
output = insert_links(citations, text)
print(output)
# Federal law provides that courts should award prevailing civil
# rights plaintiffs reasonable attorneys fees, see <a class="citation"
# href="https://www.law.cornell.edu/uscode/text/42/1988#b">42 USC § 1988(b)</a>,
# and, by discretion, expert fees, see <a class="citation"
# href="https://www.law.cornell.edu/uscode/text/42/1988#c">id. at (c)</a>.
# This is because the importance of civil rights litigation cannot be
# measured by a damages judgment. See Riverside v. Rivera, <a class="citation"
# href="https://cite.case.law/us/477/561">477 U.S. 561</a> (1986).
# But Evans v. Jeff D. upheld a settlement where the plaintiffs got
# everything they wanted, on the condition that they waive attorneys
# fees. <a class="citation" href="https://cite.case.law/us/475/717">475 U.S.
# 717</a> (1986). This ruling lets savvy defendants create a wedge between
# plaintiffs and their attorneys, discouraging civil rights suits and
# undermining the court's logic in Riverside, <a class="citation"
# href="https://cite.case.law/us/477/561#p574">477 U.S. at 574-78</a>.
Or, you can use list_authorities to combine the citations into a list of authorities cited in the text, and see how often each one is cited:
from citeurl import list_authorities
authorities = list_authorities(citations)
for authority in authorities:
print(authority)
print(len(authority.citations))
# 42 USC § 1988
# 2
# 477 U.S. 561
# 2
# 475 U.S. 717
# 1
If you want to use CiteURL to recognize citations that aren't supported by its default library, you can create custom citation schemas in YAML files.
For more information, see the documentation on the CiteURL module's classes and module-level functions.