bhoonidhi-downloader

A CLI for searching, saving, and downloading satellite imagery from ISRO's Bhoonidhi Earth Observation Portal. Every command is also callable from Python through the bhoonidhi_downloader.sdk package — a single BhoonidhiClient that mirrors the CLI one-to-one.

Features

• Search by bounding box — filter by satellite, sensor, and date range.
• Named, persistent queries — every search is saved under a short slug (misty-falcon), so you can come back to it later, refresh it for new scenes, or download from it without re-querying the portal.
• Concurrent, verified downloads — fetches multiple scenes in parallel, verifies each with a SHA256, and skips anything already downloaded.
• Cart staging — stage scenes into the Bhoonidhi cart from a saved query — priced, on-order, open-but-archived, or direct-download — and finish the order in the Browse & Order portal.
• Browse the archive — list every satellite/sensor Bhoonidhi currently supports, live from the portal.
• Session management — login once, refresh your token when it goes stale, no need to keep re-entering credentials.
• Scriptable — every command has a matching method on BhoonidhiClient, so you can drive searches and downloads from a Python script or notebook instead of shelling out.

Installation

pip install bhoonidhi-downloader

This installs two equivalent commands — bhoonidhi-downloader and the shorter bhd. They're the same tool; use whichever you'd rather type.

Quickstart

Log in, run a search, and download what you find — three commands, start to finish:

# 1. Authenticate (prompts for username/password if omitted)
bhd auth login

# 2. Search a bounding box + date range, save the results as a named query
bhd query create 91.77 92 25.496 25.695 2025-12-01 2025-12-30 --sat Sentinel-2A --sen MSI

# 3. Download everything the query found
bhd query download misty-falcon --out ./downloads

query create prints the scenes it found in a table and tells you what slug it saved them under (here, misty-falcon — yours will be different). You don't have to download right away: come back anytime with bhd query show misty-falcon, or bhd query refresh misty-falcon to check for newly published scenes in the same area.

Command reference

Every command supports --help for its full option list. This is the short version; see the API Reference for the underlying functions this calls into.

auth — session management

archive — browse what's available

query — search, save, and download

cart — stage scenes to the Bhoonidhi cart

For scenes that query download can't fetch directly — priced, on-order, or open-but-archived — add them to the Bhoonidhi cart from a saved query, then finish the order in the Browse & Order portal. Direct-download scenes can be downloaded with query download or staged to the cart; every access type routes automatically to the portal's direct-download, on-order, or priced cart based on its access type.

Calling it from Python

Every command shown above is also available from Python through the BhoonidhiClient — same behaviour, no subprocess. This is the way to script bulk ingestion or wire Bhoonidhi into a pipeline:

from datetime import datetime

from bhoonidhi_downloader.sdk import BhoonidhiClient

client = BhoonidhiClient()
client.login("my-username", "my-password")

query = client.query.create(
    91.77, 92.0, 25.496, 25.695,
    datetime(2025, 12, 1), datetime(2025, 12, 30),
    satellite="Sentinel-2A", sensor="MSI",
)

client.query.download(query.slug, "./downloads")

See the Python SDK guide for the full walkthrough, the API Reference for every method, and the notebook examples for runnable worksheets.

What's actually downloadable

Every scene is searchable and shows up in results. Scenes marked OpenData_DirectDownload can be pulled straight to disk with query download. The other access types — priced, on-order, and open-but-archived — can't be fetched directly by the CLI, but all of them, including the direct-download ones, can be staged with bhd cart add and finished in the Browse & Order portal. So the cart is a single collection path for every scene regardless of access type; query download is just the shortcut for the subset that's immediately fetchable.

The satellite/sensor list itself isn't hardcoded anywhere in this tool — bhd archive list fetches it live from the portal every time, so it's always current. Run it to see exactly what's searchable today rather than relying on a list here that would just go stale.

A couple of Bhoonidhi-specific quirks worth knowing about going in:

• No resumable downloads. The portal doesn't honor HTTP Range requests, so an interrupted download restarts from byte 0 rather than picking up where it left off. query download reports this explicitly (↺ restarted from scratch) when it happens.
• Already have it somewhere else? query download checks if a scene's already downloaded and SHA-verified in a different folder before re-fetching it — if it finds one, it'll tell you and ask before wasting bandwidth. --force skips the check and downloads anyway.

Limitations

• Search is bounding-box only — no point-coordinate or shapefile-based search yet.
• query download fetches only OpenData_DirectDownload scenes; priced, on-order, and archived scenes aren't fetched directly. Every access type — including direct-download scenes — can also be staged with bhd cart add.
• Cart support stages scenes only. Placing the order — and any payment for priced data — is finished in the Browse & Order portal; there's no order-placement step in the CLI.

Development

git clone https://github.com/geovicco-dev/bhoonidhi-downloader.git
cd bhoonidhi-downloader
uv sync --group dev

Before committing, run the same checks CI runs:

uv run ruff check src/
uv run ruff format --check src/

Changelog

See CHANGELOG.md for what's changed release to release.

License

MIT