Indian Court Data with bharat-courts

Indian Court Data with bharat-courts

Async Python SDK. Three things to know:

1. Judgments facade (recommended default) — one find(...) call, routes between archive and live transparently, returns a uniform Judgment list. Use this first.
2. Live clients (HCServicesClient, DistrictCourtClient, CalcuttaHCClient, JudgmentSearchClient, SCIClient) — for portal-specific features the facade doesn't expose: case status, cause lists, district-court drill-down, current orders. CAPTCHA-gated, rate-limited.
3. ArchiveClient — direct access to the AWS Open Data buckets. The facade calls this for you; reach for it directly only if you need archive-specific operations like iter_judgments (bulk streaming) or prefetch_sci_year (pre-warming).

Choosing the right tool

For "find a judgment" — always start with Judgments.find(). It handles the common cases and routes correctly. Only drop down to the portal clients for what they uniquely offer.

Freshness gap: the archive updates bi-monthly (SCI) and quarterly (HC). Anything decided in the last 2–3 months may not be there yet. If find() with structured filters returns nothing for a recent year, re-try with source="live" or fall back to the live clients, and tell the user about the gap.

Installation

pip install bharat-courts[ocr]       # RECOMMENDED — ddddocr CAPTCHA solving, no auth needed
pip install bharat-courts[archive]   # historical archive support (DuckDB)
pip install bharat-courts[onnx]      # ONNX CAPTCHA model — requires HF_TOKEN
pip install bharat-courts[all]       # everything

For the federated Judgments facade, install both [archive] and [ocr] so it can use either backend.

Quick Start — Federated find (the default)

import asyncio
from bharat_courts import Judgments


async def main():
    async with Judgments() as j:
        # 1. Structured filters → archive (no CAPTCHA, partition-pruned)
        for r in await j.find(judge="chandrachud", year=(2018, 2024), court="sci", limit=10):
            print(f"{r.decision_date}  {r.case_id}  {r.title}")

        # 2. Free-text → live (only it does full-body search)
        for r in await j.find(text="right to privacy", limit=5):
            print(f"{r.decision_date}  {r.title}  [{r.source}]")

        # 3. CNR alone — prefix routes to the right bucket, instant
        result = await j.find(cnr="DLHC010230802020")
        if result:
            pdf_bytes = await j.fetch_pdf(result[0])
            with open("judgment.pdf", "wb") as f:
                f.write(pdf_bytes)

        # 4. Force a backend if you need to (e.g. only-live for recent cases)
        recent = await j.find(text="bail", source="live", limit=5)


asyncio.run(main())

Routing decisions (auto mode):

Each returned Judgment carries .source = "archive" or "live" so you can tell where it came from.

fetch_pdf(judgment_or_cnr) works for archive judgments and for CNR strings whose prefix maps to a known court. For live Judgment objects it raises NotImplementedError — the live PDF download needs the original JudgmentResult instance (for session continuity); use JudgmentSearchClient.download_pdf(judgment_result, court_type) directly in that case.

Quick Start — High Courts

import asyncio
from bharat_courts import get_court, HCServicesClient
from bharat_courts.captcha.ocr import OCRCaptchaSolver


async def main():
    court = get_court("delhi")  # or "bombay", "calcutta", etc.
    solver = OCRCaptchaSolver()

    async with HCServicesClient(captcha_solver=solver) as client:
        # Search by party name (year is mandatory)
        cases = await client.case_status_by_party(court, party_name="state", year="2024")

        # Search by case number
        cases = await client.case_status(court, case_type="134", case_number="1", year="2024")

        # Get cause list PDFs
        pdfs = await client.cause_list(court, civil=True)

        # Get court orders
        orders = await client.court_orders(court, case_type="134", case_number="1", year="2024")

        # List benches and case types (no CAPTCHA needed)
        benches = await client.list_benches(court)
        case_types = await client.list_case_types(court)


asyncio.run(main())

Quick Start — District Courts

District courts use a 4-level hierarchy: State → District → Court Complex → Establishment. Discover courts dynamically, then search.

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
        states = await client.list_states()  # {"8": "Bihar", "7": "Delhi", ...}
        districts = await client.list_districts("8")  # {"1": "Patna", "35": "Gaya", ...}
        complexes = await client.list_complexes(
            "8", "1"
        )  # {"1080010@2,3,4@Y": "Civil Court, Patna Sadar", ...}

        # 2. Parse the complex value to get the code and check if establishment is needed
        complex_val = list(complexes.keys())[0]
        complex_code, est_codes, needs_est = parse_complex_value(complex_val)
        est_code = est_codes[0] if needs_est else ""

        # 3. List case types (no CAPTCHA)
        case_types = await client.list_case_types("8", "1", complex_code, est_code)

        # 4. Search by party name (CAPTCHA auto-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 case in cases:
            print(f"{case.case_number}: {case.petitioner} vs {case.respondent}")

        # 5. Search by case number
        cases = 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 court orders
        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",
        )

        # 7. Get cause list
        entries = await client.cause_list(
            state_code="8",
            dist_code="1",
            court_complex_code=complex_code,
            est_code=est_code,
            civil=True,
        )


