Generate SentinelHub cubes

xcube Data Store Framework - Sentinel Hub¶

This notebook provides a walk-through demonstrating how to use xcube and the xcube Sentinel Hub (SH) plugin to read and explore data from the Sentinel Hub cloud API.

Please note: In order to access data from Sentinel Hub, you need Sentinel Hub API credentials. They may be passed as store parameters (see further below) or exported from environment variables.
In case you have not exported them already, you may also set them by uncommenting the cell below and adjusting the content to your access credentials. However, we do not recommend this method!

Within DeepESDL there is the possiblity to apply for SentinelHub access - please contact the DeepESDL team :)
Brockmann Consult, 2025

---

This notebook runs with the python environment deepesdl-xcube-1.11.0, please checkout the documentation for help on changing the environment.

This notebook gives an introduction to the xcube-sentinelhub store and additionally shows how to access different data sets through the Sentinel Hub API via xcube:

1. Access Sentinel-1 through xcube Sentinel hub Store
2. Access Sentinel-2 through xcube Sentinel hub Store
3. Access Landsat 8-L1C through xcube Sentinel hub Store

In [1]:

# import os
# os.environ["SH_CLIENT_ID"] =  your_sh_client_id
# os.environ["SH_CLIENT_SECRET"] = your_sh_client_secret

# import os # os.environ["SH_CLIENT_ID"] = your_sh_client_id # os.environ["SH_CLIENT_SECRET"] = your_sh_client_secret

In [2]:

# mandatory imports
from xcube.core.store import find_data_store_extensions
from xcube.core.store import get_data_store_params_schema
from xcube.core.store import new_data_store

# Utilities for notebook visualization
import shapely.geometry
import IPython.display
from IPython.display import JSON
import matplotlib.pyplot as plt

# mandatory imports from xcube.core.store import find_data_store_extensions from xcube.core.store import get_data_store_params_schema from xcube.core.store import new_data_store # Utilities for notebook visualization import shapely.geometry import IPython.display from IPython.display import JSON import matplotlib.pyplot as plt

Configure matplotlib to display graphs inline directly in the notebook and set a sensible default figure size.

In [3]:

%matplotlib inline
plt.rcParams["figure.figsize"] = 16,12

%matplotlib inline plt.rcParams["figure.figsize"] = 16,12

Check whether the sentinelhub store is among the available stores, if not you need to choose an environment where xcube-sh is included.

In [4]:

JSON({e.name: e.metadata for e in find_data_store_extensions()})

JSON({e.name: e.metadata for e in find_data_store_extensions()})

Out[4]:

<IPython.core.display.JSON object>

Usually we need more information to get the actual data store object. Which data store parameters are available for the sentinelhub store?

In [5]:

get_data_store_params_schema('sentinelhub')

get_data_store_params_schema('sentinelhub')

Out[5]:

<xcube.util.jsonschema.JsonObjectSchema at 0x7f947e3e0e50>

Please note the client_id and client_secret parameters mentioned at the beginning.

Provide mandatory parameters to instantiate the store class:

In [6]:

store = new_data_store('sentinelhub', num_retries=400)

store = new_data_store('sentinelhub', num_retries=400)

Which datasets are provided? (the list may contain both gridded and vector datasets):

In [7]:

list(store.get_data_ids())

list(store.get_data_ids())

Out[7]:

['S2L1C', 'S1GRD', 'S2L2A', 'DEM']

Get more info about a specific dataset. This includes a description of the possible open formats:

In [8]:

store.describe_data('S2L2A')

store.describe_data('S2L2A')

Out[8]:

<xcube.core.store.descriptor.DatasetDescriptor at 0x7f947e30e900>

Which parameters must be passsed or are available to open the dataset?

In [9]:

store.get_open_data_params_schema('S2L2A')

store.get_open_data_params_schema('S2L2A')

Out[9]:

<xcube.util.jsonschema.JsonObjectSchema at 0x7f947e35edd0>

There are 3 required parameters, so we need to provide them to open a dataset, one of them being bbox. Let's set a region covering Hamburg:

In [10]:

bbox=[9.7, 53.4, 10.2, 53.7]

