Query

Reachable as client.query. Run searches and manage saved queries. create, refresh, and download reach the portal; the rest work on the local query store.

from datetime import datetime

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")

QueryNamespace

QueryNamespace(client: BhoonidhiClient)

The query commands, reachable as client.query.

Methods:

Name	Description
`create`	Search an AOI + date range, returning the matching scenes.
`list`	Return every saved query. Mirrors `bhd query list`.
`show`	Return a saved query by slug. Mirrors `bhd query show`.
`rename`	Update a query's name/description. Mirrors `bhd query rename`.
`fork`	Clone a query under a new slug. Mirrors `bhd query fork`.
`refresh`	Re-query for newer scenes. Mirrors `bhd query refresh`.
`rm`	Delete a saved query. Mirrors `bhd query rm`.
`download`	Download a query's open-access scenes to `out`.

create

create(
    start_date: datetime,
    end_date: datetime,
    satellite: str | None = None,
    minx: float | None = None,
    maxx: float | None = None,
    miny: float | None = None,
    maxy: float | None = None,
    sensor: str | None = None,
    lat: float | None = None,
    lon: float | None = None,
    radius_km: float | None = None,
    name: str | None = None,
    description: str | None = None,
    selections: list[Selection] | None = None,
    save: bool = True,
) -> QuerySchema | None

Search an AOI + date range, returning the matching scenes.

The AOI is either a bounding box (minx/maxx/miny/maxy) or a point plus radius (lat/lon/radius_km) — give exactly one of the two.

Targets are given as selections — a list of :class:~bhoonidhi_downloader.schemas.Selection, each naming a satellite and optionally a sensor and product. The legacy satellite + sensor scalar pair is still accepted for a single-mission search and is folded into a one-element selections list; giving both is an error.

By default (save=True) the result is persisted as a named query under ~/.bhoonidhi/queries/ and the returned query carries its slug. Pass save=False for a stateless search: the search runs identically but nothing is written to disk and no slug is generated — the returned query is ephemeral, with .scenes populated, for callers that only want the scene list.

Returns the query, or None if nothing matched. Mirrors bhd query create.

list

list() -> list[QuerySchema]

Return every saved query. Mirrors bhd query list.

show

show(slug: str) -> QuerySchema

Return a saved query by slug. Mirrors bhd query show.

Raises BhoonidhiNotFoundError if the slug is unknown.

rename

rename(
    slug: str,
    name: str | None = None,
    description: str | None = None,
) -> QuerySchema

Update a query's name/description. Mirrors bhd query rename.

fork

fork(slug: str, name: str | None = None) -> QuerySchema

Clone a query under a new slug. Mirrors bhd query fork.

refresh

refresh(slug: str) -> tuple[QuerySchema, int | None]

Re-query for newer scenes. Mirrors bhd query refresh.

Returns (query, added_count); added_count is None if the query was already up to date.

rm

rm(slug: str) -> None

Delete a saved query. Mirrors bhd query rm.

Raises BhoonidhiNotFoundError if the slug is unknown.

download

download(
    slug: str,
    out: str,
    select: list[int | str] | None = None,
    parallel: int = 4,
    force: bool = False,
    on_progress: Callable[[str, int, int | None], None]
    | None = None,
) -> list[DownloadOutcome]

Download a query's open-access scenes to out.

Mirrors bhd query download. Uses the client's held session — log in first. Priced/on-order scenes are skipped; on_progress is called with (scene_id, bytes_so_far, total_bytes) as data arrives.

select narrows the download to specific scenes: an int is a 1-based index into the query, a str is a full scene ID. Omit it to download the whole query. Example: select=[1, 2, 3].

Raises:

Type	Description
`BhoonidhiAuthError`	if the client isn't authenticated.
`BhoonidhiNotFoundError`	if the slug is unknown.
`BhoonidhiValidationError`	if a `select` entry isn't a plain index or scene ID.

Download result

download returns a list of DownloadOutcome, one per scene.

DownloadOutcome

DownloadOutcome(
    scene_id: str,
    status: str,
    path: str | None = None,
    sha256: str | None = None,
    bytes_downloaded: int = 0,
    error: str | None = None,
    restarted_bytes: int = 0,
)

DownloadOutcome(scene_id: 'str', status: 'str', path: 'str | None' = None, sha256: 'str | None' = None, bytes_downloaded: 'int' = 0, error: 'str | None' = None, restarted_bytes: 'int' = 0)

Attributes:

Name	Type	Description
`bytes_downloaded`		int([x]) -> integer
`restarted_bytes`		int([x]) -> integer

bytes_downloaded `class-attribute`

bytes_downloaded = 0

int([x]) -> integer int(x, base=10) -> integer

Convert a number or string to an integer, or return 0 if no arguments are given. If x is a number, return x.int(). For floating point numbers, this truncates towards zero.

If x is not a number or if base is given, then x must be a string, bytes, or bytearray instance representing an integer literal in the given base. The literal can be preceded by '+' or '-' and be surrounded by whitespace. The base defaults to 10. Valid bases are 0 and 2-36. Base 0 means to interpret the base from the string as an integer literal.

int('0b100', base=0) 4

restarted_bytes `class-attribute`

restarted_bytes = 0