sentinelhub.api.batch.process

Module implementing an interface with Sentinel Hub Batch Processing API.

class sentinelhub.api.batch.process.BatchTileStatus(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)[source]

Bases: Enum

An enum class with all possible batch tile statuses

PENDING = 'PENDING'
SCHEDULED = 'SCHEDULED'
QUEUED = 'QUEUED'
PROCESSING = 'PROCESSING'
PROCESSED = 'PROCESSED'
FAILED = 'FAILED'
class sentinelhub.api.batch.process.SentinelHubBatch(config=None)[source]

Bases: BaseBatchClient

An interface class for Sentinel Hub Batch API

For more info check Batch API reference.

Parameters:

config (SHConfig | None) – A configuration object with required parameters sh_client_id, sh_client_secret, and sh_auth_base_url which is used for authentication and sh_base_url which defines the service deployment that will be used.

create(sentinelhub_request, tiling_grid, output=None, bucket_name=None, description=None, **kwargs)[source]

Create a new batch request

Batch API reference

Parameters:

  • sentinelhub_request (SentinelHubRequest | Dict[str, Any]) – An instance of SentinelHubRequest class containing all request parameters. Alternatively, it can also be just a payload dictionary for Process API request

  • tiling_grid (Dict[str, Any]) – A dictionary with tiling grid parameters. It can be built with tiling_grid method

  • output (Dict[str, Any] | None) – A dictionary with output parameters. It can be built with output method. Alternatively, one can set bucket_name parameter instead.

  • bucket_name (str | None) – A name of an S3 bucket where to save data. Alternatively, one can set output parameter to specify more output parameters.

  • description (str | None) – A description of a batch request

  • kwargs (Any) – Any other arguments to be added to a dictionary of parameters.

Returns:

An instance of SentinelHubBatch object that represents a newly created batch request.

Return type:

BatchRequest

static tiling_grid(grid_id, resolution, buffer=None, **kwargs)[source]

A helper method to build a dictionary with tiling grid parameters

Parameters:

  • grid_id (int) – An ID of a tiling grid

  • resolution (float) – A grid resolution

  • buffer (Tuple[int, int] | None) – Optionally, a buffer around each tile can be defined. It can be defined with a tuple of integers (buffer_x, buffer_y), which specifies a number of buffer pixels in horizontal and vertical directions.

  • kwargs (Any) – Any other arguments to be added to a dictionary of parameters

Returns:

A dictionary with parameters

Return type:

Dict[str, Any]

static output(*, default_tile_path=None, overwrite=None, skip_existing=None, cog_output=None, cog_parameters=None, create_collection=None, collection_id=None, responses=None, **kwargs)[source]

A helper method to build a dictionary with tiling grid parameters

Parameters:

  • default_tile_path (str | None) – A path or a template on an s3 bucket where to store results. More info at Batch API documentation

  • overwrite (bool | None) – A flag specifying if a request should overwrite existing outputs without failing

  • skip_existing (bool | None) – A flag specifying if existing outputs should be overwritten

  • cog_output (bool | None) – A flag specifying if outputs should be written in COGs (cloud-optimized GeoTIFFs )or normal GeoTIFFs

  • cog_parameters (Dict[str, Any] | None) – A dictionary specifying COG creation parameters

  • create_collection (bool | None) – If True the results will be written in COGs and a batch collection will be created

  • collection_id (str | None) – If True results will be added to an existing collection

  • responses (List[str] | None) – Specification of path template for individual outputs/responses

  • kwargs (Any) – Any other arguments to be added to a dictionary of parameters

Returns:

A dictionary of output parameters

Return type:

Dict[str, Any]

iter_tiling_grids(**kwargs)[source]

An iterator over tiling grids

Batch API reference

Parameters:

kwargs (Any) – Any other request query parameters

Returns:

An iterator over tiling grid definitions

Return type:

SentinelHubFeatureIterator

get_tiling_grid(grid_id)[source]

Provides a single tiling grid

Batch API reference

Parameters:

