Tausi API

The Tausi API is a read-only, REST, JSON-based API that allows external services to fetch structured and formatted decisions from Tausi.

The API is implemented using Django Rest Framework which takes care of the bulk of the API plumbing.

Only published decisions are available through the API. Decisions that are still being processed and reviewed are not available.

NOTE: Full API documentation will follow, once the API has been implemented.

Versioning

The API is versioned using a version number in the URL. Backwards incompatible changes to the API require a new API version.

Location

The API is available at the path /api/v1/.

Data formats

The API is a REST API that primarily uses JSON as a data format. Some requests can also return XML, HTML or PDF data.

Authentication

Calls to the API must be authenticated using your API token. To get a token,

1. Sign into your Tausi account

2. Get your API token from your profile page

Include your API token in your API calls by including an Authorization header:

Authorization: Token YOUR_AUTH_TOKEN

API access also requires a dedicated permission that gives full access to all the listable content types available via the API.

Pagination

API calls that return lists will be paginated and return a limited number of items per page. The response includes information on the total number of items and the URLs to use to fetch the next and previous pages of items.

Here’s an example of the first page of a paginated response with 250 total items and two pages:

{
  "count": 250,
  "next": "https://example.com/api/v1/decisions/.json?page=2",
  "previous": null,
  "results": [ "..." ]
}

In this case, fetching the next URL will return the second (and final) page.

FRBR URIs

Decisions are uniquely identified by an FRBR URI. This is a special URI used by the Akoma Ntoso data standard that uniquely identifies a decision. The FRBR URI corresponds directly to the Medium-Neutral Citation (MNC) for the decision.

For example, the decision with MNC [2018] KEHC 500 (KLR) has the FRBR URI /akn/ke/judgment/kehc/2018/500.

Listing decisions

/api/v1/decisions will be used to return the paginated listing of decisions.

List decisions

GET /api/v1/decisions/.json

This will list all decisions (judgments) for Kenya.

List decisions for a court and a year

GET /api/v1/decisions/?court=:court
GET /api/v1/decisions/?court=:court&year=:year

This will list all decisions for a court identified by the court code :court and the :year.

Filtering lists

Various filters can be applied to listings, using the formats supported by Django Rest Framework. This is achieved using the DjangoFilterBackend extension.

For instance, to get all the cases delivered in 2020 in the High Court at Nairobi, the request endpoint would be:

GET /api/v1/decisions/?year=2020&court=HCNRB

The various filter parameters include:

• Court (unique code)

• Court division

• Court class

• County

• Delivery year

• Filing year

• Flags

• Case type

• Anonymisation status

• Area of law

Get decision details

The primary URL for a decision would be /decisions/<frbr-uri>

GET /api/v1/decisions/akn/ke/judgment/:court/:year/:number.json

Fetches the JSON details of a decision which includes accompanying metadata such as:

• court data

• flags

• judges information

• advocates information

Response format

The JSON response for the details of a single decision will include details of the nested fields such as parties, judges, courts and counties. Django Rest Framework offers support for the serialization of nested objects as described here in the documentation.

Here is an example of a response containing a subset of a decision’s details:

{
    "short_mnc": "[2020] KEHCBS 23 (KLR)",
    "full_mnc": "Honey Bee Limited v B & another (Civil Suit 444 of 2019) [2020] KEHCBS 23 (KLR) (Civ) (10 November 2020) (Ruling)",
    "case_number_string": "Civil Suit 444 of 2019",
    "case_number_numeric": 444,
    "filing_year": "2020,
    "action": {
        "name": "Ruling",
        "decsription": null
    },
    "casetype": {
        "name": "Civil Suit",
        "description": null
    },
    "filing_county": {
        "name": "Nairobi",
        "code": 47
    },
    "court": {
        "name": "High Court at Busia",
        "code": "HCBS",
        "mnc_code": "KEHCBS",
        "county": {
            "name": "Busia",
            "code": 40
        },
        "court_class": {
            "name": "High Court"
        }
    },
    "judges": [
        {
            "name": "Robert Kipkoech Limo",
            "short_name": "RK Limo",
            "title": "Judge"
        },
        {
            "name": "Stella Ngali Mutuku",
            "short_name": "SN Mutuku",
            "title": "Judge"
        }
    ],
    "advocates: [
        {
            "name": "Advocate Z",
            "for_party": "Honey Bee Limited"
        },
        {
            "name": "Advocate Y",
            "for_party": "Party B"
        }
    ],
    "parties": [
        {
            "name": "Honey Bee Limited",
            "name_for_citation": "Honey Bee Limited",
            "party_group": 1
        },
        {
            "name": "Party B",
            "name_for_citation": "B",
            "party_group": 2 
        },
        {
            "name": "Party C",
            "name_for_citation": "C",
            "party_group": 2 
        },
    ],
    "flags": [
        {
            "label": "Law reform",
            "color": null,
            "description": "Law reform issue"
        },
        {
            "label": "Flag 2",
            "color": null,
            "description": null
        }
    ],

}

Get decision content

GET /api/v1/decisions/akn/ke/judgment/:court/:year/:number.xml
GET /api/v1/decisions/akn/ke/judgment/:court/:year/:number.html
GET /api/v1/decisions/akn/ke/judgment/:court/:year/:number.pdf

Fetches the content (body) of a decision in various formats.

Other listable content types

Extra listable content types are made available to enhance the filtering of decisions. The following is a list of the other listable content types and their endpoints:

Courts

GET /api/v1/courts

Fetches a list of courts.

GET /api/v1/courts/:court_code

Fetches the details of a single court matching the provided :court_code.

Court divisions

GET /api/v1/courtdivisions 

Fetches a list of available court divisions.

Court classes

GET /api/v1/courtclasses 

Fetches a list of available court classes.

Flags

GET /api/v1/flags 

Fetches a list of available flags.

Judges

GET /api/v1/judges

This endpoint returns a list of judges.

GET /api/v1/judges/:id

Fetches the details of a single court matching the provided judge :id.

Case Types

GET /api/v1/casetypes

This will list available case types.

Case Actions

GET /api/v1/caseactions

Fetches a list of case actions.

Areas of Law

GET /api/v1/areasoflaw

Fetches a list of areas of law.

Counties

GET /api/v1/counties

Fetches a list of counties.

Search

Full-text, faceted search across published decisions is achieved using ElasticSearch. This requires all published decisions to be indexed on the Elastic Search host. This adds functionality such as:

• Find-as-you-type

• Modern language support such synonyms and stemming

• Spelling corrections support

The search API will be available at:

GET /api/v1/search

Parameters:

• q: free-text search string

• filters: filters to apply to search results, as per listing filters

TODO: Search API specification and output to be finalised