Lex Machina API

Beta Release

This software is a beta in ongoing development. Bugs and outages are possible as well as the occasional breaking change between now and general availability.

Case and Entity Data

The API is built to provide data on cases and the entities relevant to cases like judges, law firms, and parties. A set of cases with relevant metadata, such as specific types and amounts of damages, can then provide a dataset for direct consumption or analytics.

District Case

The core data structure of the API, this is a collection of everything Lex Machina knows about a single district case. All other data types are generally relevant in their relation to a case.

Endpoint Structure

Query

Endpoints like /query-district-cases/ allow a user to create a query that returns a large set of cases based on specific criteria. This is the core function of this version of the API: finding relevant cases to collect other data from.

Get

Endpoints like /federal-judges/{federal_judge_id} provide a way to get information about a single entity or can be used with query parameters to retrieve data about multiple entities.

List

Endpoints like /list-courts/ provide the list of options for the query methods, in this case as the list of valid courts to filter on.

Search

Endpoints like /search-judges allow the user to search for a specific entity in order to build queries relevant to that entity.

Resolve

Resolvers like /resolve-law-firms/ are used to resolve entities ids, see the section below on IDs for more detail.

IDs

The API makes heavy use of numeric ids and in order to be accurate and complete Lex Machina’s ID structure can be rather complex. The two major things to be aware of are normalized IDs and ID Spaces.

Normalized IDs

When Lex Machina consumes legal data each individual mention of a relevant entity is given a unique ID. We then normalize all of these IDs, such that each entity only uses a single ID and all others refer to it.

The API only deals with normalized IDs; any ID output will be a normalized IDs. However because we renormalize to include more complete or changing data over time, the normalized ID for an entity may change. The old ID, however, can still be resolved to the new one. For this reason we provide resolver methods, which map IDs to the current normalized ID.

All the other methods are also able to resolve IDs and will provide correct data with old IDs. And the normalized IDs for well established entities tend to change rarely. Thus this is generally not a major functional issue.

ID Spaces

All of our IDs are integers, thus understanding the relevant ID space for each type of ID can be helpful to understand the data. These are the ID spaces that exist for each type of data used by the API.

District Cases - All district cases have a single ID space.

Federal Article III Judges - These IDs are provided by the FJC and are their own ID space. Also note that because these are provided to us there is no normalization process for such judges, their IDs are unique.

Magistrate Judges - Magistrates on district court cases.

Counsel - Law Firms and Attorneys share an ID space, common across all sets of cases.

Parties - Parties have an ID space common across all sets of cases.

ExpertWitnesses - Expert witnesses have an ID space common across all sets of cases.