bbox=[9.7, 53.4, 10.2, 53.7]

Take a look at the bbox in order to make sure the area is correctly set:

In [11]:

IPython.display.GeoJSON(shapely.geometry.box(*bbox).__geo_interface__)

IPython.display.GeoJSON(shapely.geometry.box(*bbox).__geo_interface__)

<IPython.display.GeoJSON object>

Now set the other parameters for opening the dataset from the store:

In [12]:

dataset = store.open_data('S2L2A', 
                          variable_names=['B04'], 
                          bbox=bbox, 
                          spatial_res=0.00018, 
                          time_range=('2020-08-10','2020-08-20'), 
                          time_period='1D',
                          tile_size= [1024, 1024])
dataset

dataset = store.open_data('S2L2A', variable_names=['B04'], bbox=bbox, spatial_res=0.00018, time_range=('2020-08-10','2020-08-20'), time_period='1D', tile_size= [1024, 1024]) dataset

Out[12]:

<xarray.Dataset> Size: 277MB
Dimensions:    (time: 11, lat: 2048, lon: 3072, bnds: 2)
Coordinates:
  * lat        (lat) float64 16kB 53.77 53.77 53.77 53.77 ... 53.4 53.4 53.4
  * lon        (lon) float64 25kB 9.7 9.7 9.7 9.701 ... 10.25 10.25 10.25 10.25
  * time       (time) datetime64[ns] 88B 2020-08-10T12:00:00 ... 2020-08-20T1...
    time_bnds  (time, bnds) datetime64[ns] 176B dask.array<chunksize=(11, 2), meta=np.ndarray>
Dimensions without coordinates: bnds
Data variables:
    B04        (time, lat, lon) float32 277MB dask.array<chunksize=(1, 1024, 1024), meta=np.ndarray>
