sentinelhub.api.batch.process_v2

Module implementing an interface with Batch Process V2.

class sentinelhub.api.batch.process_v2.BatchProcessClient(config=None)[source]

Bases: BaseBatchClient

An interface class for Sentinel Hub Batch API version 2.

Batch Process API

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.

static s3_specification(url, access_key=None, secret_access_key=None, iam_role_arn=None, region=None)

A helper method to build a dictionary used for specifying S3 paths. Consult the access documentation for more information.

In general either use iam_role_arn or access_key plus secret_access_key.

Parameters:

  • url (str) – A URL pointing to an S3 bucket or an object in an S3 bucket.

  • access_key (str | None) – AWS access key that allows programmatic access to the S3 bucket specified in the url field.

  • secret_access_key (str | None) – AWS secret access key which must correspond to the AWS access key.

  • iam_role_arn (str | None) – IAM role ARN, which allows programmatic access to the S3 bucket specified in the url field using the recommended assume IAM role flow.

  • region (str | None) – The region where the S3 bucket is located. If omitted, the region of the Sentinel Hub deployment that the request is submitted to is assumed.

Returns:

A dictionary of S3 specifications used by the Batch Statistical API

Return type:

AccessSpecification

create(process_request, input, output, instance_type='normal', description=None, **kwargs)[source]

Create a new batch request

Batch Process V2

Parameters:

  • process_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

  • input (Dict[str, Any]) – A dictionary with input parameters. It can be built with tiling_grid_input or geopackage_input methods.

  • output (Dict[str, Any]) – A dictionary with output parameters. It can be built with raster_output or zarr_output methods.

  • instance_type" – Specifies which size of instances to use for the request.

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

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

  • instance_type (Literal['normal', 'large']) –

Return type:

BatchProcessRequest

static geopackage_input(geopackage_specification)[source]

A helper method to build a suitable dictionary for the input field.

Parameters:

geopackage_specification (AccessSpecification) – A specification of the S3 path for the Geopackage. Can be built using the s3_specification helper method.

Return type:

Dict[str, Any]

static tiling_grid_input(grid_id, resolution, buffer_x=None, buffer_y=None, **kwargs)[source]

A helper method to build a dictionary with tiling grid parameters for the input field.

Parameters:

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

  • resolution (float) – A grid resolution

  • buffer_x (int | None) – Will expand each output tile horizontally (left and right) by specified number of pixels.

  • buffer_y (int | None) – Will expand each output tile vertically (up and down) by specified number of pixels.

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

Return type:

Dict[str, Any]

static raster_output(delivery, *, overwrite=None, skip_existing=None, cog_output=None, cog_parameters=None, create_collection=None, collection_id=None, **kwargs)[source]

A helper method to build a dictionary specifying raster output

Parameters:

  • delivery (AccessSpecification) – An S3 access specification containing a path or a template on an s3 bucket where to store results. You can use the s3_specification method for construction. For more information on templates see 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. See documentation for more info.

  • 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

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

Return type:

Dict[str, Any]

static zarr_output(delivery, *, group=None, array_parameters=None, array_overrides=None, **kwargs)[source]

A helper method to build a dictionary specifying Zarr output. See documentation for more information on each parameter.

Batch Process V2

Parameters:

  • delivery (AccessSpecification) – An S3 access specification containing a path or a template on an s3 bucket where to store results. You can use the s3_specification method for construction. For more information on templates see documentation.

  • group (Dict[str, Any] | None) – Zarr group level parameters

  • array_parameters (Dict[str, Any] | None) – Parameters that will be used for all output arrays, except where overriden with array_overrides. Required unless array_overrides includes all required fields for all output arrays.

  • array_overrides (Dict[str, Any] | None) – Overrides the values of array_arameters for individual arrays.

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

Return type:

Dict[str, Any]

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

Iterate existing batch requests

Batch Process V2

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[BatchProcessRequest]

get_request(batch_request)[source]

Collects information about a single batch request.

Batch Process V2

Parameters:

batch_request (str | dict | BatchProcessRequest) –

Return type:

BatchProcessRequest

update_request(batch_request, description)[source]

Update certain batch job request parameters. Can only update requests that are not currently being processed.

Batch Process V2

Parameters:

  • batch_request (str | dict | BatchProcessRequest) – Batch request ID, a dictionary containing an “ID” field, or a BatchProcessRequest.

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

Return type:

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

start_analysis(batch_request)[source]

Starts analysis of a batch job request

Parameters:

batch_request (str | dict | BatchProcessRequest) – Batch request ID, a dictionary containing an “ID” field, or a BatchProcessRequest.

Return type:

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

start_job(batch_request)[source]

Starts running a batch job

Parameters:

batch_request (str | dict | BatchProcessRequest) – Batch request ID, a dictionary containing an “ID” field, or a BatchProcessRequest.

Return type:

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

stop_job(batch_request)[source]

Stops a batch job

Parameters:

batch_request (str | dict | BatchProcessRequest) – Batch request ID, a dictionary containing an “ID” field, or a BatchProcessRequest.

Return type:

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

iter_tiling_grids(**kwargs)[source]

An iterator over tiling grids

Batch Process V2

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 Process V2

Parameters:

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

Returns:

A tiling grid definition

Return type:

Dict[str, Any]

class sentinelhub.api.batch.process_v2.BatchProcessRequest(request_id, request, domain_account_id, status, error=None, user_action=None, user_action_updated=None, created=None, completion_percentage=0, last_updated=None, cost_PU=None, stopped_status_reason=None, other_data=<factory>)[source]

Bases: BaseBatchRequest

A dataclass object that holds information about a batch request

Parameters:

  • request_id (str) –

  • request (dict) –

  • domain_account_id (str) –

  • status (BatchRequestStatus) –

  • error (str | None) –

  • user_action (BatchUserAction | None) –

  • user_action_updated (datetime | None) –

  • created (datetime | None) –

  • completion_percentage (float) –

  • last_updated (datetime | None) –

  • cost_PU (float | None) –

  • stopped_status_reason (StoppedStatusReason | None) –

  • other_data (CatchAllVar | None) –

request_id: str
request: dict
domain_account_id: str
status: BatchRequestStatus
error: str | None = None
user_action: BatchUserAction | None = None
user_action_updated: datetime | None = None
created: datetime | None = None
completion_percentage: float = 0
last_updated: datetime | None = None
cost_PU: float | None = None
stopped_status_reason: StoppedStatusReason | None = None
other_data: CatchAllVar | None
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