District Courts¶

DistrictCourtClient is the live client for the District Courts portal at services.ecourts.gov.in — the national eCourts service that covers 700+ district and taluka courts across every state and union territory. Use it for live case status, court orders, and cause lists at the district level.

The 4-level hierarchy¶

Unlike High Courts (which you address with a single static code via get_court()), district courts are organised as a four-level cascade. You must resolve all four levels before you can search:

State  →  District  →  Court Complex  →  Establishment
 "8"       "1"          "1080010"          "2"
 Bihar     Patna        Civil Court        (a specific court within the complex)

• State — the state or UT (e.g. "8" = Bihar). 36 in total.
• District — a district within that state (e.g. "1" = Patna).
• Court Complex — a physical court complex within the district. A complex may contain one or many establishments.
• Establishment — a specific court within a complex. Only required for some complexes (see the note on the complex value format below).

Because these codes are not static and differ from district to district, you discover them dynamically by walking the cascade — each step's output feeds the next.

The discovery flow¶

list_states()                          → {"8": "Bihar", ...}
list_districts("8")                    → {"1": "Patna", ...}
list_complexes("8", "1")               → {"1080010@2,3,4@Y": "Civil Court, Patna Sadar", ...}
parse_complex_value("1080010@2,3,4@Y") → ("1080010", ["2","3","4"], True)
list_establishments("8","1","1080010") → {"2": "...", ...}   # only if flag is Y
list_case_types("8","1","1080010","2") → {"1": "Civil Suit", ...}

The discovery methods are CAPTCHA-free — only the actual searches (case_status, case_status_by_party, court_orders, cause_list) require a CAPTCHA, which the client solves and retries automatically.

Method reference¶

All search methods take state_code, dist_code, court_complex_code, and an optional est_code (resolved via the discovery methods above). Search methods are keyword-only (*) — pass them by name.

Worked example¶

This walks the full cascade — discover the hierarchy, parse the complex value, list case types, then run searches. CAPTCHA solving and retries happen automatically when an OCR solver is configured (the default when bharat-courts[ocr] is installed).

import asyncio
from bharat_courts import DistrictCourtClient
from bharat_courts.captcha.ocr import OCRCaptchaSolver
from bharat_courts.districtcourts.parser import parse_complex_value


async def main():
    solver = OCRCaptchaSolver()

    async with DistrictCourtClient(captcha_solver=solver) as client:
        # 1. Discover the court hierarchy (no CAPTCHA)
        states = await client.list_states()
        # {"8": "Bihar", "7": "Delhi", ...}

        districts = await client.list_districts("8")        # Bihar
        # {"1": "Patna", "35": "Gaya", ...}

        complexes = await client.list_complexes("8", "1")   # Patna
        # {"1080010@2,3,4@Y": "Civil Court, Patna Sadar", ...}

        # 2. Parse the complex value → (complex_code, est_codes, needs_establishment)
        complex_val = next(iter(complexes))
        complex_code, est_codes, needs_est = parse_complex_value(complex_val)
        est_code = est_codes[0] if needs_est else ""

        # 2b. If the complex needs an establishment, list them and pick one
        if needs_est:
            establishments = await client.list_establishments("8", "1", complex_code)
            # {"2": "Civil Judge Sr. Div.", ...}
            est_code = next(iter(establishments))

        # 3. Discover case types for this court (no CAPTCHA)
        case_types = await client.list_case_types("8", "1", complex_code, est_code)
        # {"1^2": "Civil Suit", "89^2": "ADMINISTRATIVE SUITE", ...}

        # 4. Search by party name (CAPTCHA auto-solved and retried)
        cases = await client.case_status_by_party(
            state_code="8", dist_code="1",
            court_complex_code=complex_code, est_code=est_code,
            party_name="kumar", year="2024",
        )
        for c in cases:
            print(f"{c.case_number}: {c.petitioner} vs {c.respondent}  [{c.cnr_number}]")

        # 5. Search by case number
        by_number = await client.case_status(
            state_code="8", dist_code="1",
            court_complex_code=complex_code, est_code=est_code,
            case_type="1", case_number="100", year="2024",
        )

        # 6. Get orders for a case
        orders = await client.court_orders(
            state_code="8", dist_code="1",
            court_complex_code=complex_code, est_code=est_code,
            case_type="1", case_number="100", year="2024",
        )
        for o in orders:
            print(f"{o.order_date} | {o.order_type} | {o.judge} | {o.pdf_url}")

        # 7. Cause list — court_name is auto-resolved from court_no if omitted
        entries = await client.cause_list(
            state_code="8", dist_code="1",
            court_complex_code=complex_code, est_code=est_code,
            court_no="1@2", civil=True,
        )
        for e in entries:
            print(f"{e.serial_number}. {e.case_number}: {e.petitioner} vs {e.respondent}")


asyncio.run(main())

Parsing the complex value¶

parse_complex_value(value) lives in bharat_courts.districtcourts.parser and is the bridge between the raw dropdown value and the bare codes the search methods expect:

from bharat_courts.districtcourts.parser import parse_complex_value

parse_complex_value("1080010@2,3,4@Y")
# → ("1080010", ["2", "3", "4"], True)   # needs an establishment

parse_complex_value("1080099@@N")
# → ("1080099", [], False)               # establishment not required

The third element is the needs_establishment boolean (the flag Y/N). When it is True, call list_establishments() and pass a chosen est_code to the search methods; when False, leave est_code="".

What you get back¶

District-court order PDFs (CaseOrder.pdf_url) are not always uploaded on eCourts even when the case exists. The client returns the URL it finds; the download itself may fail server-side if the file was never published.

How it works under the hood¶

The portal is session-and-token driven. Each AJAX response carries a rotating app_token that must accompany the next request, and the CAPTCHA is pinned to the PHP session. The client handles all of this for you:

1. GET the home page to establish the SERVICES_SESSID cookie.
2. Fetch an initial app_token.
3. Walk the cascade dropdowns (fillDistrict, fillcomplex, fillCourtEstablishment, fillCaseType).
4. Store the court selection server-side (set_data) before any search.
5. Solve the CAPTCHA and submit the query.

On a CAPTCHA rejection the client creates a fresh session (new cookies, new CAPTCHA), re-establishes the court selection, and retries — up to 5 attempts by default. You do not manage tokens, cookies, or retries yourself.

See also¶

• CAPTCHA handling — solver options and accuracy.
• High Courts — the sibling client for HC Services.
• Calcutta High Court — direct-website client.
• Clients API reference — full signatures.