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 / Learning Tracks / API Learning Track / CAP API In Depth
    • 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

Getting Started

If you're a RESTful API pro, you may just need our API Reference.

If you're an absolute beginner and haven't used APIs before, but want to get up to speed, check out our Beginner's Introduction to APIs.

If you need a more detailed, step-by-step walkthrough of our API, check out our CAP API Tutorial.

Making Basic Queries

This is a RESTful API, and its primary return format is in JSON. For details on the data returned by the API, head over to our API Reference.

CAPAPI includes an in-browser API viewer, but is primarily intended for software developers to access caselaw programmatically, whether to run your own analysis or build tools for other users. API results are in JSON format with case text available as structured XML, presentation HTML, or plain text. If you just want to read cases, we have a Search Tool.

To get started with the API, you can explore it in your browser, or reach it from the command line. For example, here is a curl command to request a single case from Illinois:

curl "https://api.case.law/v1/cases/?jurisdiction=ill&page_size=1"

Filtering

To filter your queries, just add more parameters. For example, if we wanted to request a single case from illinois decided before 1850:

curl "https://api.case.law/v1/cases/?jurisdiction=ill&page_size=1&decision_date__lt=1850"

Now let's search for all cases in the jurisdiction of Rhode Island that contain the word "spork":

curl "https://api.case.law/v1/cases/?search=spork&jurisdiction=ri"

Searching and Filtering Cases

Our cases endpoint is indexed by Elasticsearch, and supports a range of searching, filtering, and sorting options.

Options in this section work only with the cases endpoint.

Full-text Search

Full-text search uses the search parameter. For example, if you'd like to search for all cases that contain the word 'baronetcy', use the following query:

https://api.case.law/v1/cases/?search=baronetcy

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.

The search parameter searches the case, jurisdiction, and court names, docket number, and case text. You can also use the name, name_abbreviation, or docket_number parameters to perform full-text search just on those fields.

Filtering by Groups or Ranges

Many of the parameters on the /cases endpoint can be filtered by appending a suffix to the query parameter key.

To match to a list, append __in to the query parameter. For example, to fetch cases matching ID 12, 34, or 56:

curl "https://api.case.law/v1/cases/?id__in=12__34__56"

To filter by less than or greater than, append __gt (greater than), __gte (greater than or equal to), __lt (less than), or __lte (less than or equal to). For example, to fetch cases of 2,000 to 3,000 words:

curl "https://api.case.law/v1/cases/?analysis.word_count__gte=2000&analysis.word_count__lte=3000"

To filter by prefix, append __prefix. For example, to find cases from February of 1800:

curl "https://api.case.law/v1/cases/?decision_date__prefix=1800-02"

To filter by fields not equal to a value, append __exclude. For example, to fetch cases outside of California:

curl "https://api.case.law/v1/cases/?jurisdiction__exclude=cal"

Sorting

You can sort your search in the /cases endpoint using the ordering parameter. To sort your results in ascending order, supply the ordering parameter with the field on which you'd like to sort your results. For example, if you'd like to search for the term 'baronetcy' with the oldest cases appearing first, supply the following query:

https://api.case.law/v1/cases/?search=baronetcy&ordering=decision_date

You can also sort in descending order by adding a minus sign before the field on which you'd like to sort. To perform the same search sorted in descending order, that is, with the newest cases first, use this query:

https://api.case.law/v1/cases/?search=baronetcy&ordering=-decision_date

Random sorting

Sort order can be randomized using ordering=random. Random sorting comes with two caveats:

  • Random results cannot be paginated. Consider using page_size if you need a larger sample of random results.
  • Random results may be cached by CAP's content delivery network, meaning you may receive the same "random" results when sending precisely the same query twice in a row. To avoid caching, make some modification to the query between each request.

Types of Data You Can Query

We make data available through several API endpoints, the most popular being our /cases endpoint. It's the only endpoint through which we distribute full case text, and the only endpoint for which you may need authentication. We also serve up citations, ngrams, court metadata, reporter series metadata, volume metadata, and jurisdiction metadata. They all work about the same way, and are all based on the same data set. That means that an ID in the /reporters endpoint will correspond to a reporter object's ID listed in a case.

Check out our API Reference for a complete list of specs and arguments.

Getting Full Case Text

You can request full case text for cases anywhere in the /cases endpoint, whether you're viewing an individual case or a list of cases. to do so, you must include the full_case=true parameter in your query url, like so:

https://api.case.law/v1/cases/?jurisdiction=ill&page_size=1&full_case=true

Without that option, you'll just get the case metadata:

https://api.case.law/v1/cases/?jurisdiction=wash&page_size=1

For most cases, you'll need to authenticate using an API key to get the case text. There are several jurisdictions for which we do not require authentication, which we call open jurisdictions. To see a complete list of open jurisdictions, check out our access limits documentation.

For restricted jurisdictions, if you try to get case text without authenticating, you'll run into this:

https://api.case.law/v1/cases/?jurisdiction=wash&page_size=1&full_case=true

      ...
      "casebody": {
        "data": null,
        "status": "error_auth_required"
      }
      ...