Attributes: (12/13)
    Conventions:               CF-1.7
    title:                     S2L2A Data Cube Subset
    history:                   [{'program': 'xcube_sh.chunkstore.SentinelHubC...
    date_created:              2025-10-01T07:48:21.075808
    time_coverage_start:       2020-08-10T00:00:00+00:00
    time_coverage_end:         2020-08-21T00:00:00+00:00
    ...                        ...
    time_coverage_resolution:  P1DT0H0M0S
    geospatial_lon_min:        9.7
    geospatial_lat_min:        53.4
    geospatial_lon_max:        10.25296
    geospatial_lat_max:        53.76864
    processing_level:          L2A

xarray.Dataset

• Dimensions:
  • time: 11
  • lat: 2048
  • lon: 3072
  • bnds: 2
• Coordinates: (4)
  • lat
    (lat)
    float64
    53.77 53.77 53.77 ... 53.4 53.4

    units :

    decimal_degrees

    long_name :

    latitude

    standard_name :

    latitude

    array([53.76855, 53.76837, 53.76819, ..., 53.40045, 53.40027, 53.40009],
          shape=(2048,))

  • lon
    (lon)
    float64
    9.7 9.7 9.7 ... 10.25 10.25 10.25

    units :

    decimal_degrees

    long_name :

    longitude

    standard_name :

    longitude

    array([ 9.70009,  9.70027,  9.70045, ..., 10.25251, 10.25269, 10.25287],
          shape=(3072,))

  • time
    (time)
    datetime64[ns]
    2020-08-10T12:00:00 ... 2020-08-...

    standard_name :

    time

    bounds :

    time_bnds

    array(['2020-08-10T12:00:00.000000000', '2020-08-11T12:00:00.000000000',
           '2020-08-12T12:00:00.000000000', '2020-08-13T12:00:00.000000000',
           '2020-08-14T12:00:00.000000000', '2020-08-15T12:00:00.000000000',
           '2020-08-16T12:00:00.000000000', '2020-08-17T12:00:00.000000000',
           '2020-08-18T12:00:00.000000000', '2020-08-19T12:00:00.000000000',
           '2020-08-20T12:00:00.000000000'], dtype='datetime64[ns]')

  • time_bnds
    (time, bnds)
    datetime64[ns]
    dask.array<chunksize=(11, 2), meta=np.ndarray>

    standard_name :

    time

    Array Chunk Bytes 176 B 176 B Shape (11, 2) (11, 2) Dask graph 1 chunks in 2 graph layers Data type datetime64[ns] numpy.ndarray

• Data variables: (1)
  • B04
    (time, lat, lon)
    float32
    dask.array<chunksize=(1, 1024, 1024), meta=np.ndarray>

    sample_type :

    FLOAT32

    units :

    reflectance

    wavelength :

    664.75

    wavelength_a :

    664.6

    wavelength_b :

    664.9

    bandwidth :

    31.0

    bandwidth_a :

    31

    bandwidth_b :

    31

    resolution :

    10

    Array Chunk Bytes 264.00 MiB 4.00 MiB Shape (11, 2048, 3072) (1, 1024, 1024) Dask graph 66 chunks in 2 graph layers Data type float32 numpy.ndarray

• Indexes: (3)
  • lat
    PandasIndex

    PandasIndex(Index([          53.76855,           53.76837,           53.76819,
                     53.76801,           53.76783, 53.767649999999996,
           53.767469999999996, 53.767289999999996, 53.767109999999995,
           53.766929999999995,
           ...
                     53.40171,           53.40153,           53.40135,
                     53.40117,           53.40099,           53.40081,
                     53.40063,           53.40045,           53.40027,
                     53.40009],
          dtype='float64', name='lat', length=2048))

  • lon
    PandasIndex

    PandasIndex(Index([           9.70009,            9.70027,            9.70045,
                      9.70063,  9.700809999999999,            9.70099,
                      9.70117,            9.70135,            9.70153,
                      9.70171,
           ...
           10.251249999999999,           10.25143,           10.25161,
                     10.25179,           10.25197,           10.25215,
                     10.25233,           10.25251,           10.25269,
                     10.25287],
          dtype='float64', name='lon', length=3072))

  • time
    PandasIndex

    PandasIndex(DatetimeIndex(['2020-08-10 12:00:00', '2020-08-11 12:00:00',
                   '2020-08-12 12:00:00', '2020-08-13 12:00:00',
                   '2020-08-14 12:00:00', '2020-08-15 12:00:00',
                   '2020-08-16 12:00:00', '2020-08-17 12:00:00',
                   '2020-08-18 12:00:00', '2020-08-19 12:00:00',
                   '2020-08-20 12:00:00'],
                  dtype='datetime64[ns]', name='time', freq=None))

• Attributes: (13)

  Conventions :

  CF-1.7

  title :

  S2L2A Data Cube Subset

  history :

  [{'program': 'xcube_sh.chunkstore.SentinelHubChunkStore', 'cube_config': {'dataset_name': 'S2L2A', 'band_names': ['B04'], 'band_fill_values': None, 'band_sample_types': None, 'band_units': None, 'tile_size': [1024, 1024], 'bbox': [9.7, 53.4, 10.25296, 53.76864], 'spatial_res': 0.00018, 'crs': 'WGS84', 'upsampling': 'NEAREST', 'downsampling': 'NEAREST', 'mosaicking_order': 'mostRecent', 'time_range': ['2020-08-10T00:00:00+00:00', '2020-08-20T00:00:00+00:00'], 'time_period': '1 days 00:00:00', 'time_tolerance': None, 'collection_id': None, 'four_d': False}}]

  date_created :

  2025-10-01T07:48:21.075808

  time_coverage_start :

  2020-08-10T00:00:00+00:00

  time_coverage_end :

  2020-08-21T00:00:00+00:00

  time_coverage_duration :

  P11DT0H0M0S

  time_coverage_resolution :

  P1DT0H0M0S

  geospatial_lon_min :

  9.7

  geospatial_lat_min :

  53.4

  geospatial_lon_max :

  10.25296

  geospatial_lat_max :

  53.76864

  processing_level :

  L2A

For further information, a description about the dataset and the bands may be found here: https://docs.sentinel-hub.com/api/latest/data/sentinel-2-l2a/ .

Plot one time stamp of the dataset for our requested variable:

In [13]:

dataset.B04.isel(time=2).plot.imshow(vmin=0, vmax=0.2, cmap='Greys_r')

dataset.B04.isel(time=2).plot.imshow(vmin=0, vmax=0.2, cmap='Greys_r')

Out[13]:

<matplotlib.image.AxesImage at 0x7f948cf18440>

In case you wonder why we chose Hamburg - well, it is a lovely city!

Let's have a look at the different products, which are available via xcube-sentinelhub.¶

1. Sentinel-1 GRD¶

Setting of AOI bounding box

In [14]:

x1 = 10.00  # degree
y1 = 54.27  # degree
x2 = 11.00  # degree
y2 = 54.60  # degree

bbox = x1, y1, x2, y2

x1 = 10.00 # degree y1 = 54.27 # degree x2 = 11.00 # degree y2 = 54.60 # degree bbox = x1, y1, x2, y2

In [15]:

spatial_res = 0.00018   # = 20.038 meters in degree

spatial_res = 0.00018 # = 20.038 meters in degree

Sentinel Hub currently supported Sentinel-1 GRD (Ground Range Detected) products: here

In [16]:

store = new_data_store('sentinelhub', num_retries=400)

store = new_data_store('sentinelhub', num_retries=400)

In [17]:

list(store.get_data_ids())

list(store.get_data_ids())

Out[17]:

['S2L1C', 'S1GRD', 'S2L2A', 'DEM']

In [18]:

store.describe_data('S1GRD')

store.describe_data('S1GRD')

Out[18]:

<xcube.core.store.descriptor.DatasetDescriptor at 0x7f948cd9ad50>

In [19]:

cube = store.open_data(
    'S1GRD',
    variable_names=['VH'],
    tile_size=[512, 512],
    crs = "EPSG:4326",
    spatial_res = spatial_res,
    bbox=bbox,
    time_range=['2019-06-14', '2019-07-31'],
    time_period='2D'
)
cube

cube = store.open_data( 'S1GRD', variable_names=['VH'], tile_size=[512, 512], crs = "EPSG:4326", spatial_res = spatial_res, bbox=bbox, time_range=['2019-06-14', '2019-07-31'], time_period='2D' ) cube

Out[19]:

<xarray.Dataset> Size: 1GB
Dimensions:    (time: 24, lat: 2048, lon: 5632, bnds: 2)
Coordinates:
  * lat        (lat) float64 16kB 54.64 54.64 54.64 54.64 ... 54.27 54.27 54.27
  * lon        (lon) float64 45kB 10.0 10.0 10.0 10.0 ... 11.01 11.01 11.01
  * time       (time) datetime64[ns] 192B 2019-06-15 2019-06-17 ... 2019-07-31
    time_bnds  (time, bnds) datetime64[ns] 384B dask.array<chunksize=(24, 2), meta=np.ndarray>
Dimensions without coordinates: bnds
Data variables:
    VH         (time, lat, lon) float32 1GB dask.array<chunksize=(1, 512, 512), meta=np.ndarray>
Attributes: (12/13)
    Conventions:               CF-1.7
    title:                     S1GRD Data Cube Subset
    history:                   [{'program': 'xcube_sh.chunkstore.SentinelHubC...
    date_created:              2025-10-01T07:48:23.913504
    time_coverage_start:       2019-06-14T00:00:00+00:00
    time_coverage_end:         2019-08-01T00:00:00+00:00
    ...                        ...
    time_coverage_resolution:  P2DT0H0M0S
    geospatial_lon_min:        10.0
    geospatial_lat_min:        54.27
    geospatial_lon_max:        11.01376
    geospatial_lat_max:        54.63864
    processing_level:          L1B

xarray.Dataset

• Dimensions:
  • time: 24
  • lat: 2048
  • lon: 5632
  • bnds: 2
• Coordinates: (4)
  • lat
    (lat)
    float64
    54.64 54.64 54.64 ... 54.27 54.27

    units :

    decimal_degrees

    long_name :

    latitude

    standard_name :

    latitude

    array([54.63855, 54.63837, 54.63819, ..., 54.27045, 54.27027, 54.27009],
          shape=(2048,))

  • lon
    (lon)
    float64
    10.0 10.0 10.0 ... 11.01 11.01

    units :

    decimal_degrees

    long_name :

    longitude

    standard_name :

    longitude

    array([10.00009, 10.00027, 10.00045, ..., 11.01331, 11.01349, 11.01367],
          shape=(5632,))

  • time
    (time)
    datetime64[ns]
    2019-06-15 ... 2019-07-31

    standard_name :

    time

    bounds :

    time_bnds

    array(['2019-06-15T00:00:00.000000000', '2019-06-17T00:00:00.000000000',
           '2019-06-19T00:00:00.000000000', '2019-06-21T00:00:00.000000000',
           '2019-06-23T00:00:00.000000000', '2019-06-25T00:00:00.000000000',
           '2019-06-27T00:00:00.000000000', '2019-06-29T00:00:00.000000000',
           '2019-07-01T00:00:00.000000000', '2019-07-03T00:00:00.000000000',
           '2019-07-05T00:00:00.000000000', '2019-07-07T00:00:00.000000000',
           '2019-07-09T00:00:00.000000000', '2019-07-11T00:00:00.000000000',
           '2019-07-13T00:00:00.000000000', '2019-07-15T00:00:00.000000000',
           '2019-07-17T00:00:00.000000000', '2019-07-19T00:00:00.000000000',
           '2019-07-21T00:00:00.000000000', '2019-07-23T00:00:00.000000000',
           '2019-07-25T00:00:00.000000000', '2019-07-27T00:00:00.000000000',
           '2019-07-29T00:00:00.000000000', '2019-07-31T00:00:00.000000000'],
          dtype='datetime64[ns]')

  • time_bnds
    (time, bnds)
    datetime64[ns]
    dask.array<chunksize=(24, 2), meta=np.ndarray>

    standard_name :

    time

    Array Chunk Bytes 384 B 384 B Shape (24, 2) (24, 2) Dask graph 1 chunks in 2 graph layers Data type datetime64[ns] numpy.ndarray

• Data variables: (1)
  • VH
    (time, lat, lon)
    float32
    dask.array<chunksize=(1, 512, 512), meta=np.ndarray>

    sample_type :

    FLOAT32

    units :

    Linear power in the chosen backscattering coefficient

    Array Chunk Bytes 1.03 GiB 1.00 MiB Shape (24, 2048, 5632) (1, 512, 512) Dask graph 1056 chunks in 2 graph layers Data type float32 numpy.ndarray

• Indexes: (3)
  • lat
    PandasIndex

    PandasIndex(Index([          54.63855,           54.63837,           54.63819,
                     54.63801,           54.63783,           54.63765,
                     54.63747,           54.63729,           54.63711,
                     54.63693,
           ...
           54.271710000000006, 54.271530000000006, 54.271350000000005,
           54.271170000000005, 54.270990000000005, 54.270810000000004,
           54.270630000000004, 54.270450000000004, 54.270270000000004,
                     54.27009],
          dtype='float64', name='lat', length=2048))

  • lon
    PandasIndex

    PandasIndex(Index([          10.00009,           10.00027,           10.00045,
           10.000630000000001,           10.00081,           10.00099,
                     10.00117,           10.00135,           10.00153,
           10.001710000000001,
           ...
           11.012049999999999, 11.012229999999999,           11.01241,
                     11.01259,           11.01277,           11.01295,
                     11.01313, 11.013309999999999,           11.01349,
                     11.01367],
          dtype='float64', name='lon', length=5632))

  • time
    PandasIndex

    PandasIndex(DatetimeIndex(['2019-06-15', '2019-06-17', '2019-06-19', '2019-06-21',
                   '2019-06-23', '2019-06-25', '2019-06-27', '2019-06-29',
                   '2019-07-01', '2019-07-03', '2019-07-05', '2019-07-07',
                   '2019-07-09', '2019-07-11', '2019-07-13', '2019-07-15',
                   '2019-07-17', '2019-07-19', '2019-07-21', '2019-07-23',
                   '2019-07-25', '2019-07-27', '2019-07-29', '2019-07-31'],
                  dtype='datetime64[ns]', name='time', freq=None))

• Attributes: (13)

  Conventions :

  CF-1.7

  title :

  S1GRD Data Cube Subset

  history :

  [{'program': 'xcube_sh.chunkstore.SentinelHubChunkStore', 'cube_config': {'dataset_name': 'S1GRD', 'band_names': ['VH'], 'band_fill_values': None, 'band_sample_types': None, 'band_units': None, 'tile_size': [512, 512], 'bbox': [10.0, 54.27, 11.01376, 54.63864], 'spatial_res': 0.00018, 'crs': 'EPSG:4326', 'upsampling': 'NEAREST', 'downsampling': 'NEAREST', 'mosaicking_order': 'mostRecent', 'time_range': ['2019-06-14T00:00:00+00:00', '2019-07-31T00:00:00+00:00'], 'time_period': '2 days 00:00:00', 'time_tolerance': None, 'collection_id': None, 'four_d': False}}]

  date_created :

  2025-10-01T07:48:23.913504

  time_coverage_start :

  2019-06-14T00:00:00+00:00

  time_coverage_end :

  2019-08-01T00:00:00+00:00

  time_coverage_duration :

  P48DT0H0M0S

  time_coverage_resolution :

  P2DT0H0M0S

  geospatial_lon_min :

  10.0

  geospatial_lat_min :

  54.27

  geospatial_lon_max :

  11.01376

  geospatial_lat_max :

  54.63864

  processing_level :

  L1B

In [ ]:

cube.VH.isel(time=1).plot.imshow(cmap='Greys',vmax =0.08, figsize = [16,12])

cube.VH.isel(time=1).plot.imshow(cmap='Greys',vmax =0.08, figsize = [16,12])

Out[ ]:

<matplotlib.image.AxesImage at 0x7f948ccb4550>

2. Sentinel-2 L2A (SCL)¶

Sentinel Hub currently supported Sentinel-2 products: here

In [ ]:

store.describe_data('S2L2A')

store.describe_data('S2L2A')

In [ ]:

cube = store.open_data(
    'S2L2A',
    variable_names=['SCL'],
    tile_size=[512, 512],
    spatial_res = spatial_res,
    bbox=bbox,
    time_range=['2018-06-14', '2018-07-31'],
    time_tolerance='30m'
)
cube

cube = store.open_data( 'S2L2A', variable_names=['SCL'], tile_size=[512, 512], spatial_res = spatial_res, bbox=bbox, time_range=['2018-06-14', '2018-07-31'], time_tolerance='30m' ) cube

In [ ]:

cube.SCL.isel(time=8, lat=slice(0,2000),lon=slice(0,2000)).plot.imshow(cmap='tab20c')

cube.SCL.isel(time=8, lat=slice(0,2000),lon=slice(0,2000)).plot.imshow(cmap='tab20c')

3. Landsat 8 L1C¶

Sentinel Hub currently supports Landsat 8-L1C products: here. To access Landsat or MODIS, another api endpoint is required. You can learn about the endpoints here. services.sentinel-hub.com is the default.

In [ ]:

store = new_data_store('sentinelhub', api_url='https://services-uswest2.sentinel-hub.com', num_retries=400)

store = new_data_store('sentinelhub', api_url='https://services-uswest2.sentinel-hub.com', num_retries=400)

In [ ]:

list(store.get_data_ids())

list(store.get_data_ids())

In [ ]:

store.describe_data('LOTL1')

store.describe_data('LOTL1')

In [ ]:

cube = store.open_data(
    'LOTL1',
    variable_names=['B04'],
    bbox=bbox,
    spatial_res=spatial_res,
    time_range=['2018-06-14', '2018-07-31'],
)
cube

cube = store.open_data( 'LOTL1', variable_names=['B04'], bbox=bbox, spatial_res=spatial_res, time_range=['2018-06-14', '2018-07-31'], ) cube

In [ ]:

cube.B04.isel(time=6, lat=slice(0,2000),lon=slice(0,2000)).plot.imshow(cmap='Greys', vmax=0.3)

cube.B04.isel(time=6, lat=slice(0,2000),lon=slice(0,2000)).plot.imshow(cmap='Greys', vmax=0.3)

In [ ]: