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, __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
  • 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
  • docket_number
  • 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
  • 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 Search for more details.
  • reporter
    • data type: integer
    • description: reporter id
  • 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".

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