Supreme Court Visualization API

Use this API to programmatically create and manage Supreme Court network visualizations in CourtListener.

Overview

/api/rest/v4/visualizations/

All visualizations are associated with a user and are private by default. When you GET these endpoints, you will see data for visualizations that have been made public by their owners or that you have created yourself.

To learn more about opinion clusters, see the case law API documentation. To learn more about citations between decisions see the citation API documentation.

Creating Visualizations

To create a new visualization, send an HTTP POST with a title, a starting cluster ID, and an ending cluster ID:

curl -X POST \
  --data 'cluster_start=/api/rest/v4/clusters/105659/' \
  --data 'cluster_end=/api/rest/v4/clusters/111891/' \
  --data 'title=A map from Trop to Salerno' \
  --header 'Authorization: Token <your-token-here>' \
  "https://www.courtlistener.com/api/rest/v4/visualizations/"

The cluster_start and cluster_end parameters use URLs instead of IDs.

The above command creates a visualization unless there are no connections between the start and end clusters or the network becomes too large to generate.

Once created, the visualization will have nested JSON data representing the visualization itself, a list of clusters that are in it, and various other metadata.

Editing and Deleting Visualizations

Changing data for an existing visualization can be done via an HTTP PATCH request. For example, to make a visualization publicly accessible:

curl -X PATCH \
  --data 'published=True' \
  --header 'Authorization: Token <your-token-here>' \
  "https://www.courtlistener.com/api/rest/v4/visualizations/1/"

Similar commands can be used to update other non-readonly fields.

To soft-delete a visualization, flip the deleted field to True. To hard-delete, send an HTTP DELETE request.

Deprecation Notice

If you are interested in creating, deleting, or updating visualizations, you can still do so through our APIs, but it is no longer possible to display visualizations on CourtListener.com itself. Moving forward, to support existing users, the only way to display visualizations is through their embed links.

To embed a visualization on a website you control, use code like the following on your site:

<iframe height="540" width="560" src="https://www.courtlistener.com/visualizations/scotus-mapper/YOUR_ID_HERE/embed/" frameborder="0" allowfullscreen></iframe>

Just replace YOURIDHERE with the ID of your visualization, and it should work on your website.

The following GET parameters may be used to adjust the display:

• type — Use this to set the y-axis. spread opens up the visualization with random locations for the nodes so they can all be seen. geneology makes many paths lighter to highlight the most direct paths. spaeth uses the Supreme Court Database's vote count and decision direction fields.
• xaxis — The x-axis may be set to either equal spacing (cat) or accurate chronological spacing (time)
• dos — Use this to set the Degree of Separation, which represents the maximum number of hops between the first and last nodes.

For example, GET parameters like these will provide a clean, equally spaced chart with up to five nodes of separation: ?type=geneology&xaxis=cat&dos=5.

We apologize for this deprecation and hope you understand that we cannot always maintain all the features and experiments we undertake.

Frequently Asked Questions

Learn more about these visualizations on their FAQ page.