API Learning Track
Want a tutorial? Our API Learning Track offers three levels of introduction to getting started with APIs and then using our API to query caselaw data.
Authentication
Note: many API queries don't require registration! Check our access limits section for more details.
Get an API Key
Before you can authenticate, you'll need an API key.
- First, register an account.
- Log in.
- Click on the "ACCOUNT" link at the top of the screen.
- The API key is listed in your profile.
Modify The Request Headers
To authenticate a request from the command line or a program, pass the Authorization
header with your request.
The format of the Authorization
header value is important: Use the string Token
followed
by a space, followed by your API key.
Example
With an API key of abcd12345
, you would pass Token abcd12345
to the Authorization
header.
A curl
command would look like this:
curl -H "Authorization: Token abcd12345" "https://api.case.law/v1/cases/435800/?full_case=true"
Using Python's requests
library, it would look something like this:
response = requests.get(
'https://api.case.law/v1/cases/435800/?full_case=true',
headers={'Authorization': 'Token abcd12345'}
)
Failure: error_auth_required
If authentication fails, you'll receive
...
"casebody": {
"data": null,
"status": "error_auth_required"
}
...
In this example the response included a case from a restricted jurisdiction, and casebody.data
for the case is
therefore blank, while casebody.status
is error_auth_required
.
Browsable API
If you are logged into this website and accessing the API through a web browser, all requests will be authenticated automatically.
Sitewide Token Authentication
In addition to using the Authorization: Token abcd12345
header on API endpoints, you can use the same header to send
authenticated requests to any other page at case.law, such as the Downloads section.
Case Text Formats
See Data Specs.
Pagination and Counts
We use cursor-based pagination, meaning we
keep track of where you are in the results set with a token, and you can access each page of results by returning the
token included in the "previous"
and "next"
keys of the response.
Queries by default return 100 results per page, but you may request a smaller or larger number (up to 10,000!) using the
page_size
parameter:
Example
curl "https://api.case.law/v1/cases/?jurisdiction=ill&page_size=1"
{
"count": 183149,
"next": "https://api.case.law/v1/cases/?cursor=cD0xODMyLTEyLTAx",
"previous": "https://api.case.law/v1/cases/?cursor=bz0xMCZyPTEmcD0xODI4LTEyLTAx"
...
}
Endpoints
API Base
This is the base endpoint. It just lists all of the available endpoints.
Cases Endpoint
https://api.case.law/v1/cases/
This is the primary endpoint; you use it to browse, search for, and retrieve cases. If you know the numeric ID of your case in our system, you can append it to the path to retrieve a single case.
Endpoint Parameters
Many parameters can be appended with __in
, __exclude
, __gt
, __gte
, __lt
, or __lte
. See Filtering.
analysis.<key>
- data type: integer or float
- description: Filter by an analysis field, e.g.
analysis.word_count__gt=1000
body_format
- data type: "text", "html", or "xml"
- default: "text"
- description: Change the case body format from JSON to html or xml. Requires
full_case=true
.
cite
- data type: string
- description: citation to case, e.g.
1 Ill. 21
cites_to
- data type: string or integer
- description: find cases that cite to the given citation or case ID, e.g.
1 Ill. 21
or12345
.
cites_to.reporter
- data type: string
- description: find cases that cite to the given reporter, e.g.
Ill. 2d
orHarv. L. Rev.
cites_to.category
- data type: string
- description: find cases that cite to the given citation category, e.g.
reporter:state
orreporters:federal
. Category values can be found in results for the cases endpoint underextracted_citations[].category
.
author__cites_to
- data type: string or integer
- description: only active when the
author
orauthor_type
parameters are also present. Find cases where the selected author's opinions cite to the given citation or case ID.
author__cites_to.reporter
- data type: string
- description: only active when the
author
orauthor_type
parameters are also present. Find cases where the selected author's opinions cite to the given reporter.
author__cites_to.category
- data type: string
- description: only active when the
author
orauthor_type
parameters are also present. Find cases where the selected author's opinions cite to the given category.
cites_to__*
- data type: integer, float, or string
- description: find cases with citations into a set of cases filtered by arbitrary parameters, e.g.
cites_to__jurisdiction=nc, cites_to__author=breyer, cites_to__analysis.word_count__gt=1000
. The target cases will be chosen randomly within the provided filters if the result exceeds 20,000 cases. For multiple filters, simply combine parameters, e.g.cites_to__jurisdiction=nc&cites_to__analysis.word_count__gt=1000
. Only fields used for filtering and searching the cases endpoint may be used.
cites_to
- data type: string or integer
- description: find cases that cite to the given citation or case ID, e.g.
1 Ill. 21
or12345
court
court_id
- data type: integer
- description: court id
cursor
- data type: string
- description: A value provided by a previous search result to go to the next page of results
decision_date
- data type:
YYYY-MM-DD
or a substring
- data type:
docket_number
- data type: string
- description: full-text search
facet
- data type: string
- description: A field name to aggregate results given a particular field. Currently, only the values "jurisdiction" and "decision_date" are supported. This endpoint supports ordered sub-aggregations; to split by jurisdiction and then decision_date per jurisdiction, set facet to "jurisdiction,decision_date".
full_case
- data type: "true" or "false"
- default: "false"
- description: When set to
true
, load the case body. Required when settingbody_format
.
id
- data type: integer
jurisdiction
- data type: slug
- description: jurisdiction slug
last_updated
- data type:
YYYY-MM-DDTHH:MM:SS
or a substring
- data type:
name_abbreviation
- data type: string
- description: e.g.
People v. Smith
ordering
- data type: string
- description: A field name to sort your results in ascending order. Prepend with a minus sign to sort in reverse order. See Sorting for more details.
reporter
- data type: integer
- description: reporter id
search
- data type: string
- description: full-text search
Single Case Endpoint
https://api.case.law/v1/cases/435800/
Use this endpoint to retrieve a single case.
Endpoint Parameters:
body_format
- data type: "text", "html", or "xml"
- default: "text"
- description: Change the case body format from JSON to html or xml. Requires
full_case=true
.
format
- data type: blank or "pdf"
- description: If "pdf", return original PDF of the case instead of JSON. Requires
full_case=true
.
full_case
- data type: "true" or "false"
- default: "false"
- description: When set to
true
, load the case body. Required when settingbody_format
.
Search Syntax
The search
field supports Elasticsearch Simple Query String Syntax.
For example, you can use "quotation marks around your search string"
to search by phrase and prefix words with a minus sign to exclude cases with matching terms.
Examples
Retrieve a list of cases by citation:
https://api.case.law/v1/cases/?cite=1 Breese 34
Add a date range filter:
Find all cases containing the word "insurance":
https://api.case.law/v1/cases/?search=insurance
Find cases that contain both "insurance" and "Peoria":
https://api.case.law/v1/cases/?search=insurance Peoria
Find cases that contain both "insurance" and "Peoria", limited to Illinois:
https://api.case.law/v1/cases/?search=insurance Peoria&jurisdiction=ill
Retrieve a single case by ID:
https://api.case.law/v1/cases/435800/
Reporters Endpoint
https://api.case.law/v1/cases/
Return a list of reporter series.
Endpoint Parameters
full_name
- data type: string
- description: the full reporter name, e.g. Illinois Appellate Court Reports
short_name
- data type: string
- description: the short reporter name, e.g. Ill. App.
start_year
- data type: integer
- description: the earliest year reported on in the series
end_year
- data type: integer
- description: the latest year reported on in the series
volume_count
- data type: integer
- description: filter on the number of volumes in a reporter series
cursor
- data type: string
- description: A value provided by a previous search result to go to the next page of results
Examples
Get all reporters in Arkansas:
https://api.case.law/v1/reporters/?jurisdictions=ark
Jurisdictions Endpoint
https://api.case.law/v1/jurisdictions/
Return a list of jurisdictions.
Endpoint Parameters
name_long
- data type: string
- description: the full jurisdiction name, e.g. Illinois
name
- data type: string
- description: the short jurisdiction name, e.g. Ill.
whitelisted
- data type: "true" or "false"
- description: filter for open jurisdictions
slug
- data type: string
- description: filter on the jurisdiction slug
cursor
- data type: string
- description: A value provided by a previous search result to go to the next page of results
Courts
https://api.case.law/v1/courts/
This will return a list of courts.
Endpoint Parameters
name_long
- data type: string
- description: the full court name, e.g. Illinois Appellate Court
name_abbreviation
- data type: string
- description: the short jurisdiction name, e.g. Ill. App. Ct.
whitelisted
- data type: "true" or "false"
- description: filter for open jurisdictions
jurisdiction
- data type: string
- description: filter on the jurisdiction slug
slug
- data type: string
- description: filter on the court slug
cursor
- data type: string
- description: A value provided by a previous search result to go to the next page of results
Volumes
https://api.case.law/v1/volumes/
Return a complete list of volumes.
Endpoint Parameters
cursor
- data type: string
- description: A value provided by a previous search result to go to the next page of results
Ngrams
https://api.case.law/v1/ngrams/
For any given term, this endpoint returns a year-by-year list of:
- the number of cases in which that term appears, and the total number of cases
- the number of times that term appears in all cases, and the total number of terms
If you set the optional jurisdiction
parameter, your results will be limited to a specific jurisdiction.
Endpoint Parameters
q
- data type: string
- description: Up to 3 space separated words. All words beyond the third are ignored.
jurisdiction
- data type: string
- description: Jurisdiction slug: e.g.
tex
ormass
. Limit your results to a specific jurisdiction.
year
- data type: YYYY
- description: Filter results by year.
Examples
querying for 'raisins' in California in 1984:
{
"count": 1,
"next": null,
"previous": null,
"results": {
"raisins": {
"cal": [
{
"year": "1984",
"count": [
40,
4589927
],
"doc_count": [
1,
1237
]
}
]
}
}
}
Under results
is an object containing the results for the query term raisins
. Each jurisdiction's slug
is a key in the raisins
object. Only cal
is listed because the jurisdiction parameter in the query is set to cal
.
Under cal
, there is an array of objects, each containing the counts for a specific year. Since this query filters for
results from 1984, that's the only year listed. Under count
, there's 40, 4589927
, meaning 4,589,927 terms were
indexed for California in 1984, and 40 of those are raisins. Under doc_count
there's 1, 1237
, meaning 1,237
cases were indexed for California in 1984, and raisins shows up in 1 of those cases.
-
Find what you were looking for?
If you have suggestions for improving this documentation, let us know!