sentinelhub Python API

The sentinelhub package provides an interface to Sentinel Hub services and geospatial utilities:

Sentinel Hub Services

• Process API: For requesting processed imagery.
• Catalog API: For searching data collections.
• Batch Processing API: For large-scale asynchronous processing.
• BYOC API: Bring Your Own Cloud.
• Statistical API: For extracting statistics from imagery.
• OGC services: Support for WMS, WCS, and WFS.
• Authentication & Rate-limiting: Built-in handling for service access.

Geospatial Utilities

• Interface for geospatial objects and transformations.
• Large area splitting.
• Data collection objects.
• IO tools.

Geopedia

• Support for Geopedia WMS and REST API.

When multiple configuration sources are present, sentinelhub-py follows this precedence order (from highest to lowest):

1. Explicit parameters: Values passed directly to SHConfig(sh_client_id="...") or function calls.
2. Environment variables: Values set via SH_CLIENT_ID, SH_CLIENT_SECRET, or SH_PROFILE.
3. Configuration file: Values defined in config.toml.
4. Defaults: The hardcoded default values in the library.

The package is available via the conda-forge channel. Use the following command to install it:

conda install -c conda-forge sentinelhub

To see runtime information and basic logs from the sentinelhub package, configure the standard Python logging module to the DEBUG level.

import logging

logging.basicConfig(level=logging.DEBUG)

You can install the core sentinelhub package using pip. If you need to interact with Amazon Web Services, install the package with the [AWS] extension tag to include the necessary extra dependencies.

# Install core package
pip install sentinelhub

# Install with AWS support
pip install sentinelhub[AWS]

Because downloading is multi-threaded using the threading library, you can distinguish which log belongs to which thread by adding %(threadName)s to your logging format string. The default format is %(levelname)s:%(name)s:%(message)s.

import logging

# The default format is '%(levelname)s:%(name)s:%(message)s'

logging.basicConfig(
    level=logging.DEBUG,
    format='%(levelname)s:%(name)s:%(threadName)s:%(message)s',
)

Since sentinelhub uses the requests package for HTTP communication, you can obtain detailed information about HTTP requests by enabling low-level urllib3 logs and setting the HTTPConnection.debuglevel.

import logging
from http.client import HTTPConnection

HTTPConnection.debuglevel = 1

logging.basicConfig(level=logging.DEBUG)
requests_log = logging.getLogger("requests.packages.urllib3")
requests_log.setLevel(logging.DEBUG)
requests_log.propagate = True

You can redirect all warnings that occur during evaluation to the logger by using logging.captureWarnings(True) in conjunction with the DEBUG level.

import logging

logging.basicConfig(level=logging.DEBUG)
logging.captureWarnings(True)

To use the Copernicus Data Space Ecosystem, you must register an OAuth client via the Sentinel Hub Services Dashboard and configure SHConfig with the following specific parameters:

from sentinelhub import SHConfig

config = SHConfig()
config.sh_client_id = 'oauth-client-id'
config.sh_client_secret = 'oauth-client-secret'
config.sh_base_url = 'https://sh.dataspace.copernicus.eu'
config.sh_token_url = 'https://identity.dataspace.copernicus.eu/auth/realms/CDSE/protocol/openid-connect/token'