Creating State Queries for the Lex Machina API

Overview

The Lex Machina API now allows for querying of some state case data as of general availability. In many ways it works the same as the federal district queries. For the purposes of this article, only the parts that differ will be discussed. For querying on the participants and such topics, please refer to the district query article. That will also explain the basics of operations such as the include and exclude, the date operators, etc.

Note that our state data is a partial but ever-growing set of courts inside states. Even in states for which we have coverage, we may not have cases for some courts. The full list of courts for which we get cases is at /list-courts/State.

The query endpoint for state is /query-state-cases and this is a POST request. The body of the POST will be a JSON structure of a form similar to this:

{
	"courts": {
		"state": "TX"
	},
	"caseStatus": "Terminated",
	"caseTypes": {
		"include": ["Contracts"]
	},
	"dates": {
		"filed": {"onOrBefore": "2010-01-01"},
		"terminated": {"onOrAfter": "2015-01-01"}
	},
	"page": 1,
	"pageSize": 50
}

Specifying State and Court

For state queries, it is required that there be one and only one state specified in the {“courts”{“state”: “YOUR STATE HERE”}} JSON object. Only one state can be queried at a time. If you need to query multiple states, that will require one request per state.

If the courts object contains only the “state” field, then all districts within the state will be queried. It is possible to use both the include and exclude operators to limit the courts within the state for the query. Note that Lex Machina state data can include some but not all courts within a state. The list of all covered courts can be accessed via the /list-courts/State endpoint.

• The results of this query will be a JSON object containing a “cases” field with maps to an arry of objects. These object will contain a “stateCaseId” field and an “url” field. In order to get a full picture of these cases, they will need to be looked up individually with the /state-cases/{case_id} endpoint.

{
    "cases": [
        {
            "url": "https://api.lexmachina.com/state-cases/2002947480",
            "stateCaseId": 2002947480
        },
        {
            "url": "https://api.lexmachina.com/state-cases/2003381551",
            "stateCaseId": 2003381551
        }
    ]
}

Query Types Not in State

The following fields are valid in district queries but not in state queries:

• “magistrates” does not exist in state queries
• “remedies” does not exist in state queries
• “findings” does not exist in state queries
• “patents” does not exist in state queries
• “mdl” does not exist in state queries

Query Types In State but Not in District

• “rulings” exists in state but not in district. The list of defined “judgmentEvent” values is avilable at the /list-judgment-events/State endpoint.

The full object looks like this:

"rulings": [
    {
      "judgmentEvent": {
        "include": [
          "<string>",
          "<string>"
        ],
        "exclude": [
          "<string>",
          "<string>"
        ]
      },
      "awardedToParties": [
        "<integer>",
        "<integer>"
      ],
      "awardedAgainstParties": [
        "<integer>",
        "<integer>"
      ],
      "date": {
        "onOrAfter": "<date>",
        "onOrBefore": "<date>"
      }
    }]

Query Types That Differ in State

• In district, “damages” contain a field called “nameType” made up of tuples of “name” and “type” than can be included or excluded. In state, this field is “name” and the includes and excludes are an array of simple strings.

Example Queries

To find Texas cases that began and ended in calendar 2020 the full body of the POST would be:

{
	"courts": {
		"state": "TX"
	},
	"dates": {
		"filed": {
			"onOrAfter": "2020-01-01"
		},
		"terminated": {
			"onOrBefore": "2020-12-31"
		}
  	}
}

To find the first 500 closed Texas cases except for Fort Bend County District Court:

{
	"courts": {
		"state": "TX",
		"exclude": [
			 "Fort Bend County District Court"
		]
	},
	"caseStatus": "Terminated",
	"page": 1,
	"pageSize": 500
}

Conclusion

With the addition of state data, this expands the reach of what can be achieved with the Lex Machina API. There are some quirks between the two queries because state and district court have some different concepts and different ways of capturing the data associated with a court case. The basics are the same and with a little practice writing queries for either set of courts should become routine.

If you have any challenges, issues or concerns always feel free to raise them to dslusher@lexmachina.com . Happy building and merry querying!