Run your first query¶

Start with a bounded historical search. Judgments routes the query and returns a list of Judgment objects with source metadata.

01 / Install archive support¶

python -m pip install "bharat-judgements[archive,cli]"

For live text searches, also install ocr or provide manual CAPTCHA input. See installation.

02 / Search historical judgments¶

Save this complete example as first_query.py and run python first_query.py. It needs network access but no archive credentials.

import asyncio
from bharat_judgements import Judgments


async def main():
    async with Judgments() as judgments:
        records = await judgments.find(
            court="sci", judge="chandrachud", year=(2018, 2024), limit=10
        )
        print(f"Returned {len(records)} records")
        for record in records:
            print(record.decision_date, record.case_id, record.title, record.source)


asyncio.run(main())

No result count or case outcome is assumed. Dates and identifiers may be missing. The archive can lag court publication.

03 / Understand routing¶

Filters in automatic mode	Source	Meaning
`cnr`	Archive	Historical judgment lookup; not a live case-status lookup
`text` alone	Live	One page of High Court judgment text search
Court, year, judge, party or citation	Archive	Structured metadata search
`text` plus structured filters	Archive	Text becomes a party/title match unless `party` is supplied
No filters	Error	`ValueError` asks for at least one filter

There is no automatic fallback when a source returns nothing. source="live" requires text and does not apply structured filters. Read the facade guide before combining these options.

Use the command line¶

bharat-judgements --json find --court sci --judge chandrachud --year 2018-2024 --limit 10

Global options such as --json go before the subcommand. The output is metadata; it does not contain the full judgment text.

Retrieve a PDF¶

Use fetch_pdf(record) on an archive result, or fetch_pdf(cnr) for a CNR resolving to a supported archive record. The first Supreme Court PDF retrieval for a year can download a large tar file. See archive retrieval.

For a live Judgment, fetch_pdf raises NotImplementedError. Use the direct judgment client and retain its original JudgmentResult for downloads.

Next: query routing, live High Court records, or API reference.