CiteURL
Description: None

# 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, 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`.

### 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 to `True`.
- `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 like `Id. at 305`. Defaults to `True`.
- `link_plain_ids`: Whether to insert links for citations like `Id.`. Defaults to `False`.

### 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.