The Lex Machina API has now been released for general availability. This brings in some highly anticipated features, like the availability of some state court data. That also brings in changes that will require changes from work in the beta version of the API. In this article, they will be listed by broad category of endpoint.

List Endpoints

All of the /list-* endpoints now require one of two arguments: “State” or “FederalDistrict”. In the beta version, many of the list endpoints returned JSON arrays at the top level. All endpoints now return JSON objects that include an element specifying which courts they are applicable to. As an example, here is the FederalDistrict output:

{
    "court": {
        "name": "All Federal District Courts",
        "type": "FederalDistrict"
    },
    "events": [
        "Markman Hearing",
        "Permanent Injuction",
        "Summary Judgment",
        "Dismiss (Contested)",
        "Filed",
        "Terminated"
    ]
}

and here is the State version of the same list:

{
    "court": {
        "name": "All State Courts",
        "type": "State"
    },
    "events": [
        "Filed",
        "Trial",
        "Terminated"
    ]
}

The one exception to this pattern is that /list-judgment-sources/FederalDistrict lists judgment sources for district cases and has now state equivalent. Conversely, /list-judgment-events/State has no district equivalent. The district and state courts are different enough in judgments that these two endpoints each have their own structure.

Entity Endpoints

The entity endpoints are largely unchanged. Anything not mentioned has not changed.

The /search-judges endpoint now returns three groupings inside the JSON object:

{
    "federalJudges": [],
    "magistrateJudges": [],
    "stateJudges": []
}

There is an additional endpoint besides /federal-judges and /magistrate-judges, the new endpoint /state-judges which works the same and takes parameters on the same pattern.

District Case Query

Previously, the return value of the /query-district-cases/ endpoint was an array of caseIds. Now it is an object with a field name “cases” that contains an array of DistrictCaseReference objects. These objects consist of a districtCaseId field with the Lex Machina id and an url field with the fully qualifed link to the single case lookup.

{
    "cases": [
        {
            "url": "https://localhost:8000/district-cases/966",
            "districtCaseId": 966
        },
        {
            "url": "https://localhost:8000/district-cases/5791",
            "districtCaseId": 5791
        }
    ]
}

State Cases

There are now two new endpoints which have been added to the API. Just as there was the previous /district-cases/ and /query-district-cases/ there are now the analogous /state-cases/ and /query-state-cases/ endpoints.

The /state-cases/ endpoint is straightforward. It takes a single Lex Machina case ID and returns the full case information for that case. It requires no additional parameters because a case ID is already unique across all courts in the database.

This is not the case for the /query-state-cases/ endpoint. It takes many of the same parameters in the JSON object in the body of a POST request. State has an additional required parameter in the form of the state specifier. This can specify a whole state or an include/exclude for specific court(s) within a state but it must be present or an error will be returned.

    "courts": {
        "state": "CA"
    },

or

"courts": {
    "state": "TX",
    "include": [ "Harris County Court"
    ]
  },

or

"courts": {
    "state": "NY",
    "exclude": [ "Richmond County Supreme Court",
    "Bronx County Supreme Court"
    ]
  },

The state query will be covered in its own post similarly to the district court query guide.

Conclusion

Overall while much of the API has changed in either input or output, as you can see from above that most of the changes fall into a few patterns. Hopefully that will make any transition work understandable and predictable. While disruption is never the goal, the choice was either have district and state operate completely differently or make them operate in similar manners while requiring changes.

As always, if you need help in this transition please reach out to the Lex Machina Developer team. Happy conversion!