Search live judgment text¶

Use JudgmentSearchClient for the judgment portal's text search, pagination and session-aware PDF retrieval. The archive searches metadata instead of judgment bodies.

Search and retrieve a PDF¶

Install bharat-judgements[ocr] for automatic CAPTCHA solving. This example requests one page of High Court results and downloads the first result only if one exists.

import asyncio
from pathlib import Path
from bharat_judgements import JudgmentSearchClient


async def main():
    async with JudgmentSearchClient() as client:
        results = await client.search(
            "right to privacy", page=1, page_size=10, search_opt="PHRASE", court_type="2"
        )
        print("Portal total:", results.total_count)
        for record in results.items:
            print(record.title, record.judgment_date, record.source_id)
        if results.items:
            record = await client.download_pdf(results.items[0], court_type="2")
            if record.pdf_bytes is not None:
                Path("judgment.pdf").write_bytes(record.pdf_bytes)


asyncio.run(main())

judgment.pdf is overwritten if it already exists. Keep downloads inside the same client context: the portal's PDF resolution uses session state and the original JudgmentResult.

Choose the query shape¶

The search returns SearchResult with items and portal pagination metadata. A successful empty result differs from CaptchaError, which reports that authentication failed.

Walk through pages¶

search_all is an async iterator that yields one SearchResult per page and re-authenticates when needed. It can produce many results, so set application-level limits and save progress for long runs. Do not claim an exhaustive corpus from a single page.

The facade's text path uses the default High Court search and requests only one page, with at most 25 rows. Use this direct client for SCR searches or pagination.

Download semantics¶

download_pdf(record, court_type=...) fills record.pdf_bytes and returns that record. It resolves the portal's encrypted path for the current session and validates PDF bytes. Use the same court_type as the search.

Judgments.fetch_pdf cannot download a mapped live Judgment, because it lacks the original result's session metadata. Keep the direct result for this operation.

CLI examples¶

Install cli as well, then run:

bharat-judgements --json judgments search --text "right to privacy" --page 1 --page-size 10
bharat-judgements --json judgments search --text bail --court-type 3 --page-size 10
bharat-judgements judgments search-all --text "section 498A" --max-pages 2 --download judgments

The last command downloads available PDFs and bounds the page walk. Review the CLI guide for global options and output shapes.

Next: live client API, query routing, or Supreme Court sources.