grid_id (int | str) – An ID of a requested tiling grid

Returns:

A tiling grid definition

Return type:

Dict[str, Any]

iter_requests(user_id=None, search=None, sort=None, **kwargs)[source]

Iterate existing batch requests

Batch API reference

Parameters:

  • user_id (str | None) – Filter requests by a user id who defined a request

  • search (str | None) – A search query to filter requests

  • sort (str | None) – A sort query

  • kwargs (Any) – Any additional parameters to include in a request query

Returns:

An iterator over existing batch requests

Return type:

Iterator[BatchRequest]

get_latest_request()[source]

Provides a batch request that has been created the latest

Returns:

Batch request info

Return type:

BatchRequest

get_request(batch_request)[source]

Collects information about a single batch request

Batch API reference

Returns:

Batch request info

Parameters:

batch_request (str | dict | BatchRequest) –

Return type:

BatchRequest

update_request(batch_request, output=None, description=None, **kwargs)[source]

Update batch job request parameters

Batch API reference

Similarly to update_info method, this method also updates local information in the current instance of SentinelHubBatch.

Parameters:

  • batch_request (str | dict | BatchRequest) – It could be a batch request object, a raw batch request payload or only a batch request ID.

  • output (Dict[str, Any] | None) – A dictionary with output parameters to be updated.

  • description (str | None) – A description of a batch request to be updated.

  • kwargs (Any) – Any other arguments to be added to a dictionary of parameters.

Return type:

Dict[str, Any] | list | str | float | int | None

delete_request(batch_request)[source]

Delete a batch job request

Batch API reference

Parameters:

batch_request (str | dict | BatchRequest) – It could be a batch request object, a raw batch request payload or only a batch request ID.

Return type:

Dict[str, Any] | list | str | float | int | None

start_analysis(batch_request)[source]

Starts analysis of a batch job request

Batch API reference

Parameters:

batch_request (str | dict | BatchRequest) – It could be a batch request object, a raw batch request payload or only a batch request ID.

Return type:

Dict[str, Any] | list | str | float | int | None

start_job(batch_request)[source]

Starts running a batch job

Batch API reference

Parameters:

batch_request (str | dict | BatchRequest) – It could be a batch request object, a raw batch request payload or only a batch request ID.

Return type:

Dict[str, Any] | list | str | float | int | None

cancel_job(batch_request)[source]

Cancels a batch job

Batch API reference

Parameters:

batch_request (str | dict | BatchRequest) – It could be a batch request object, a raw batch request payload or only a batch request ID.

Return type:

Dict[str, Any] | list | str | float | int | None

restart_job(batch_request)[source]

Restarts only those parts of a job that failed

Batch API reference

Parameters:

batch_request (str | dict | BatchRequest) – It could be a batch request object, a raw batch request payload or only a batch request ID.

Return type:

Dict[str, Any] | list | str | float | int | None

iter_tiles(batch_request, status=None, **kwargs)[source]

Iterate over info about batch request tiles

Batch API reference

Parameters:

  • batch_request (str | dict | BatchRequest) – It could be a batch request object, a raw batch request payload or only a batch request ID.

  • status (None | BatchTileStatus | str) – A filter to obtain only tiles with a certain status

  • kwargs (Any) – Any additional parameters to include in a request query

Returns:

An iterator over information about each tile

Return type:

SentinelHubFeatureIterator

get_tile(batch_request, tile_id)[source]

Provides information about a single batch request tile

Batch API reference

Parameters:

  • batch_request (str | dict | BatchRequest) – It could be a batch request object, a raw batch request payload or only a batch request ID.

  • tile_id (int | None) – An ID of a tile

Returns:

Information about a tile

Return type:

Dict[str, Any]

iter_collections(search=None, **kwargs)[source]

Iterate over batch collections

Batch API reference

Parameters:

  • search (str | None) – A search query to filter collections

  • kwargs (Any) – Any additional parameters to include in a request query

Returns:

An iterator over existing batch collections

Return type:

SentinelHubFeatureIterator

get_collection(collection_id)[source]

Get batch collection by its id

Batch API reference

Parameters:

collection_id (str) – A batch collection id

Returns:

A dictionary of the collection parameters

Return type:

Dict[str, Any]

create_collection(collection)[source]

Create a new batch collection

Batch API reference

Parameters:

collection (BatchCollection | dict) – Batch collection definition

Returns:

A dictionary of a newly created collection

Return type:

Dict[str, Any]

update_collection(collection)[source]

Update an existing batch collection

Batch API reference

Parameters:

collection (BatchCollection | dict) – Batch collection definition

Return type:

Dict[str, Any] | list | str | float | int | None

delete_collection(collection)[source]

Delete an existing batch collection

Batch API reference

Parameters:

collection (str | dict | BatchCollection) – Batch collection id or object

Return type:

Dict[str, Any] | list | str | float | int | None

class sentinelhub.api.batch.process.BatchRequest(request_id, process_request, tile_count, status, user_id=None, created=None, tiling_grid=<factory>, output=<factory>, bucket_name=None, description=None, value_estimate=None, tile_width_px=None, tile_height_px=None, user_action=None, user_action_updated=None, error=None, other_data=<factory>)[source]

Bases: BaseBatchRequest

A dataclass object that holds information about a batch request

Parameters:

  • request_id (str) –

  • process_request (dict) –

  • tile_count (int) –

  • status (BatchRequestStatus) –

  • user_id (str | None) –

  • created (datetime | None) –

  • tiling_grid (dict) –

  • output (dict) –

  • bucket_name (str | None) –

  • description (str | None) –

  • value_estimate (float | None) –

  • tile_width_px (int | None) –

  • tile_height_px (int | None) –

  • user_action (BatchUserAction | None) –

  • user_action_updated (str | None) –

  • error (str | None) –

  • other_data (CatchAllVar | None) –

request_id: str
process_request: dict
tile_count: int
status: BatchRequestStatus
user_id: str | None = None
created: datetime | None = None
tiling_grid: dict
output: dict
bucket_name: str | None = None
description: str | None = None
value_estimate: float | None = None
tile_width_px: int | None = None
tile_height_px: int | None = None
user_action: BatchUserAction | None = None
user_action_updated: str | None = None
error: str | None = None
other_data: CatchAllVar | None
property evalscript: str

Provides an evalscript used by a batch request

Returns:

An evalscript

property bbox: BBox | None

Provides a bounding box used by a batch request

Returns:

An area bounding box together with CRS

Raises:

ValueError

property geometry: Geometry | None

Provides a geometry used by a batch request

Returns:

An area geometry together with CRS

Raises:

ValueError

dataclass_json_config = {'letter_case': <function camelcase>, 'undefined': Undefined.INCLUDE}
classmethod from_dict(kvs, *, infer_missing=False)

Transforms itself into a dictionary form.

Parameters:

kvs (dict | list | str | int | float | bool | None) –

Return type:

A

classmethod from_json(s, *, parse_float=None, parse_int=None, parse_constant=None, infer_missing=False, **kw)
Parameters:

s (str | bytes | bytearray) –

Return type:

A

classmethod schema(*, infer_missing=False, only=None, exclude=(), many=False, context=None, load_only=(), dump_only=(), partial=False, unknown=None)
Parameters:

  • infer_missing (bool) –

  • many (bool) –

  • partial (bool) –

Return type:

SchemaF[A]

to_dict(encode_json=False)

Transforms itself into a dictionary form.

Return type:

Dict[str, dict | list | str | int | float | bool | None]

to_json(*, skipkeys=False, ensure_ascii=True, check_circular=True, allow_nan=True, indent=None, separators=None, default=None, sort_keys=False, **kw)
Parameters:

  • skipkeys (bool) –

  • ensure_ascii (bool) –

  • check_circular (bool) –

  • allow_nan (bool) –

  • indent (int | str | None) –

  • separators (Tuple[str, str] | None) –

  • default (Callable | None) –

  • sort_keys (bool) –

Return type:

str

