sentinelhub.api.batch.process

Module implementing an interface with Sentinel Hub Batch Processing API.

class sentinelhub.api.batch.process.BatchTileStatus(value)[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 – 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 (Union[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 (Optional[Dict[str, Any]]) – A dictionary with output parameters. It can be built with output method. Alternatively, one can set bucket_name parameter instead.

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

  • description (Optional[str]) – 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 (Optional[Tuple[int, int]]) – 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 (Optional[str]) – A path or a template on an s3 bucket where to store results. More info at Batch API documentation

  • overwrite (Optional[bool]) – A flag specifying if a request should overwrite existing outputs without failing

  • skip_existing (Optional[bool]) – A flag specifying if existing outputs should be overwritten

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

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

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

  • collection_id (Optional[str]) – If True results will be added to an existing collection

  • responses (Optional[List[str]]) – 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 (Union[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 (Optional[str]) – Filter requests by a user id who defined a request

  • search (Optional[str]) – A search query to filter requests

  • sort (Optional[str]) – 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 (Union[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 (Union[str, dict, BatchRequest]) – It could be a batch request object, a raw batch request payload or only a batch request ID.

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

  • description (Optional[str]) – A description of a batch request to be updated.

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

Return type

Optional[Union[Dict[str, Any], list, str, float, int]]

delete_request(batch_request)[source]

Delete a batch job request

Batch API reference

Parameters

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

Return type

Optional[Union[Dict[str, Any], list, str, float, int]]

start_analysis(batch_request)[source]

Starts analysis of a batch job request

Batch API reference

Parameters

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

Return type

Optional[Union[Dict[str, Any], list, str, float, int]]

start_job(batch_request)[source]

Starts running a batch job

Batch API reference

Parameters

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

Return type

Optional[Union[Dict[str, Any], list, str, float, int]]

cancel_job(batch_request)[source]

Cancels a batch job

Batch API reference

Parameters

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

Return type

Optional[Union[Dict[str, Any], list, str, float, int]]

restart_job(batch_request)[source]

Restarts only those parts of a job that failed

Batch API reference

Parameters

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

Return type

Optional[Union[Dict[str, Any], list, str, float, int]]

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

Iterate over info about batch request tiles

Batch API reference

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

  • status (Union[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 (Union[str, dict, BatchRequest]) – It could be a batch request object, a raw batch request payload or only a batch request ID.

  • tile_id (Optional[int]) – An ID of a tile

Returns

Information about a tile

Return type

Dict[str, Any]

reprocess_tile(batch_request, tile_id)[source]

Reprocess a single failed tile

Batch API reference

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

  • tile_id (Optional[int]) – An ID of a tile

Return type

Optional[Union[Dict[str, Any], list, str, float, int]]

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

Iterate over batch collections

Batch API reference

Parameters
  • search (Optional[str]) – 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 (Union[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 (Union[BatchCollection, dict]) – Batch collection definition

Return type

Optional[Union[Dict[str, Any], list, str, float, int]]

delete_collection(collection)[source]

Delete an existing batch collection

Batch API reference

Parameters

collection (Union[str, dict, BatchCollection]) – Batch collection id or object

Return type

Optional[Union[Dict[str, Any], list, str, float, int]]

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: Optional[str] = None
created: Optional[datetime] = None
tiling_grid: dict
output: dict
bucket_name: Optional[str] = None
description: Optional[str] = None
value_estimate: Optional[float] = None
tile_width_px: Optional[int] = None
tile_height_px: Optional[int] = None
user_action: Optional[BatchUserAction] = None
user_action_updated: Optional[str] = None
error: Optional[str] = None
other_data: Optional[CatchAllVar]
property evalscript: str

Provides an evalscript used by a batch request

Returns

An evalscript

property bbox: BBox

Provides a bounding box used by a batch request

Returns

An area bounding box together with CRS

Raises

ValueError

property geometry: Geometry

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 (Optional[Union[dict, list, str, int, float, bool]]) –

Return type

A

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

s (Union[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, Optional[Union[dict, list, str, int, float, bool]]]

to_json(*, skipkeys=False, ensure_ascii=True, check_circular=True, allow_nan=True, indent=None, separators=None, default=None, sort_keys=False, **kw)
Parameters
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: Optional[int] = None
other_data: Optional[CatchAllVar]
dataclass_json_config = {'letter_case': <function camelcase>, 'undefined': Undefined.INCLUDE}
classmethod from_dict(kvs, *, infer_missing=False)
Parameters

kvs (Optional[Union[dict, list, str, int, float, bool]]) –

Return type

A

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

s (Union[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, Optional[Union[dict, list, str, int, float, bool]]]

to_json(*, skipkeys=False, ensure_ascii=True, check_circular=True, allow_nan=True, indent=None, separators=None, default=None, sort_keys=False, **kw)
Parameters
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: Optional[Dict[str, Any]] = None
other_data: Optional[CatchAllVar]
dataclass_json_config = {'letter_case': <function camelcase>, 'undefined': Undefined.INCLUDE}
classmethod from_dict(kvs, *, infer_missing=False)
Parameters

kvs (Optional[Union[dict, list, str, int, float, bool]]) –

Return type

A

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

s (Union[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, Optional[Union[dict, list, str, int, float, bool]]]

to_json(*, skipkeys=False, ensure_ascii=True, check_circular=True, allow_nan=True, indent=None, separators=None, default=None, sort_keys=False, **kw)
Parameters
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
batch_data: Optional[BatchCollectionBatchData] = None
additional_data: Optional[BatchCollectionAdditionalData] = None