## burstmap.download_burst_map()


Download and prepare the Sentinel-1 burst-ID map for a given acquisition mode.


Usage

``` python
burstmap.download_burst_map(
    cache_dir=None,
    *,
    mode="IW",
)
```


The map is a large (~500 MB per mode) static dataset from SAR-MPC. It is only needed to look up the relative orbit number, pass direction, or footprint geometry of a burst that was **not** obtained from a CDSE search or an SLC filename (e.g. a manually constructed burst). It is not downloaded automatically; call this once to opt in. The raw download is verified against a pinned SHA-256.


## Parameters


`cache_dir: str | Path | None = None`  
Root directory for cached dataset files. Defaults to the `FREEZEBASE_CACHE` environment variable or the system cache directory.

`mode: Mode = ``"IW"`  
Sentinel-1 acquisition mode.


## Returns


`Path`  
Path to the prepared GeoParquet file.


## Raises


`BurstMapUnavailableError`  
If the download fails, the downloaded archive is corrupt or holds no burst-ID map for `mode`, or a map prepared earlier is unreadable. A failed download keeps the `requests` or freezebase error as the cause; a corrupt archive or unreadable prepared map keeps the read error and names the file to delete.