sentinelhub_batch

Module implementing an interface with Sentinel Hub Batch service

class sentinelhub.sentinelhub_batch.SentinelHubBatch(config=None, base_url=None)[source]

Bases: sentinelhub.sh_utils.SentinelHubService

An interface class for Sentinel Hub Batch API

For more info check Batch API reference.

Parameters:
  • config (SHConfig or 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.
  • base_url (str or None) – A deprecated parameter. Use config instead.
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 or dict) – 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) – A dictionary with tiling grid parameters. It can be built with tiling_grid method
  • output (dict or None) – A dictionary with output parameters. It can be built with output method. Alternatively, one can set bucket_name parameter instead.
  • bucket_name (str or None) – A name of an s3 bucket where to save data. Alternatively, one can set output parameter to specify more output parameters.
  • description (str or None) – A description of a batch request
  • kwargs – 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 or int) – A grid resolution
  • buffer ((int, int) or 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 other arguments to be added to a dictionary of parameters
Returns:

A dictionary with parameters

Return type:

dict

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 or None) – A path or a template on an s3 bucket where to store results. More info at Batch API documentation
  • overwrite (bool or None) – A flag specifying if a request should overwrite existing outputs without failing
  • skip_existing (bool or None) – A flag specifying if existing outputs should be overwritten
  • cog_output (bool or None) – A flag specifying if outputs should be written in COGs (cloud-optimized GeoTIFFs )or normal GeoTIFFs
  • cog_parameters (dict or None) – A dictionary specifying COG creation parameters
  • create_collection (bool or None) – If True the results will be written in COGs and a batch collection will be created
  • collection_id (str or None) – If True results will be added to an existing collection
  • responses (list or None) – Specification of path template for individual outputs/responses
  • kwargs – Any other arguments to be added to a dictionary of parameters
Returns:

A dictionary of output parameters

Return type:

dict

iter_tiling_grids(**kwargs)[source]

An iterator over tiling grids

Batch API reference

Parameters:kwargs – Any other request query parameters
Returns:An iterator over tiling grid definitions
Return type:Iterator[dict]
get_tiling_grid(grid_id)[source]

Provides a single tiling grid

Batch API reference

Parameters:grid_id (str or int) – An ID of a requested tiling grid
Returns:A tiling grid definition
Return type:dict
iter_requests(user_id=None, search=None, sort=None, **kwargs)[source]

Iterate existing batch requests

Batch API reference

Parameters:
  • user_id (str or None) – Filter requests by a user id who defined a request
  • search (str or None) – A search query to filter requests
  • sort (str or None) – A sort query
  • kwargs – 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
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 (BatchRequest or dict or str) – It could be a batch request object, a raw batch request payload or only a batch request ID.
  • output (dict or None) – A dictionary with output parameters to be updated.
  • description (str or None) – A description of a batch request to be updated.
  • kwargs – Any other arguments to be added to a dictionary of parameters.
delete_request(batch_request)[source]

Delete a batch job request

Batch API reference

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

Starts analysis of a batch job request

Batch API reference

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

Starts running a batch job

Batch API reference

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

Cancels a batch job

Batch API reference

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

Restarts only those parts of a job that failed

Batch API reference

Parameters:batch_request (BatchRequest or dict or str) – It could be a batch request object, a raw batch request payload or only a batch request ID.
iter_tiles(batch_request, status=None, **kwargs)[source]

Iterate over info about batch request tiles

Batch API reference

Parameters:
  • batch_request (BatchRequest or dict or str) – It could be a batch request object, a raw batch request payload or only a batch request ID.
  • status (BatchTileStatus or str or None) – A filter to obtain only tiles with a certain status
  • kwargs – Any additional parameters to include in a request query
Returns:

An iterator over information about each tile

Return type:

Iterator[dict]

get_tile(batch_request, tile_id)[source]

Provides information about a single batch request tile

Batch API reference

Parameters:
  • batch_request (BatchRequest or dict or str) – It could be a batch request object, a raw batch request payload or only a batch request ID.
  • tile_id (int or None) – An ID of a tile
Returns:

Information about a tile

Return type:

dict

reprocess_tile(batch_request, tile_id)[source]

Reprocess a single failed tile

Batch API reference

Parameters:
  • batch_request (BatchRequest or dict or str) – It could be a batch request object, a raw batch request payload or only a batch request ID.
  • tile_id (int or None) – An ID of a tile
iter_collections(search=None, **kwargs)[source]

Iterate over batch collections

Batch API reference

Parameters:
  • search (str or None) – A search query to filter collections
  • kwargs – Any additional parameters to include in a request query
Returns:

An iterator over existing batch collections

Return type:

Iterator[dict]

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
create_collection(collection)[source]

Create a new batch collection

Batch API reference

Parameters:collection (BatchCollection or dict) – Batch collection definition
Returns:A dictionary of a newly created collection
Return type:dict
update_collection(collection)[source]

Update an existing batch collection

Batch API reference

Parameters:collection (BatchCollection or dict) – Batch collection definition
delete_collection(collection)[source]

Delete an existing batch collection

Batch API reference

Parameters:collection (str or BatchCollection) – Batch collection id or object
class sentinelhub.sentinelhub_batch.BatchRequestStatus[source]

Bases: enum.Enum

An enum class with all possible batch request statuses

class sentinelhub.sentinelhub_batch.BatchTileStatus[source]

Bases: enum.Enum

An enum class with all possible batch tile statuses

class sentinelhub.sentinelhub_batch.BatchUserAction[source]

Bases: enum.Enum

An enum class with all possible batch user actions

class sentinelhub.sentinelhub_batch.BatchRequest(request_id: str, process_request: dict, other_data: Optional[CatchAllVar], user_id: Optional[str] = None, created: Optional[datetime.datetime] = None, tiling_grid: Optional[dict] = None, output: Optional[dict] = None, bucket_name: Optional[str] = None, description: Optional[str] = None, value_estimate: Optional[float] = None, tile_count: Optional[int] = None, tile_width_px: Optional[int] = None, tile_height_px: Optional[int] = None, user_action: Optional[sentinelhub.sentinelhub_batch.BatchUserAction] = None, user_action_updated: Optional[str] = None, status: Optional[sentinelhub.sentinelhub_batch.BatchRequestStatus] = None, error: Optional[str] = None)[source]

Bases: object

A dataclass object that holds information about a batch request

evalscript

Provides an evalscript used by a batch request

Returns:An evalscript
Return type:str
bbox

Provides a bounding box used by a batch request

Returns:An area bounding box together with CRS
Return type:BBox
Raises:ValueError
geometry

Provides a geometry used by a batch request

Returns:An area geometry together with CRS
Return type:Geometry
Raises:ValueError
raise_for_status(status=<BatchRequestStatus.FAILED: 'FAILED'>)[source]

Raises an error in case batch request has a given status

Parameters:status (str or list(str) or BatchRequestStatus or list(BatchRequestStatus)) – One or more status codes on which to raise an error. The default is ‘FAILED’.
Raises:RuntimeError
class sentinelhub.sentinelhub_batch.BatchCollectionBatchData(other_data: Optional[CatchAllVar], tiling_grid_id: Optional[int] = None)[source]

Bases: object

Dataclass to hold batch collection batchData part of the payload

class sentinelhub.sentinelhub_batch.BatchCollectionAdditionalData(other_data: Optional[CatchAllVar], bands: Optional[dict] = None)[source]

Bases: object

Dataclass to hold batch collection additionalData part of the payload

class sentinelhub.sentinelhub_batch.BatchCollection(name: str, s3_bucket: str, other_data: Optional[CatchAllVar], collection_id: Optional[str] = None, user_id: Optional[str] = None, created: Optional[datetime.datetime] = None, no_data: Union[int, float, None] = None)[source]

Bases: sentinelhub.sh_utils.BaseCollection

Dataclass for batch collections

to_data_collection()

Returns a DataCollection enum for this collection

sentinelhub.sentinelhub_batch.monitor_batch_job(batch_request, config, sleep_time=120, analysis_sleep_time=10)[source]

A utility function that keeps checking for number of processed tiles until the given batch request finishes. During the process it shows a progress bar and at the end it reports information about finished and failed tiles.

Notes:

  • Before calling this function make sure to start a batch job by calling SentinelHubBatch.start_job method. In case a batch job is still being analysed this function will wait until the analysis ends.
  • This function will be continuously collecting tile information from Sentinel Hub service. To avoid making too many requests please make sure to adjust sleep_time parameter according to the size of your job. Larger jobs don’t need too frequent tile status updates.
  • Some information about the progress of this function is reported to logging level INFO.
Parameters:
  • batch_request (BatchRequest or dict or str.) – An object with information about a batch request. Alternatively, it could only be a batch request id or a payload.
  • config (SHConfig or 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 where Batch API will be called.
  • sleep_time (int) – Number of seconds to sleep between consecutive progress bar updates.
  • analysis_sleep_time (int) – Number of seconds between consecutive status updates during analysis phase.
Returns:

A dictionary mapping a tile status to a list of tile payloads.

Return type:

defaultdict(BatchTileStatus, list(dict))