asyncio.run(main())

Judgment Search Portal

Search High Court judgments by keyword on judgments.ecourts.gov.in.

from bharat_courts import JudgmentSearchClient
from bharat_courts.captcha.ocr import OCRCaptchaSolver


async def main():
    solver = OCRCaptchaSolver()

    async with JudgmentSearchClient(captcha_solver=solver) as client:
        # Single page search
        result = await client.search("right to privacy", search_opt="ALL", court_type="2")
        for j in result.items:
            print(f"{j.title} — {j.judgment_date}")

        # Paginate through all results
        async for page in client.search_all("right to privacy", search_opt="ALL"):
            for j in page.items:
                print(j.title)

        # Download PDFs
        result = await client.search("constitution")
        result.items = [await client.download_pdf(j) for j in result.items]

        # Batch download with automatic session reset every 25 downloads
        judgments = await client.download_pdfs(result.items, batch_size=25)


asyncio.run(main())

Calcutta High Court (Direct)

Search orders/judgments directly on calcuttahighcourt.gov.in — has better PDF coverage than eCourts for Calcutta HC cases from September 2020 onwards.

from bharat_courts import CalcuttaHCClient


async def main():
    async with CalcuttaHCClient() as client:
        # Search by case number
        orders = await client.search_orders(
            case_type="12",  # WPA
            case_number="12886",
            year="2024",
            establishment="appellate",  # or "original", "jalpaiguri", "portblair"
        )
        for order in orders:
            print(f"{order.order_date} | {order.judge} | {order.neutral_citation}")
            if order.pdf_url:
                pdf = await client.download_order_pdf(order.pdf_url)


asyncio.run(main())

CalcuttaHCClient Methods

establishment values: "appellate", "original", "jalpaiguri", "portblair".

Quick Start — Historical Archive (AWS Open Data)

ArchiveClient reads the public S3 buckets maintained by Dattam Labs — SCI judgments from 1950 and 25 HCs, all CC-BY-4.0. No CAPTCHA, no rate limits, no AWS account needed. Requires pip install bharat-courts[archive].

Use the archive whenever the user wants historical research, bulk PDF retrieval, or a judgment with a known CNR. For "current status" / "next hearing" / "cause list" questions, use the live clients above.

from bharat_courts import ArchiveClient


async def main():
    async with ArchiveClient() as client:
        # 1. Search by judge + year range (partition-pruned in DuckDB)
        results = await client.search(
            court="sci",
            judge="chandrachud",
            year=(2018, 2024),
            limit=20,
        )
        for j in results:
            print(f"{j.decision_date}  {j.case_id}  {j.title}")
            print(f"  {j.citation}  outcome: {j.disposal_nature}")

        # 2. CNR lookup — court is auto-inferred from the 4-letter CNR prefix
        results = await client.search(cnr="DLHC010230802020")

        # 3. Bulk streaming — get every Delhi 2020 judgment without huge limits
        count = 0
        async for j in client.iter_judgments(court="delhi", year=2020, batch_size=500):
            count += 1
            # process(j)

        # 4. Fetch the PDF — pass a CNR string or a Judgment
        pdf_bytes = await client.fetch_pdf("DLHC010230802020")
        with open("judgment.pdf", "wb") as f:
            f.write(pdf_bytes)

        # 5. SCI supports regional-language PDFs
        hindi = await client.fetch_pdf("ESCR010000301950", language="hindi")


asyncio.run(main())

ArchiveClient Methods

ArchiveClient gotchas to communicate to the user

• Freshness: SCI updates bi-monthly, HC quarterly. For a case decided last month, try the live JudgmentSearchClient or HCServicesClient first.
• No party search on HC: HC parquet doesn't have separate petitioner/respondent columns. party= matches against the title only for HC. SCI works as expected.
• No citation search on HC: same reason — citation= is silently ignored for HC.
• PDF cache lives on disk at ~/.cache/bharat-courts/archive/ (5 GiB cap by default; override with BHARAT_COURTS_ARCHIVE_CACHE_MAX_GB). First SCI fetch in a year downloads a ~40–500 MB tar; subsequent fetches in the same year are essentially free.
• License: CC-BY-4.0 — when redistributing, attribute Dattam Labs / eCourts.

Judgments facade methods (use this first)

CNR-prefix helper

bharat_courts.infer_court_from_cnr(cnr) resolves a CNR's first 4 letters to a Court. Use it if you're routing CNRs across both live and archive clients yourself.

from bharat_courts import infer_court_from_cnr

infer_court_from_cnr("DLHC010230802020")  # → Court(code="delhi")
infer_court_from_cnr("ESCR010000301950")  # → SUPREME_COURT
infer_court_from_cnr("HCBM020056322016")  # → Bombay (note: legacy prefix)
infer_court_from_cnr("WBCHCJ0008142019")  # → Calcutta
infer_court_from_cnr("garbage")  # → None (never raises)

