Skip to main content
  • Caselaw
    Tools overview Search Trends API Timeline Cases by Jurisdiction Bulk Data Fetch PDFs From Text
  • Support/docs
    Docs Overview API Bulk Data Search
  • Gallery
    Gallery home CAP Labs Research Results Coursework Fun Stuff Applications Applications Third Party Tutorials
  • About
    About CAP Contact
  • Log in
Documentation / Site Features / API
    • For Researchers
        • How do you want to access caselaw data?
          • Bulk Downloads
          • API
        • What level of access do you need?
        • How do I register?
        • How do I apply for researcher access?
          • Important Caveats
          • Eligibility
          • Where do I apply?
    • For Courts
        • Digital-First Guidelines
            • Introduction
            • Digital-first publishing guidelines
              • Essential characteristics
                • Online
                • Free & Open
                • Comprehensive
                • Official
                • Citable
                • Machine Readable
              • Desirable characteristics
                • Digitally Signed
                • Versioning
                • Structured Data
                • Medium-Neutral
                • Archives
                • Search
                • Bulk
                • API
        • Case Studies
            • Case study: Arkansas
            • Case study: Canada
            • Case study: New Mexico
    • For Libraries
    • Registration
    • Search
        • Overview
        • What's included?
        • Searching in CAP is simple
          • First: Choose What To Search
          • Second: Select Your Search Criteria
          • Third: Execute the Search
        • Full-Text Case Search
          • Phrase Search
          • Exclusion
        • Tips
        • Getting Legal Help
    • API
        • API Learning Track
        • Authentication
          • Get an API Key
          • Modify The Request Headers
          • Example
          • Failure: error_auth_required
          • Browsable API
          • Sitewide Token Authentication
        • Case Text Formats
        • Pagination and Counts
          • Example
        • Endpoints
          • API Base
          • Cases Endpoint
            • Endpoint Parameters
            • Single Case Endpoint
            • Search Syntax
            • Examples
          • Reporters Endpoint
            • Endpoint Parameters
            • Examples
          • Jurisdictions Endpoint
            • Endpoint Parameters
          • Courts
            • Endpoint Parameters
          • Volumes
            • Endpoint Parameters
          • Ngrams
            • Endpoint Parameters
            • Examples
    • Bulk Data
        • Access Limits
        • Downloading
        • API Equivalence
        • Data Format
        • Using Bulk Data
        • Other repositories
    • Historical Trends
        • Start Here
        • Reading Results
          • Key
          • Horizontal axis
          • Vertical axis
        • Customize
          • Percentage Count/Instance Count/Scaling
          • Smoothing
        • Table view
        • Keyboard navigation
        • Download
        • Wildcard search
        • Citation search
        • Jurisdiction search
        • Jurisdiction codes
        • Filter fields
        • Citation feature
    • API Learning Track
        • Intro to APIs
        • CAP API Tutorial
            • Intro: Browsable API
            • Intro to JSON
            • curl
            • Overview of the endpoints
            • Dig-in With Real Queries
            • Next Steps
            • Wrap-up
        • CAP API In Depth
            • Getting Started
              • Making Basic Queries
              • Filtering
              • Search
                • Full-text Search
                • Filtering by Groups or Ranges
              • Sorting
                • Random sorting
              • Types of Data You Can Query
            • Getting Full Case Text
            • Authentication
              • Find your API Key
              • Modify Your Headers
                • curl
                • python requests library
                • Other Environments
              • Doesn't work?
                • error_auth_required
                • error_limit_exceeded
            • Data Formats
              • Structured Casebody Text
            • Other Endpoints
    • Access Limits
        • Exceptions
        • Open Jurisditions
        • Research Access
        • Commercial Licensing
        • User Types and Permissions
          • Unregistered Users
          • Registered Users
          • Researchers
          • Commercial Users
    • Stability and Changes
    • Reporting Problems
        • Misspelled Words
        • Website Errors
        • Metadata Errors
    • Documentation Glossary
        • API
        • Character
        • Special Character
        • Command Line
        • curl
        • Endpoint
        • Jurisdiction
        • OCR
        • RESTful
        • Reporter
        • Server
        • Slug
        • String
        • Top-Level Domain
        • URL
        • URL Parameter
        • URL Path
        • Open Jurisdiction
        • Restricted Jurisdiction
        • Cursor
    • Data Specifications
        • Bulk
          • Structure
          • Data Format
        • API
          • Individual Records
          • Query Results
        • Individual Objects
          • Case
            • Casebody
            • Analysis Fields
          • Jurisdiction
          • Court
          • Volume
          • Reporter
          • Citation
          • Ngrams
    • Changelog
        • August 28 2020
        • August 2020
        • June 2020
        • April 2020
        • March 2020
        • February 2020
        • January 24, 2020
        • January 19, 2020
        • January 16, 2020
        • January 9, 2020
        • December 6, 2019
        • October 1, 2019
        • July 31, 2019
        • June 19, 2019

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

https://api.case.law/

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 or 12345.
  • cites_to.reporter
    • data type: string
    • description: find cases that cite to the given reporter, e.g. Ill. 2d or Harv. L. Rev.
  • cites_to.category
    • data type: string
    • description: find cases that cite to the given citation category, e.g. reporter:state or reporters:federal. Category values can be found in results for the cases endpoint under extracted_citations[].category.
  • author__cites_to
    • data type: string or integer
    • description: only active when the author or author_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 or author_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 or author_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 or 12345
  • court
    • data type: slug
    • description: court slug
  • 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
  • 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 setting body_format.
  • id
    • data type: integer
  • jurisdiction
    • data type: slug
    • description: jurisdiction slug
  • last_updated
    • data type: YYYY-MM-DDTHH:MM:SS or a substring
  • 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 setting body_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:

https://api.case.law/v1/cases/?cite=1 Breese 34&decision_date_min=1900-12-30&decision_date_max=2000-12-30

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 or mass. 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!

API

The Caselaw Access Project API, also known as CAPAPI, serves all official US court cases published in books from 1658 to 2018. The collection includes over six million cases scanned from the Harvard Law School Library shelves. Learn more about the project.

Caselaw
  • Search
  • API
  • Trends
  • Bulk Data
  • By Jurisdiction
  • Fetch PDFs
Gallery
  • CAP Labs
  • Research
  • Coursework
  • Fun Stuff
  • Community Apps
  • Our Apps
  • Community Tutorials
Docs
  • About CAP
  • Docs Overview
  • API
  • Bulk Data
  • Search
Site text is licensed CC BY-SA 4.0. Source code is MIT licensed. Harvard asserts no copyright in caselaw retrieved from this site. ©2023 The President and Fellows of Harvard University.
terms
privacy
accessibility