How do I get the title and organization information for a judge?

[mlissner]

A user writes:

We noticed that the judges​ endpoint includes a positions​ array with their past jobs, but judicial positions are missing a position_title​ and organization_name​ The org name I assume we can pull from the nested court​ object, but I’m wondering how y’all are populating the job title on your front end? I saw a position​ property within the court object that seems to be an integer, and I initially thought that might correspond to a job title, but I haven’t been able to find a dictionary for those in the courtlistener repo.

Appreciate any light you can shed here!

So: How can we get the title and org info for a judge, and what is the position information for a court?

[mlissner]

First, the position information on a court is described in the API as:

↪ curl -s -X OPTIONS https://www.courtlistener.com/api/rest/v3/courts/ | jq '.actions.POST.position'
{
  "type": "float",
  "required": true,
  "read_only": false,
  "label": "Position",
  "help_text": "A dewey-decimal-style numeral indicating a hierarchical ordering of jurisdictions"
}

That's not a terrible description of it. The general idea is that we need to know what order to list courts in. Alphabetical doesn't do it, and we are constantly adding more danged courts. By sorting them by position, we can put SCOTUS first, then circuit courts, then state courts, etc.

---

Your next (and actual) question was, how do we get the title information for a judge? Good question. Looking at the schema, judges are linked to position objects. Position objects have a lot of fields as I recall, so which ones matter?

Let's take a look, as above. I actually forget how this works, so let's explore together. First, this gets us the field definitions for the positions table:

curl -s -X OPTIONS https://www.courtlistener.com/api/rest/v3/positions/ | jq '.actions.POST'
...lots of output here...

Looking at that, I see a couple fields:

↪ curl -s -X OPTIONS https://www.courtlistener.com/api/rest/v3/positions/ | jq '.actions.POST.job_title'
{
  "type": "string",
  "required": false,
  "read_only": false,
  "label": "Job title",
  "help_text": "If title isn't in position_type, a free-text position may be entered here.",
  "max_length": 100
}

Interesting! Remind me, API, what's position_type?