Available High Courts

Use get_court(code) with any of these codes:

HCServicesClient Methods

JudgmentSearchClient Methods

search_opt values: "PHRASE" (exact phrase), "ANY" (any word), "ALL" (all words). court_type values: "2" (High Courts), "3" (Supreme Court Reports).

DistrictCourtClient Methods

All search methods require state_code, dist_code, court_complex_code, and est_code (use the discovery methods to find these).

Use parse_complex_value(value) from bharat_courts.districtcourts.parser to extract (complex_code, est_codes, needs_establishment) from the complex dropdown values.

Data Models

All models support to_dict() and to_json() for serialization.

• CaseInfo: case_number, case_type, cnr_number, filing_number, registration_number, registration_date, petitioner, respondent, status, court_name, judges, next_hearing_date
• CaseOrder: order_date, order_type, judge, pdf_url, pdf_bytes, order_text
• CauseListPDF: serial_number, bench, cause_list_type, pdf_url (HC Services — one PDF per bench)
• CauseListEntry: serial_number, case_number, case_type, petitioner, respondent, advocate_petitioner, advocate_respondent, court_number, judge, listing_date, item_number (District Courts — structured entries)
• JudgmentResult: title, court_name, case_number, judgment_date, judges, pdf_url, pdf_bytes, citation, bench_type, source_url, source_id, metadata (used by JudgmentSearchClient / SCIClient)
• Judgment: cnr, case_id, title, court (resolved Court), court_name_raw, bench, court_code, judges, author_judge, decision_date, date_of_registration, petitioner, respondent, citation, disposal_nature, description, pdf_path, available_languages, pdf_exists, source, year (used by ArchiveClient — unified across SCI + HC schemas; fields not applicable to a given source are None)
• SearchResult: items, total_count, page, page_size, has_next, total_pages (paginated container)

CAPTCHA Handling

Both HC Services and District Courts use Securimage CAPTCHAs. Two auto-solvers are available:

# Option 1: ddddocr (pip install bharat-courts[ocr])
from bharat_courts.captcha.ocr import OCRCaptchaSolver

solver = OCRCaptchaSolver()  # ~60% accuracy, auto-retry with fresh sessions

# Option 2: ONNX model (pip install bharat-courts[onnx])
# REQUIRES HF_TOKEN env var — the model is downloaded from HuggingFace
# Get a token at https://huggingface.co/settings/tokens
# export HF_TOKEN=hf_...
from bharat_courts.captcha.onnx import ONNXCaptchaSolver

solver = ONNXCaptchaSolver()  # lighter, uses onnxruntime, needs HF auth

# Option 3: Manual input
from bharat_courts.captcha.manual import ManualCaptchaSolver

solver = ManualCaptchaSolver()  # prompts on stdin

# Option 4: Custom solver
from bharat_courts.captcha.base import CaptchaSolver


class MySolver(CaptchaSolver):
    async def solve(self, image_bytes: bytes) -> str:
        return "solved_text"

Important Notes

• All methods are async — use asyncio.run() or await
• Default CAPTCHA solver is OCRCaptchaSolver (ddddocr) — no explicit solver needed if bharat-courts[ocr] is installed. Clients auto-detect the best available solver.
• ONNXCaptchaSolver requires HF_TOKEN — the ONNX model is hosted on HuggingFace which requires authentication. Set export HF_TOKEN=hf_... before use. Prefer OCRCaptchaSolver unless you have a specific reason to use ONNX.
• CAPTCHA is pinned to PHP session — the library creates fresh sessions on each retry automatically
• year is mandatory for party name search (server returns ERROR_VAL if empty)
• Case type codes are numeric and vary by court — discover via list_case_types()
• Rate limiting is built in (default 1 second between requests)
• District courts require dynamic court discovery (state → district → complex → establishment) unlike High Courts which use static get_court() codes
• JudgmentSearchClient only supports keyword search — there is no search by party name, CNR, or case number on the judgments portal
• Some order PDFs may not be uploaded on eCourts even when the case exists — court_orders() will return the URL but the PDF download may return an error from the server
• Default to Judgments.find() for judgment searches. It picks archive vs live for you based on the query — no need to reason about which to call. Use the portal-specific clients only when you need their portal-only features (cause lists, case status, district drill-down).
• Archive freshness gap: ArchiveClient data lags by 2–3 months (SCI bi-monthly, HC quarterly). When a user asks about a recent judgment and the facade's archive route returns nothing, retry with source="live" or fall back to JudgmentSearchClient / HCServicesClient, and mention the freshness gap.
• Prefer archive over live for historical / bulk queries: live judgment search is CAPTCHA-gated and rate-limited; archive iter_judgments can stream tens of thousands of judgments in seconds with no portal load.
• Archive PDFs cache on disk: first SCI PDF in a year triggers a 40–500 MB tar download. Subsequent fetches in that year are essentially free. Warn the user before kicking off many SCI fetches across many years.