Authentication

Once you've read the access limits documentation to confirm you need to authenticate, and registered your account, you're ready to authenticate your requests.

Find your API Key

First, log in to your account using the LOG IN link at the top of the screen. After you've signed in, the link at the top of the screen now reads ACCOUNT. Click that link. In the API key field, you should see a 40-character long string. That is your API key.

Modify Your Headers

You must submit the API key in the request headers. The headers are a group of metadata fields automatically included in the background of each request. Your browser (or equivalent, like curl, or Python's requests library) uses headers to describe each request to the server, and the server uses headers to describe its response. For example, your web browser will include a header field called User-Agent, which tells the web server what version of what browser you're using, on what operating system. Among the various headers in its response, the server will include a Content-Type field, which says if it's HTML text, an image, etc. Our service requires you to include the header labeled Authorization, containing the string Token [your API key]. So, if your API key were 1234thisisntarealapikeysodontusethisone1, your header would look like this: Authorization: Token 1234thisisntarealapikeysodontusethisone1.

In practice, that looks like this:

curl

curl -H "Authorization: Token 1234thisisntarealapikeysodontusethisone1" "https://api.case.law/v1/cases/435800/?full_case=true"

python requests library

response = requests.get(
    'https://api.case.law/v1/cases/435800/?full_case=true',
    headers={
        'Authorization': 'Token 1234thisisntarealapikeysodontusethisone1'
    })

Other Environments

Other environments work much the same way — consult your documentation to see how to modify the headers of your request. As long as a header labelled Authorization has a value of Token [your API key], that should do the trick.

Doesn't work?

There are a few common errors that trip up API users.

error_auth_required

If you request full case text from from restricted jurisdictions without authenticating, this is what you'll see in the casebody section of each case:

  "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". To resolve this, simply include a valid API key in your request.

error_limit_exceeded

You've likely exceeded your limit of 500 per day limit of restricted case texts. See the access limits documentation for more info.

Case Text Formats

All non-browser API responses are in JSON format.

{
    "count": (integer),
    "next": (url),
    "previous": (url),
    "results": [list of objects]
}

Each endpoint has its own object format. For a complete breakdown, check out our data specs.

This is what a case object looks like:

{
    "id": (int),
    "url": (API url to this case),
    "name": (string),
    "name_abbreviation": (string),
    "decision_date": (string),
    "docket_number": (string),
    "first_page": (string),
    "last_page": (string),
    "citations": [array of citation objects],
    "volume": {Volume Object},
    "reporter": {Reporter Object},
    "court": {Court Object},
    "jurisdiction": {Jurisdiction Object},
    "cites_to": [array of cases this case cites to],
    "frontend_url": (url of case on our website),
    "frontend_pdf_url": (url of case pdf),
    "preview": [array of snippets that contain search term],
    "analysis": {
        "cardinality": (int),
        "char_count": (int),
        "ocr_confidence": (float),
        "sha256": (str),
        "simhash": (str),
        "word_count": (int)
    },
    "last_updated": (datetime),
    "casebody": {
        "status": ok/(error)"
        "data": (null if status is not ok) {
            "judges": [array of strings that contain judges names],
            "parties": [array of strings containing party names],
            "opinions": [
                {
                    "text": (case text),
                    "type": (string),
                    "author": (string)
                }
            ],
            "attorneys": [array of strings that contain attorneys names],
            "corrections": (string. May include formatting notes.),
            "head_matter": (elements before the case text)
        }
    }
}

By default, when you include full_case=true in your request url, the cases endpoint returns structured plain text. Structured text is most useful for natural language processing. By changing the body_format query parameter, it can also return the casebody in XML (body_format=xml), or HTML (body_format=html).

Structured Casebody Text

https://api.case.law/v1/cases/?jurisdiction=ill&full_case=true

Example response data:

"data": {
      "head_matter": "Fifth District\n(No. 70-17;\nThe People of the State of Illinois ...",
      "opinions": [
          {
              "author": "Mr. PRESIDING JUSTICE EBERSPACHER",
              "text": "Mr. PRESIDING JUSTICE EBERSPACHER\ndelivered the opinion of the court: ...",
              "type": "majority"
          }
      ],
      "judges": [],
      "attorneys": [
          "John D. Shulleriberger, Morton Zwick, ...",
          "Robert H. Rice, State’s Attorney, of Belleville, for the Peop ..."
      ]
  }
}

In this example, "head_matter" is a string representing all text printed in the volume before the text prepared by judges. "opinions" is an array containing a dictionary for each opinion in the case. "judges", and "attorneys" are particular substrings from "head_matter" that we believe refer to entities involved with the case.

Other Endpoints

The other endpoints function in a very similar way to the case endpoint, though the parameters and return values are different. Check out our API Reference for a complete list of endpoints and values. Check out our data specs for a complete rundown of data formats.

  • Find what you were looking for?

    If you have suggestions for improving this documentation, let us know!

CAP API In Depth

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