Historical Archive (ArchiveClient)¶

ArchiveClient reads two public AWS Open Data S3 buckets directly with DuckDB. It is the engine behind every historical and bulk query in bharat-courts: no CAPTCHA, no rate limits, and no AWS account required.

Reach for the archive when the user wants historical research, bulk PDF retrieval, or a judgment with a known CNR. For current state — case status, next hearing, cause lists, orders just uploaded — use the live clients instead (see High Courts and Judgment Search).

The data¶

Both buckets live in ap-south-1, are licensed CC-BY-4.0, and are maintained by Dattam Labs. Because the data is public, anonymous S3 access is used — you do not need credentials.

See Data sources for the full provenance and attribution details.

Installation¶

The archive is an opt-in extra (it pulls in DuckDB):

pip install "bharat-courts[archive]"

Quick start¶

import asyncio
from bharat_courts import ArchiveClient

async def main():
    async with ArchiveClient() as client:
        # 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}")

asyncio.run(main())

Every row comes back as a unified Judgment with .source = "archive", so it interoperates with results from the live clients and the facade.

Method reference¶

Shared filter arguments¶

search, iter_judgments, and count share the same filter vocabulary:

Worked examples¶

Judge + year-range search¶

async with ArchiveClient() as client:
    results = await client.search(
        court="delhi", judge="hari shankar", year=(2019, 2021), limit=25,
    )
    for j in results:
        print(j.decision_date, j.case_id, j.title)

CNR lookup (court auto-inferred)¶

You do not need to pass court when you have a CNR — the first four letters of the CNR identify the bucket and partition, so the lookup is instant and avoids scanning all 25 HC partitions.

async with ArchiveClient() as client:
    results = await client.search(cnr="DLHC010230802020")   # → Delhi HC
    sci = await client.search(cnr="ESCR010000301950")       # → Supreme Court

Bulk streaming with iter_judgments¶

For large pulls — "every Delhi 2020 judgment" is roughly 18,000 rows — stream instead of using a huge limit. Pages are fetched via LIMIT/OFFSET, so you start consuming results immediately and never hold the full set in memory.

async with ArchiveClient() as client:
    count = 0
    async for j in client.iter_judgments(court="delhi", year=2020, batch_size=500):
        count += 1
        # process(j) — write to a file, index, etc.
    print(f"Streamed {count} judgments")

Sources stream sequentially (SCI first, then HC) and each source is internally sorted by decision_date DESC, cnr, so individual pages are deterministic. There is no cross-source date merge across SCI and HC in streaming mode. Use max_results=N to cap the total yielded across sources.

Fetch a PDF to disk¶

fetch_pdf accepts either a Judgment (preferred — no extra lookup) or a CNR string (which triggers one metadata query first).

async with ArchiveClient() as client:
    pdf_bytes = await client.fetch_pdf("DLHC010230802020")
    with open("judgment.pdf", "wb") as f:
        f.write(pdf_bytes)

Regional-language SCI PDF¶

The Supreme Court archive carries regional-language renderings. The language argument is only meaningful for SCI — HC PDFs in the archive are English-only.

async with ArchiveClient() as client:
    hindi = await client.fetch_pdf("ESCR010000301950", language="hindi")
    # other values: "tamil", "gujarati", … (see SCI_LANGUAGE_MAP)

Pre-warm a year before a batch¶

If you are about to fetch many SCI PDFs from the same year, warm the tar once so the per-PDF fetches are cheap:

async with ArchiveClient() as client:
    local_tar = await client.prefetch_sci_year(2020)
    print("warmed:", local_tar)
    # subsequent fetch_pdf(...) calls for 2020 read from this tar

Sizing a query with count¶

async with ArchiveClient() as client:
    print(await client.count(court="delhi", year=2020))  # {"hc": 18000}
    print(await client.count(year=2020))                 # {"sci": ..., "hc": ...}

Gotchas¶

See also¶

• API reference: ArchiveClient — full signatures and types.
• The Judgments facade — the recommended default that routes between archive and live for you.
• Data sources — bucket provenance, licence, and update cadence.