How do you work with nature of suit?

[mlissner]

An emailer writes:

I was trying to retrieve specific filings using the field nature_of_suit (or SuitNature) as a filtering parameter in the search, dockets and fjc-integrated endpoints.

Here are a few examples which I have tried (After a while I kinda tried to bruteforce it as you can see):
https://www.courtlistener.com/api/rest/v3/fjc-integrated-database/?suitNature=120
https://www.courtlistener.com/api/rest/v3/fjc-integrated-database/?suitNature=Marine
https://www.courtlistener.com/api/rest/v3/fjc-integrated-database/?nature_of_suit=120
https://www.courtlistener.com/api/rest/v3/fjc-integrated-database/?nature_of_suit=Marine
https://www.courtlistener.com/api/rest/v3/clusters/?SuitNature=120
https://www.courtlistener.com/api/rest/v3/clusters/?SuitNature=Marine
https://www.courtlistener.com/api/rest/v3/clusters/?nature_of_suit=120
https://www.courtlistener.com/api/rest/v3/clusters/?nature_of_suit=Marine
https://www.courtlistener.com/api/rest/v3/search/?SuitNature=120
https://www.courtlistener.com/api/rest/v3/search/?nature_of_suit=Marine
https://www.courtlistener.com/api/rest/v3/search/?SuitNature=120
https://www.courtlistener.com/api/rest/v3/search/?nature_of_suit=Marine

They all seem to respond to other filters whether numeric, Boolean or textual. Could you please help me figure this out?

[mlissner]

Hi, um, Mike! The Nature of Suit code can be queried in two ways. First, via search. To identify a query using search, start on the front end, with a query like:

https://www.courtlistener.com/?type=r&q=&type=r&order_by=score%20desc&nature_of_suit=120

That'll give you all the items with NoS of "120", but note that these are not normalized and sometimes courts just give the NoS as a string, so you'd want to be a bit more clever with something like 120 OR Marine OR...

But the next step I'd take is to convert that to an API request by tweaking the URL:

https://www.courtlistener.com/api/rest/v3/search/?type=r&q=&type=r&order_by=score%20desc&nature_of_suit=120

Now you get back JSON.

Great!

Now, the NoS code is a field on the docket object, so you might also be thinking, "Hey, can I get dockets instead of search results?" I didn't know if this was possible, so I checked by sending an HTTP OPTIONS request to the docket endpoint, and then using jq to filter to the NoS field:

04:13:41::mlissner@rhyolite::~/Programming 
↪ curl --silent -X OPTIONS https://www.courtlistener.com/api/rest/v3/dockets/ | jq '.filters.nature_of_suit'
{
  "type": "CharFilter",
  "lookup_types": [
    "exact",
    "iexact",
    "startswith",
    "istartswith",
    "endswith",
    "iendswith",
    "contains",
    "icontains"
  ]
}

That tells you that, yes, you can do look-ups on the NoS. field of the docket. Therefore, I tried this:

curl --silent https://www.courtlistener.com/api/rest/v3/dockets/?nature_of_suit__contains=120

That was very slow, but it did eventually work. We have database index on that field, but the table still has 60M records, so this kind of thing is hard. startswith was a lot faster:

curl --silent https://www.courtlistener.com/api/rest/v3/dockets/?nature_of_suit__startswith=120

Doing an exact query would be better too, but searching is going to generally be best for speed.

Does this help?

[Eran-T]

Hi there. Quick follow-up question.
I have been trying to do something similar with the 'cause' field. however, each time I try and filter out the search using 'startswith' when using the cause field, I get the entire 66m-long list of docket instances. (Is that the result of searching a non-existent filter and how do I overcome this?).
Many thanks in advance.

[mlissner]

Sorry I missed this. Yes, if you use a non-existent filter field, it simply gets ignored. I with it weren't so, but it is how our API library works.