Legal citation extractor. Standalone library, and optional HTTP API.
A fast, stand-alone legal citation extractor.
usc: US Code
law: US Slip Laws (public and private laws)
stat: US Statutes at Large
cfr: US Code of Federal Regulations
dc_code: DC Code
dc_register: DC Register
dc_law: DC Slip Law
With limited, opt-in support for:
As you can see, Citation is currently US-only, but we'd love for that to change. There are lots more citation types out there, and it's easy to contribute, so please help us grow!
Compatible in-browser with modern browsers, including IE 9+.
Citation can be used:
But one way or another, you pass in text:
And you get back data about matched citations:
"match": "5 U.S.C. 552(a)(1)(E)""type": "usc""index": "0""usc":"title": "5""section": "552""subsections": "a" "1" "E""id": "usc/5/552/a/1/E""section_id": "usc/5/552"
Check out /browser for browser-ready compressed and uncompressed versions of the library.
Loading any of them with a
<script> tag will result in a global
Citation object being available for immediate use.
Install Node.js and NPM, then install Citation globally (may require
npm install -g citation
Or install it locally to a
node_modules directory with
npm install citation.
Check a block of
text for citations of a given type, returning an array of
matches with citations broken out into fields.
options can include:
types: (string | string array) Limit citation types to those given. e.g.
excerpt: (integer) Return an
excerptof the surrounding text for each detected cite, with the given number of characters on either side.
parents: (boolean) For any cite, return any "parent" cites alongside it. For example, matching "5 USC 552(b)(3)" would return 3 results - one for the parent section, one for
(b), and one for
filter: (string) Enable Filtering.
replace: (function | object) Enable Replacement.
Citation;// Yields:"match": "5 U.S.C. 552(a)(1)(E)""type": "usc""index": "0""usc":"title": "5""section": "552""subsections": "a" "1" "E""id": "usc/5/552/a/1/E""section_id": "usc/5/552"Citation// Yields:"match": "section 5362(5) of title 31""excerpt": "t term in section 5362(5) of title 31, United S"// ... more details ...
Start the API on a given port (defaults to 3000):
GET or POST to
/citation/find with a
curlcurl -XPOST "" -d "text=5 U.S.C. 552(a)(1)(E)"
Will return the results of running Citation.find() on the block of text, under a
Some HTTP-specific parameters:
callback: a function name to use as a JSONP callback.
pretty: prettify (indent) output.
text: required, text to extract citations from.
options[excerpt]: include excerpts with up to this many characters around it.
options[types]: limit citation types to a comma-separated list (e.g. "usc,law")
See etc/ for an example upstart script to keep
cite-server running in production.
The shell command can accept a string to parse as an argument or through STDIN, and outputs results to STDOUT as indented JSON.
cite "section 5362(5) of title 31"echo "section 5362(5) of title 31" | citecite "pursuant to 5 U.S.C. 552(a)(1)(E) and > results.json"
Pass any options the library takes, using dot operators to pass nested options.
For example, searching among types:
cite --types=usc,law "section 5362(5) of title 31"
Passing nested options:
cite --dc_code.source=dc_code "and then § 3-101.01 happened"
Opt-in to using
walverine to search judicial cites with
cite --judicial "Smith v. Hardibble, 111 Cal.2d 222, 555, 558, 333 Cal.3d 444 (1988)"
You can perform a "find-and-replace" with detected citations, by providing a
replace callback to be executed on each citation, that returns the string to replace that citation.
By passing a
replace callback, a
text field will be included at the top of the returned object, with the processed text.
The response will have a
text field containing:
click on <a href="">5 USC 552</a> to read more
You can pass arbitrary options to individual citators, if that citator supports them.
By using a key is the key of a citator, e.g.
dc_code, that citator's processors will get the value of that key passed in as an argument.
For example, the
dc_code citator accepts a
source option, to indicate
what the text source is. If the value of
source is itself "dc_code",
then the citator will apply a looser pattern to detect internal cites.
That looks like this:
That will match
§ 3-101.01(13)(e), because the
dc_code citator assumes it's processing the text of the DC Code itself, and internal references are unambiguous.
Citation can integrate with walverine to detect and return results for US court opinions.
To use walverine, you may need to "opt-in" to including
Citationtypesjudicial = ;
cite --judicial "Text to scan"
The HTTP server,
cite-server actually loads
judicial cites by default, since the performance penalty is absorbed on start-up.
walverine's support for extra features is limited. When detecting
judicial-type cites, there is no support for:
This project is tested with nodeunit.
To run tests, you'll need to install this project from source and install its node dependencies:
git clone email@example.com:unitedstates/citation.gitcd citationnpm installnpm test
Test cases are stored in the
test directory. Each test case covers a subsection
of the code and ensures that citations are correctly detected: for instance, see
To run all tests:
To run a specific test:
The project is in the public domain within the United States, and copyright and related rights in the work worldwide are waived through the CC0 1.0 Universal public domain dedication.
All contributions to this project will be released under the CC0 dedication. By submitting a pull request, you are agreeing to comply with this waiver of copyright interest.