class sentinelhub.api.batch.process.BatchCollectionBatchData(tiling_grid_id=None, other_data=<factory>)[source]

Bases: object

Dataclass to hold batch collection batchData part of the payload

Parameters:

  • tiling_grid_id (int | None) –

  • other_data (CatchAllVar | None) –

tiling_grid_id: int | None = None
other_data: CatchAllVar | None
dataclass_json_config = {'letter_case': <function camelcase>, 'undefined': Undefined.INCLUDE}
classmethod from_dict(kvs, *, infer_missing=False)
Parameters:

kvs (dict | list | str | int | float | bool | None) –

Return type:

A

classmethod from_json(s, *, parse_float=None, parse_int=None, parse_constant=None, infer_missing=False, **kw)
Parameters:

s (str | bytes | bytearray) –

Return type:

A

classmethod schema(*, infer_missing=False, only=None, exclude=(), many=False, context=None, load_only=(), dump_only=(), partial=False, unknown=None)
Parameters:

  • infer_missing (bool) –

  • many (bool) –

  • partial (bool) –

Return type:

SchemaF[A]

to_dict(encode_json=False)
Return type:

Dict[str, dict | list | str | int | float | bool | None]

to_json(*, skipkeys=False, ensure_ascii=True, check_circular=True, allow_nan=True, indent=None, separators=None, default=None, sort_keys=False, **kw)
Parameters:

  • skipkeys (bool) –

  • ensure_ascii (bool) –

  • check_circular (bool) –

  • allow_nan (bool) –

  • indent (int | str | None) –

  • separators (Tuple[str, str] | None) –

  • default (Callable | None) –

  • sort_keys (bool) –

Return type:

str

class sentinelhub.api.batch.process.BatchCollectionAdditionalData(bands=None, other_data=<factory>)[source]

Bases: object

Dataclass to hold batch collection additionalData part of the payload

Parameters:

  • bands (Dict[str, Any] | None) –

  • other_data (CatchAllVar | None) –

bands: Dict[str, Any] | None = None
other_data: CatchAllVar | None
dataclass_json_config = {'letter_case': <function camelcase>, 'undefined': Undefined.INCLUDE}
classmethod from_dict(kvs, *, infer_missing=False)
Parameters:

kvs (dict | list | str | int | float | bool | None) –

Return type:

A

classmethod from_json(s, *, parse_float=None, parse_int=None, parse_constant=None, infer_missing=False, **kw)
Parameters:

s (str | bytes | bytearray) –

Return type:

A

classmethod schema(*, infer_missing=False, only=None, exclude=(), many=False, context=None, load_only=(), dump_only=(), partial=False, unknown=None)
Parameters:

  • infer_missing (bool) –

  • many (bool) –

  • partial (bool) –

Return type:

SchemaF[A]

to_dict(encode_json=False)
Return type:

Dict[str, dict | list | str | int | float | bool | None]

to_json(*, skipkeys=False, ensure_ascii=True, check_circular=True, allow_nan=True, indent=None, separators=None, default=None, sort_keys=False, **kw)
Parameters:

  • skipkeys (bool) –

  • ensure_ascii (bool) –

  • check_circular (bool) –

  • allow_nan (bool) –

  • indent (int | str | None) –

  • separators (Tuple[str, str] | None) –

  • default (Callable | None) –

  • sort_keys (bool) –

Return type:

str

class sentinelhub.api.batch.process.BatchCollection(name, s3_bucket, additional_data, collection_id=None, user_id=None, created=None, no_data=None, other_data=<factory>)[source]

Bases: BaseCollection

Dataclass for batch collections

Parameters:

  • name (str) –

  • s3_bucket (str) –

  • additional_data (BatchCollectionAdditionalData | None) –

  • collection_id (str | None) –

  • user_id (str | None) –

  • created (datetime | None) –

  • no_data (int | float | None) –

  • other_data (CatchAllVar | None) –

batch_data: BatchCollectionBatchData | None = None
additional_data: BatchCollectionAdditionalData | None = None