bhoonidhi-downloader

CLI and Python SDK for ISRO's Bhoonidhi Browse & Order portal (NRSC) — programmatic search and download of satellite imagery from Indian satellite missions (ResourceSat, NISAR, CartoSat, EOS, and more) alongside international Earth-observation / remote-sensing data (Sentinel, Landsat). It reaches the portal's full archive of 41 satellite missions and 79 sensors — see the supported missions.

Find scenes over an area and date range, keep your searches to come back to them later and refresh them to fetch new scenes for the time diff only. Scenes that need ordering or payment are staged to the Bhoonidhi cart to finish on the portal. Everything the bhd command does is also a method on the Python SDK, for scripting and pipelines.

Features

• Search by bounding box or point + radius — filter by satellite, sensor, and date range. --sat is repeatable and accepts SAT[:SEN[:PROD]], so one search can span several missions or narrow to a single product within a sensor.
• 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 automatically while it's still within Bhoonidhi's refresh window; re-enter credentials only once that window has closed.
• Scriptable — every command has a matching method on BhoonidhiClient, so you can drive searches and downloads from a Python script or notebook for programmatically accessing the entire archive.

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; waits for email OTP if the portal sends one)
bhd auth login

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

# 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.

Prefer a point and radius over a bounding box? Swap --minx/--maxx/--miny/--maxy for --lat/--lon/--radius (radius defaults to 10km, 1-100km):

bhd query create 2025-12-01 2025-12-30 --sat Sentinel-2A:MSI --lat 25.58 --lon 91.89 --radius 15

--sat is repeatable and accepts SAT[:SEN[:PROD]] — combine several missions in one search, or narrow to a single product within a sensor:

# Two missions in one search
bhd query create 2025-12-01 2025-12-30 --sat ResourceSat-2A:LISS3 --sat CartoSat-3 --minx 91.77 --maxx 92 --miny 25.496 --maxy 25.695

# One product within a sensor (quote it — the parentheses matter to the shell)
bhd query create 2025-12-01 2025-12-30 --sat "EOS-06:OCM(GAC):L2C-Chlorophyll" --minx 74 --maxx 80 --miny 12 --maxy 18

An unknown satellite, sensor, or product is skipped with a warning instead of failing the whole search; run bhd archive list --sat X first to see what's valid.

Every search is saved by default. For a one-off search — or a scripted/multi-worker run where you don't want query files piling up on disk — add --no-save: the scenes still print (and the SDK still returns them), but nothing is written under ~/.bhoonidhi/queries/ and no slug is generated:

bhd query create 2025-12-01 2025-12-30 --sat Sentinel-2A:MSI --minx 91.77 --maxx 92 --miny 25.496 --maxy 25.695 --no-save

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()
# otp_prompt is only called if the account needs a mailed OTP; a
# password-only account logs in without it being invoked.
client.login("my-username", "my-password", otp_prompt=lambda msg: input("OTP: "))

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

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

Already have the OTP in hand, or scripting a password-only account? Pass otp="123456" instead of otp_prompt for non-interactive use.

Search several missions or narrow to one product with selections instead of satellite/sensor:

from bhoonidhi_downloader.sdk import Selection

query = client.query.create(
    datetime(2025, 12, 1), datetime(2025, 12, 30),
    selections=[
        Selection(satellite="ResourceSat-2A", sensor="LISS3"),
        Selection(satellite="CartoSat-3"),
    ],
    minx=91.77, maxx=92.0, miny=25.496, maxy=25.695,
)

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 or point + radius (up to 100km) — no shapefile-based search from CLI  - easy enough using SDK with geopandas or shapely to work around that.
• 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.

Data usage and attribution

The imagery this tool downloads belongs to ISRO/NRSC and is governed by Bhoonidhi EULA, not by this project's MIT license — that license covers the code here, nothing else. What the EULA asks of you:

• Use your own account. Every download authenticates with your own Bhoonidhi login. You register and log in as yourself; the tool never shares or bypasses a session.
• Credit the source. Anything you publish from this data must carry the caption ISRO-IRS.
• Don't resell the raw data. Scenes the portal marks as open data are free to use, publish, and build on. The original products just can't be redistributed commercially in their original form — derived and value-added products are fine.
• Priced and on-order scenes go through the portal. This tool never bypasses payment: priced and on-order scenes are only staged to the cart, and you complete any order and payment on Bhoonidhi.

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