↪ curl -s -X OPTIONS https://www.courtlistener.com/api/rest/v3/positions/ | jq '.actions.POST.position_type'
{
  "type": "choice",
  "required": false,
  "read_only": false,
  "label": "Position type",
  "help_text": "If this is a judicial position, this indicates the role the person had. This field may be blank if job_title is complete instead.",
  "choices": [
    {
      "value": "jud",
      "display_name": "Judge"
    },
    {
      "value": "jus",
      "display_name": "Justice"
    },
    {
      "value": "ad-law-jud",
      "display_name": "Administrative Law Judge"
    },
    {
      "value": "act-jud",
      "display_name": "Acting Judge"
    },
    {
      "value": "act-jus",
      "display_name": "Acting Justice"
    },
    {
      "value": "act-pres-jud",
      "display_name": "Acting Presiding Judge"
    },
    {
      "value": "act-c-admin-jus",
      "display_name": "Acting Chief Administrative Justice"
    },
    {
      "value": "ass-jud",
      "display_name": "Associate Judge"
    },
    {
      "value": "ass-jus",
      "display_name": "Associate Justice"
    },
    {
      "value": "ass-c-jud",
      "display_name": "Associate Chief Judge"
    },
    {
      "value": "ass-pres-jud",
      "display_name": "Associate Presiding Judge"
    },
    {
      "value": "asst-pres-jud",
      "display_name": "Assistant Presiding Judge"
    },
    {
      "value": "c-jud",
      "display_name": "Chief Judge"
    },
    {
      "value": "c-jus",
      "display_name": "Chief Justice"
    },
    {
      "value": "c-spec-m",
      "display_name": "Chief Special Master"
    },
    {
      "value": "c-admin-jus",
      "display_name": "Chief Administrative Justice"
    },
    {
      "value": "pres-jud",
      "display_name": "Presiding Judge"
    },
    {
      "value": "pres-jus",
      "display_name": "Presiding Justice"
    },
    {
      "value": "sup-jud",
      "display_name": "Supervising Judge"
    },
    {
      "value": "ad-pres-jus",
      "display_name": "Administrative Presiding Justice"
    },
    {
      "value": "com",
      "display_name": "Commissioner"
    },
    {
      "value": "com-dep",
      "display_name": "Deputy Commissioner"
    },
    {
      "value": "jud-pt",
      "display_name": "Judge Pro Tem"
    },
    {
      "value": "jus-pt",
      "display_name": "Justice Pro Tem"
    },
    {
      "value": "ref-jud-tr",
      "display_name": "Judge Trial Referee"
    },
    {
      "value": "ref-off",
      "display_name": "Official Referee"
    },
    {
      "value": "ref-state-trial",
      "display_name": "State Trial Referee"
    },
    {
      "value": "ret-act-jus",
      "display_name": "Active Retired Justice"
    },
    {
      "value": "ret-ass-jud",
      "display_name": "Retired Associate Judge"
    },
    {
      "value": "ret-c-jud",
      "display_name": "Retired Chief Judge"
    },
    {
      "value": "ret-jus",
      "display_name": "Retired Justice"
    },
    {
      "value": "ret-senior-jud",
      "display_name": "Senior Judge"
    },
    {
      "value": "mag",
      "display_name": "Magistrate"
    },
    {
      "value": "c-mag",
      "display_name": "Chief Magistrate"
    },
    {
      "value": "pres-mag",
      "display_name": "Presiding Magistrate"
    },
    {
      "value": "mag-pt",
      "display_name": "Magistrate Pro Tem"
    },
    {
      "value": "mag-rc",
      "display_name": "Magistrate (Recalled)"
    },
    {
      "value": "mag-part-time",
      "display_name": "Magistrate (Part-Time)"
    },
    {
      "value": "spec-chair",
      "display_name": "Special Chairman"
    },
    {
      "value": "spec-jud",
      "display_name": "Special Judge"
    },
    {
      "value": "spec-m",
      "display_name": "Special Master"
    },
    {
      "value": "spec-scjcbc",
      "display_name": "Special Superior Court Judge for Complex Business Cases"
    },
    {
      "value": "chair",
      "display_name": "Chairman"
    },
    {
      "value": "chan",
      "display_name": "Chancellor"
    },
    {
      "value": "presi-jud",
      "display_name": "President"
    },
    {
      "value": "res-jud",
      "display_name": "Reserve Judge"
    },
    {
      "value": "trial-jud",
      "display_name": "Trial Judge"
    },
    {
      "value": "vice-chan",
      "display_name": "Vice Chancellor"
    },
    {
      "value": "vice-cj",
      "display_name": "Vice Chief Judge"
    },
    {
      "value": "att-gen",
      "display_name": "Attorney General"
    },
    {
      "value": "att-gen-ass",
      "display_name": "Assistant Attorney General"
    },
    {
      "value": "att-gen-ass-spec",
      "display_name": "Special Assistant Attorney General"
    },
    {
      "value": "sen-counsel",
      "display_name": "Senior Counsel"
    },
    {
      "value": "dep-sol-gen",
      "display_name": "Deputy Solicitor General"
    },
    {
      "value": "pres",
      "display_name": "President of the United States"
    },
    {
      "value": "gov",
      "display_name": "Governor"
    },
    {
      "value": "mayor",
      "display_name": "Mayor"
    },
    {
      "value": "clerk",
      "display_name": "Clerk"
    },
    {
      "value": "clerk-chief-dep",
      "display_name": "Chief Deputy Clerk"
    },
    {
      "value": "staff-atty",
      "display_name": "Staff Attorney"
    },
    {
      "value": "prof",
      "display_name": "Professor"
    },
    {
      "value": "adj-prof",
      "display_name": "Adjunct Professor"
    },
    {
      "value": "prac",
      "display_name": "Practitioner"
    },
    {
      "value": "pros",
      "display_name": "Prosecutor"
    },
    {
      "value": "pub-def",
      "display_name": "Public Defender"
    },
    {
      "value": "da",
      "display_name": "District Attorney"
    },
    {
      "value": "ada",
      "display_name": "Assistant District Attorney"
    },
    {
      "value": "legis",
      "display_name": "Legislator"
    },
    {
      "value": "sen",
      "display_name": "Senator"
    },
    {
      "value": "state-sen",
      "display_name": "State Senator"
    }
  ]
}

OK, that looks pretty good, and it gives us a long (structured) mapping of the possible values. Seems not to bad.

The third question was organization. I happened to see this when looking at the positions. So, again:

↪ curl -s -X OPTIONS https://www.courtlistener.com/api/rest/v3/positions/ | jq '.actions.POST.organization_name'
{
  "type": "string",
  "required": false,
  "read_only": false,
  "label": "Organization name",
  "help_text": "If the organization where this position was held is not a school or court, this is the place it was held.",
  "max_length": 120
}

Cool. That hints at the fact that if it's a school or court we're going to do that as structured data (as your question surmised). I also saw that next to the organization_name field there was location_city, and location_state, which would be useful, I imagine.

The last thing you could do, if you wanted to really confirm this is all correct, would be to grab one of these fields and see how it's used in the code. Pulling together all of this judge information is fairly complicated because it's so detailed, but a search for any of these fields will work well. Perhaps something like:

https://github.com/search?q=repo%3Afreelawproject%2Fcourtlistener+organization_name+%28language%3APython+OR+language%3AHTML%29&type=code

I hope this helps!