Judgment Search Portal¶

JudgmentSearchClient is the live client for judgments.ecourts.gov.in — the official eCourts portal that does full-text keyword search over High Court (and Supreme Court Reports) judgments. Give it a phrase or set of words and it returns matching judgments, each with a downloadable PDF.

This is the only backend in bharat-courts that searches the body of a judgment. The historical archive can match on title and structured fields, but not on the words inside the text — so when a user says "find me judgments that mention X", this is the portal that can answer it.

How it works¶

The portal is CAPTCHA-gated. The client handles the whole dance for you:

1. Establishes a session.
2. Fetches the CAPTCHA image and solves it with the configured solver.
3. Validates the CAPTCHA, receiving an app_token that must be echoed on every subsequent request.
4. Runs the search (a DataTables AJAX call) and parses the result rows.
5. For each downloaded PDF, exchanges the row's path for a per-session download URL, then fetches the bytes.

The session token rotates on every call and the client tracks it automatically. If the session expires mid-pagination, search_all() re-authenticates and continues.

Method reference¶

search_opt values¶

court_type values¶

What you get back¶

search() and each page from search_all() return a SearchResult:

Each JudgmentResult carries title, court_name, case_number, judgment_date, judges, citation, pdf_url, pdf_bytes, source_url, source_id, and a metadata dict. After download_pdf(), pdf_bytes holds the PDF.

Single-page search¶

import asyncio
from bharat_courts import JudgmentSearchClient

async def main():
    async with JudgmentSearchClient() as client:
        result = await client.search(
            "right to privacy",
            search_opt="ALL",   # match all of the words
            court_type="2",     # High Courts
            page_size=25,
        )
        print(f"{result.total_count} matches; showing {len(result.items)}")
        for j in result.items:
            print(f"{j.judgment_date}  {j.court_name}  {j.title}")

asyncio.run(main())

Paginate through every result¶

search_all() is an async generator that yields one SearchResult per page and stops when there are no more rows. It transparently re-authenticates if the portal session expires during a long walk.

import asyncio
from bharat_courts import JudgmentSearchClient

async def main():
    async with JudgmentSearchClient() as client:
        all_items = []
        async for page in client.search_all(
            "compassionate appointment",
            search_opt="PHRASE",
            page_size=50,
        ):
            print(f"page {page.page}/{page.total_pages}  (+{len(page.items)})")
            all_items.extend(page.items)
        print(f"collected {len(all_items)} judgments")

asyncio.run(main())

Download PDFs¶

download_pdf() mutates the JudgmentResult in place, setting pdf_bytes. The row's pdf_url is a portal-internal path, not a directly fetchable URL — the client resolves it through the portal's download endpoint for you.

import asyncio
from bharat_courts import JudgmentSearchClient

async def main():
    async with JudgmentSearchClient() as client:
        result = await client.search("medical negligence", search_opt="PHRASE")

        # One PDF
        first = await client.download_pdf(result.items[0])
        with open("judgment.pdf", "wb") as f:
            f.write(first.pdf_bytes)

asyncio.run(main())

Batch download¶

download_pdfs() downloads PDFs for a list of results. It skips any result that already has pdf_bytes, and by default logs failures and keeps going (set stop_on_error=True to raise on the first failure instead).

import asyncio
from bharat_courts import JudgmentSearchClient

async def main():
    async with JudgmentSearchClient() as client:
        result = await client.search("anticipatory bail", page_size=25)

        downloaded = await client.download_pdfs(result.items)
        for j in downloaded:
            if j.pdf_bytes is not None:
                print(f"{len(j.pdf_bytes):>8} bytes  {j.title}")
            else:
                print(f"   (no PDF)  {j.title}")

asyncio.run(main())

Errors¶

search() and search_all() raise CaptchaError if the solver cannot produce a valid CAPTCHA within max_captcha_attempts tries. An empty SearchResult is distinct from a failure: it means the portal genuinely returned zero matching rows.

from bharat_courts.hcservices.parser import CaptchaError

try:
    result = await client.search("some rare phrase")
except CaptchaError:
    print("Could not get past the CAPTCHA; try again or use a different solver.")

See also¶

• Judgments facade — the recommended entry point for judgment lookups; routes free-text queries here for you.
• Historical archive — faster for bulk / historical pulls, but matches on title and structured fields, not full text.
• CAPTCHA handling — solvers used by all live clients.
• Clients API reference — full signatures.