odc.stac.load(items, bands=None, *, groupby=None, resampling=None, chunks=None, crs=None, resolution=None, geobox=None, bbox=None, lon=None, lat=None, x=None, y=None, align=None, like=None, geopolygon=None, stac_cfg=None, patch_url=None, product_cache=None, skip_broken_datasets=False, progress_cbk=None, fuse_func=None, **kw)[source]

STAC Item to xarray.Dataset.

Load several STAC Item objects (from the same or similar collections) as an xarray.Dataset.

This method can load pixel data directly on a local machine or construct a Dask graph that can be processed on a remote cluster.

catalog = pystac.Client.open(...)
query = catalog.search(...)
xx = odc.stac.load(
    bands=["red", "green", "blue"],
    resolution=(-100, 100),

Common Options

  • groupby (Optional[str]) – Controls what items get placed in to the same pixel plane, supported values are “time” or “solar_day”, default is “time”

  • resampling (Union[str, Dict[str, str], None]) – Controls resampling strategy, can be specified per band

  • chunks (Optional[Dict[str, int]]) – Rather than loading pixel data directly, construct Dask backed arrays. chunks={'x': 2048, 'y': 2048}

Control Pixel Grid of Output

There are many ways to control footprint and resolution of returned data. The most precise way is to use GeoBox, geobox=GeoBox(..). Similarly one can use like=xx to match pixel grid to previously loaded data (xx = odc.stac.load(...)).

Other common way is to configure crs and resolution only

xx = odc.stac.load(...
    resolution=(-10, 10))

# resolution units must match CRS
# here we assume 1 degree == 111km to load at roughly
# the same 10m resolution as statement above.
yy = odc.stac.load(...

By default odc.stac.load() loads all available pixels in the requested projection and resolution. To limit extent of loaded data you have to supply bounds via either geobox= or like= parameters (these also select projection and resolution). Alternatively use a pair of x, y or lon, lat parameters. x, y allows you to specify bounds in the output projection, while lon, lat operate in degrees. You can also use bbox which is equivalent to lon, lat.

It should be noted that returned data is likely to reach outside of the requested bounds by fraction of a pixel when using bbox, x, y or lon, lat mechanisms. This is due to pixel grid “snapping”. Pixel edges will still start at N*pixel_size where N is int regardless of the requested bounding box.

  • crs (Union[str, CRS, CRS, Dict[str, Any], None]) – Load data in a given CRS

  • resolution (Union[float, int, Tuple[float, float], None]) – Set resolution of output in Y, X order, it is common for Y to be negative, e.g. resolution=(-10, 10). Resolution must be supplied in the units of the output CRS, so they are commonly in meters for Projected and in degrees for Geographic CRSs. resolution=10 is equivalent to resolution=(-10, 10).

  • bbox (Optional[Tuple[float, float, float, float]]) – Specify bounding box in Lon/Lat. [min(lon), min(lat), max(lon), max(lat)]

  • lon (Optional[Tuple[float, float]]) – Define output bounds in Lon/Lat

  • lat (Optional[Tuple[float, float]]) – Define output bounds in Lon/Lat

  • x (Optional[Tuple[float, float]]) – Define output bounds in output projection coordinate units

  • y (Optional[Tuple[float, float]]) – Define output bounds in output projection coordinate units

  • align (Union[float, int, Tuple[float, float], None]) – Control pixel snapping, default is to align pixel grid to X/Y axis such that pixel edges lie on the axis.

  • geobox (Optional[GeoBox]) – Allows to specify exact region/resolution/projection using GeoBox object

  • like (Optional[Any]) – Match output grid to the data loaded previously.

STAC Related Options


Pass-through to datacube.Datacube.load()

  • progress_cbk (Optional[Callable[[int, int], Any]]) – Get data loading progress via callback, ignored when constructing Dask arrays

  • skip_broken_datasets (bool) – Continue processing when IO errors are encountered

  • fuse_func (Optional[Callable[[ndarray, ndarray], ndarray]]) –

    Provide custom function for fusing pixels from different sources into one pixel plane.

    The default behaviour is to use first observed valid pixel. Item timestamp is used to determine order, nodata is used to determine “valid”.

  • kw – Any other named parameter is passed on to datacube.Datacube.load()

Return type



xarray.Dataset with requested bands populated

Complete Example Code

import planetary_computer as pc
from pystac_client import Client

from odc import stac

catalog = Client.open("https://planetarycomputer.microsoft.com/api/stac/v1")
query = catalog.search(
    query={"s2:mgrs_tile": dict(eq="06VVN")},

xx = stac.load(
    bands=["red", "green", "blue"],
xx.red.plot.imshow(col="time", size=8, aspect=1)

Example Configuration

Sample stac_cfg={..} parameter.

sentinel-2-l2a:  # < name of the collection, i.e. ``.collection_id``
    "*":  # Band named "*" contains band info for "most" bands
      data_type: uint16
      nodata: 0
      unit: "1"
    SCL:  # Those bands that are different than "most"
      data_type: uint8
      nodata: 0
      unit: "1"
  aliases:  #< unique alias -> canonical map
    rededge: B05
    rededge1: B05
    rededge2: B06
    rededge3: B07

  warnings: ignore  # ignore|all  (default all)


"*": # Applies to all collections if not defined on a collection
  warnings: ignore

See also

STAC item interpretation stac2ds()