sentinelpy

Queries ESA Sentinel APIs for products

Free software: MIT license

Usage

`query_sentinel_hub`

import logging

from sentinelpy import (
    query_sentinel_hub,
    SentinelProductRequestBuilder,
    RequestQueryBuilder,
    PlatformName,
    QuerySentinelProductsResponse
)

request = (
    SentinelProductRequestBuilder()
    .with_username("username")
    .with_password("password")
    .with_query(
        RequestQueryBuilder()
        .platform_name(PlatformName.SENTINEL_1)
    )
    .build()
)

result = query_sentinel_hub(request, log_level=logging.DEBUG)

assert isinstance(result, QuerySentinelProductsResponse)

print(result.status_code)
print(result.body)
print(result.error)

Positional arguments:

sentinel_product_request (SentinelProductRequest)

Request object containing the details of the query. You should use the SentinelProductRequestBuilder to construct

Keyword arguments:

log_level (int)

Level for which to log at use logging to define correct level, defaults to 'INFO'.
logger (logging.Logger)

Logger to use to log messages with, defaults to logging.getLogger(__name__) if no value supplied

Returns: QuerySentinelProductsResponse object

API Documentation

range_value

range_value (`function`)

A helper function for defining range values for queries using the RequestQueryBuilder

Parameters:

start_val (str)

Start of the range
end_val (str)

End of the range

Returns: str range string in format of "[MIN TO MAX]" where MIN is start_val and MAX is end_val

Example

from sentinelpy import (
    RequestQueryBuilder,
    range_value
)

query = (
    RequestQueryBuilder()
    .orbit_number(range_value("1", "2"))
    .build()
)

assert query == "orbitnumber:[1 TO 2]"

SentinelProductRequestBuilder

SentinelProductRequestBuilder (`class`)

Builder resposible for creating SentinelProductRequest objects.

As a minimum, the username and password for the Sentinel Hub should be supplied.

Constructor details

default_query (str): Default value for query, defaults to *
default_rows (int): Default value for rows, defaults to 30
default_order_by (Optional[str]): Default value for order by, defaults to None
default_start (int): Default value for start, defaults to 0

Method details

`build`

Method that constructs the SentinelProductRequest using the values supplied to the builder

Returns: SentinelProductRequest - Built request from input data

Raises: ValueError - if username or password missing

`with_username`

Sets the Sentinel Hub username

Parameter:

username (str)

The username for Sentinel Hub API

Returns: SentinelProductRequestBuilder Builder object with username supplied

`with_password`

Sets the Sentinel Hub password

Parameter:

password (str)

The associated password for the user for the Sentinel Hub API

Returns: SentinelProductRequestBuilder Builder object with password supplied

`with_query`

Sets the query (q) value

Parameter:

query (str or RequestQueryBuilder)

The query to use to filter results. If it is a RequestQueryBuilder, then build will call build on the RequestQueryBuilder before constructing the SentinelProductRequest.

Returns: SentinelProductRequestBuilder Builder object with query supplied

`with_rows`

Sets the rows value

Parameter:

rows (int)

The value for rows to return in each request

Returns: SentinelProductRequestBuilder Builder object with rows supplied

`with_order_by`

Sets the order_by value

Parameter:

order_by (str)

The value for order_by to return in each request

Returns: SentinelProductRequestBuilder Builder object with order_by supplied

`with_start`

Sets the start value

Parameter:

start (int)

The value for start to return in each request

Returns: SentinelProductRequestBuilder Builder object with start supplied

Example usage

from sentinelpy import (
    SentinelProductRequestBuilder,
    SentinelProductRequest,
    RequestQueryBuilder,
    PlatformName,
)

minimal = (
    SentinelProductRequestBuilder()
    .with_username("username")
    .with_password("password")
    .build()
)

assert minimal == SentinelProductRequest(
    query="*",
    rows=None,
    order_by=None,
    start=0,
    username="username",
    password="password"
)

full = (
    SentinelProductRequestBuilder()
    .with_username("username")
    .with_password("password")
    .with_query(
        RequestQueryBuilder()
        .platform_name(PlatformName.SENTINEL_1)
    )
    .with_start(15)
    .with_rows(15)
    .with_order_by('ingestiondate desc')
    .build()
)

assert full == SentinelProductRequest(
    query="platformname:Sentinel-1",
    rows=15,
    order_by='ingestiondate desc',
    start=15,
    username="username",
    password="password"
)

RequestQueryBuilder

RequestQueryBuilder (`class`)

A builder utility to build values for queries. Refer to the Sentinel Hub API documentation for more information about the values. The methods of this class map to search keywords/operators described in the former documentation. The keywords use snake case rather than all lowercase to adhere to Python conventions.

Method details

`build`

Creates the value for query/q using the supplied values. If two non-operators supplied in order without an operator (i.e. and_, or_, or not_) defaults to and_ operator.

If the query has and_ or or_ operators at the start or an operator at the end then these are removed from the query.

Returns: str - the query constructed using the builder, if no methods called returns * by default

Example

from sentinelpy import RequestQueryBuilder, PlatformName

default_build_behaviour = RequestQueryBuilder().build()

assert default_build_behaviour == "*"

hanging_operator_start = RequestQueryBuilder().and_().platform_name(PlatformName.SENTINEL_1).build()

assert hanging_operator_start == "platformname:Sentinel-1"

hanging_operator_end = RequestQueryBuilder().not_().platform_name(PlatformName.SENTINEL_1).and_().build()

assert hanging_operator_end == "NOT platformname:Sentinel-1"

`and_`

Logical and - combines the previous and next clauses i.e. platform_name(X).and_().platform_name(Y) results in the query being platformname:X AND platform_name:Y

Returns: RequestQueryBuilder self

`or_`

Logical or - either the previous or next clauses i.e. platform_name(X).or_().platform_name(Y) results in the query being platformname:X OR platform_name:Y

Returns: RequestQueryBuilder self

`not_`

Negates the following clause.

Returns: RequestQueryBuilder self

`group_`

Creates a grouped clause in the query. If the parameter is a RequestQueryBuilder then it calls the build method before.

Parameter:

inner_query (str or RequestQueryBuilder)

The query that is part of the group.

Returns: RequestQueryBuilder self

Example

from sentinelpy import (
    RequestQueryBuilder,
    PlatformName,
    PolarisationMode
)

q = (
    RequestQueryBuilder()
    .group_(
        RequestQueryBuilder()
        .platform_name(PlatformName.SENTINEL_1)
        .and_()
        .polarisation_mode(PolarisationMode.HH)
    )
    .or_()
    .group_(
        RequestQueryBuilder()
        .platform_name(PlatformName.SENTINEL_1)
        .and_()
        .not_()
        .polarisation_mode(PolarisationMode.VH)
    )
    .build()
)
assert q == (
    "(platformname:Sentinel-1 AND polarisationmode:HH) OR "
    "(platformname:Sentinel-1 AND NOT polarisationmode:VH)"
)

`begin_position`

Sets the beginposition filter between the parameters start/end

Parameters:

begin_position_start (str)

Start of the range that the query is interested in, in ISO date/time stamp with millis, or relative to NOW (e.g. NOW/NOW-1DAY etc.)
begin_position_end (str)

End of the range that the query is interested in, in ISO date/time stamp with millis, or relative to NOW (e.g. NOW/NOW-1DAY etc.)

Returns: RequestQueryBuilder self

Raises: ValueError - if begin_position_start or begin_position_end are not valid, i.e not ISO or relative date

`cloud_cover_percentage`

The range of acceptable values for cloud cover percentage as per Sentinel Dataset

Parameter:

percentage (int or string)

The percentage value or range (the format of MIN TO MAX where MIN is lowest acceptable and MAX is upper limit) of limit for Cloud Cover Percentage

Returns: RequestQueryBuilder self

Raises: ValueError if the value is not an integer or valid percentage or range

`collection`

Set the value for collection. Used to specify the name of a predefined collection of products

Parameter:

collection (str)

Value for collection

Returns: RequestQueryBuilder self

Raises: ValueError if supplied string is empty i.e. '' or just whitespace

`end_position`

Set a filter on the range for endposition (that is Sensing Stop Time) that the query is interested in.

Parameter:

end_position_start (str)

Start of the period, in ISO date/time stamp with millis, or relative to NOW (e.g. NOW/NOW-1DAY etc.)
end_position_end (str)

End of the period, in ISO date/time stamp with millis, or relative to NOW (e.g. NOW/NOW-1DAY etc.)

Returns: RequestQueryBuilder self

Raises: ValueError - if end_position_start or end_position_end are not valid, i.e not ISO or relative date

`file_name`

Sets a filter on product filename.

Parameter:

filename (str)

Name of the product file to filter results by

Returns: RequestQueryBuilder self

Raises: ValueError if supplied string is empty i.e. '' or just whitespace

`footprint`

Sets a filter on geographic area that the query is interested in. Can use either a simple bounding box described as a WKT Polygon or a point described by a Latitude Longitude pair. Refer to the Sentinel Hub documentation for in depth information about footprint.

Parameter:

geographic_type (str)

The Area of Interest for the query. Can either be a point (lat/lon pair e.g. "0.000, 1.000") or a Polygon (WKT polygon without cut outs, e.g. POLYGON ((30 10, 40 40, 20 40, 10 20, 30 10)))

Can have the Intersects() or can be just the coordinate pair or Polygon

Returns: RequestQueryBuilder self

Raises: ValueError if not valid WKT Polygon or point

`ingestion_date`

Sets a filter on the date the Sentinel product was ingested using the supplied range.

Parameter:

ingestion_date_start (str)

Start of the period, in ISO date/time stamp with millis, or relative to NOW (e.g. NOW/NOW-1DAY etc.)
ingestion_date_end (str)

End of the period, in ISO date/time stamp with millis, or relative to NOW (e.g. NOW/NOW-1DAY etc.)

Returns: RequestQueryBuilder self

Raises: ValueError - if ingestion_date_start or ingestion_date_end are not valid, i.e not ISO or relative

`last_orbit_number`

Sets on a filter on the last orbit number or range range of last orbit numbers (i.e [MIN TO MAX] whereby MIN is the lowest last orbit number and MAX is highest).

Parameter:

orbit_number (str or int)

The orbit number or range that should be used. Can be a single value i.e. 1234 or a range such as [1234 TO 4321] must be between 0 and 999999

Returns: RequestQueryBuilder self

Raises: ValueError if value is not a valid number or range

`last_relative_orbit_number`

Sets a filter on the last orbit number or range range of last orbit numbers (i.e [MIN TO MAX] whereby MIN is the lowest last orbit number and MAX is highest). Relative orbit number of the oldest line within the image data (the start of the product) and relative orbit number of the most recent line within the image data (the end of the product), respectively.

Parameter:

orbit_number (str or int)

The orbit number or range that should be used. Can be a single value i.e. 1234 or a range such as [1234 TO 4321] must be between 0 and 175

Returns: RequestQueryBuilder self

Raises: ValueError if value is not a valid number or range

`orbit_direction`

Sets a filter on the orbit direction for the oldest data in the product

Parameter:

orbit_direction (OrbitDirection)

Direction that the query is interested in

Returns: RequestQueryBuilder self

`orbit_number`

Sets a filter on the orbit number or range range of orbit numbers (i.e [MIN TO MAX] whereby MIN is the lowest orbit number and MAX is highest).

Parameter:

orbit_number (str or int)

The orbit number or range that should be used. Can be a single value i.e. 1234 or a range such as [1234 TO 4321]. must be between 0 and 999999

Returns: RequestQueryBuilder self

Raises: ValueError if value is not a valid number or range

`platform_name`

Sets a filter on the platform name

Parameter:

platform_name (PlatformName)

The platform name to filter the results by

Returns: RequestQueryBuilder self

`polarisation_mode`

Sets a filter on polarisation mode.

Parameter:

polarisation_mode (PolarisationMode)

Specified value for polarisation_mode

Returns: RequestQueryBuilder self

`product_type`

Sets a filter on product type. Note the valid combinations with platform_name

Parameter:

product_type (Sentinel1ProductType or Sentinel2ProductType or Sentinel3ProductType or Sentinel5PProductType)

Specified value for product type to filter the results on

Returns: RequestQueryBuilder self

`relative_orbit_number`

Set filter on relative orbit number of the oldest line within the image data (the start of the product).

Parameter:

orbit_number (str or int)

The orbit number or range that should be used. Can be a single value i.e. 123 or a range such as [123 TO 124]. must be between 0 and 175

Returns: RequestQueryBuilder self

Raises: ValueError if value is not a valid number or range

`sensor_operational_mode`

Set filter on sensor operational mode

Parameter:

sensor_operational_mode (SensorOperationalMode)

The value to filter products on

Returns: RequestQueryBuilder self

`swath_identifier`

Search all valid swath identifiers for the Sentinel-1 SAR instrument. The S1-S6 swaths apply to SM products, the IW and IW1-3 swaths apply to IW products (IW is used for detected IW products where the 3 swaths are merged into one image), the EW and EW1-5 swaths apply to EW products (EW is used for detected EW products where the 5 swaths are merged into one image).

Parameter:

swath_identifier (SwathIdentifier)

Swath Identifier to filter products with

Returns: RequestQueryBuilder self

`timeliness`

Filter sentinel products on timeliness

Parameter:

timeliness (Timeliness)

Value of timeliness that the query is interested in

Returns: RequestQueryBuilder self

Example

from sentinelpy import RequestQueryBuilder, PlatformName

simple_q = (
    RequestQueryBuilder()
    .platform_name(PlatformName.SENTINEL_1)
    .build()
)

assert simple_q == "platformname:Sentinel-1"

multiple_clauses_q = (
    RequestQueryBuilder()
        .platform_name(PlatformName.SENTINEL_3)
        .and_()
        .cloud_cover_percentage("[0 TO 5]")
        .and_()
        .footprint(
            "POLYGON((-4.53 29.85, 26.75 29.85, 26.75 46.80,-4.53 46.80,-4.53 29.85))"
        )
        .build()
)

assert multiple_clauses_q == (
    'platformname:Sentinel-3 AND cloudcoverpercentage:[0 TO 5] AND '
    'footprint:"Intersects(POLYGON((-4.53 29.85, 26.75 29.85, 26.75 46.'
    '80,-4.53 46.80,-4.53 29.85)))"'
)

SentinelProductRequest

SentinelProductRequest (`NamedTuple`/`class`)

Named Tuple representing a request. Best practice would be to use the builders (SentinelProductRequestBuilder and RequestQueryBuilder) to derive.

Properties:

query (str)

Query string value for 'q' in the request. Sentinel hub documentation. This can be constructed using the RequestQueryBuilder.
rows (int)

Number of rows to return from the API Reference to documentation
order_by (Optional[str])

Field to order the results on Reference to documentation
start (int)

Start position of the records to return Reference to documentation
username (str)

Valid username to use to authenticate with the Sentinel Hub API
password (str)

Valid password to use to authenticate with the Sentinel Hub API

QuerySentinelProductsResponse

QuerySentinelProductsResponse (`NamedTuple`/`class`)

Represents the result from the Sentinel Hub API

Can be interacted with as an object or in a more functional style using the 'on' methods (on_success/on_failure).

Property Details

status_code (Optional[int])

The HTTP Status code representing the outcome of the query
body (Optional[Dict[str, Any]])

The resulting data from the Sentinel Hub
error (Optional[BaseException])

An error object if there was an error or exception raised
success (bool)

Whether or not the query was successful

Method details

`raise_error`

If encountered an error raise error encountered. Otherwise do nothing

Situations this would be useful:

Prevent exceptions being swallowed
You prefer to handle exception rather than checking if value is None

Returns: None

Raises: Error that was encountered when querying the API

`on_success`

A functional style method for handling successful results. When the action was successful, calls the supplied function with data from Sentinel Hub API and returns the QuerySentinelProductsResponse so that other methods can be chained

Parameters:

callback: (Callable[[Dict[str, Any]], None])

Function which defines the successful behaviour

Returns: QuerySentinelProductsResponse self

`on_failure`

A functional style method for handling cases where the API was not reachable or there was an error either in the response or parsing the response, i.e. the request was not successful.

Parameters:

callback: (Callable[[QuerySentinelProductsResponse], None])

Function which defines the failure behaviour, which will be called with named tuple representing the result

Returns: QuerySentinelProductsResponse self

Example

from sentinelpy import QuerySentinelProductsResponse

# You can use the attributes of the response in a more object fashion
# Successful response:
successful_response = QuerySentinelProductsResponse(200, {})

assert successful_response.success
assert successful_response.status_code == 200
assert successful_response.body == {}
assert successful_response.error is None

# Failed response:
failed_response = QuerySentinelProductsResponse(400, {})
assert not failed_response.success
assert failed_response.status_code == 400
assert failed_response.body == {}
assert failed_response.error is None

# Erroneous response
erroneous_response = QuerySentinelProductsResponse(None, None, IOError())
assert not erroneous_response.success
assert erroneous_response.status_code is None
assert erroneous_response.body is None
assert isinstance(erroneous_response.error, IOError)

# Using the functional style methods
successful_response.on_success(
    lambda data: print(f'success:{data}')
).on_failure(
    lambda failure_response: print(f'failure:{failure_response.status_code}')
) # success:{}

failed_response.on_success(
    lambda data: print(f'success:{data}')
).on_failure(
    lambda failure_response: print(f'failure:{failure_response.status_code}')
) # failure:400

Enumerations

In order to simplify validation there are some Enumerations representing some of the types in the RequestQueryBuilder, each valid option maps to a value defined by the API. Refer to the Sentinel Hub API documentation for more information about the values

The enumerations are as follows:

OrbitDirection
PlatformName
PolarisationMode
ProductType
SensorOperationalMode
Sentinel1ProductType
Sentinel2ProductType
Sentinel3ProductType
Sentinel5PProductType
SwathIdentifier
Timeliness

Features

Queries the Sentinel Hub for products
Define your requests using the RequestQueryBuilder and SentinelProductRequestBuilder objects

Development Documentation

Built using Poetry.

poetry install

To install the library locally from source

Credits

This package was created with Cookiecutter and the UKHO/cookiecutter-pypackage project template.

Cookiecutter: https://github.com/cookiecutter/cookiecutter
UKHO/cookiecutter-pypackage: https://github.com/UKHO/cookiecutter-pypackage

Name		Name	Last commit message	Last commit date
Latest commit History 85 Commits
.github		.github
sentinelpy		sentinelpy
tests		tests
.editorconfig		.editorconfig
.flake8		.flake8
.gitignore		.gitignore
AUTHORS.md		AUTHORS.md
CODEOWNERS		CODEOWNERS
CONTRIBUTING.md		CONTRIBUTING.md
HISTORY.md		HISTORY.md
LICENSE		LICENSE
Makefile		Makefile
README.md		README.md
liccheck.ini		liccheck.ini
poetry.lock		poetry.lock
pyproject.toml		pyproject.toml
tox.ini		tox.ini

License

UKHO/sentinelpy

Folders and files

Latest commit

History

Repository files navigation

sentinelpy

Usage

query_sentinel_hub

API Documentation

range_value (function)

Example

SentinelProductRequestBuilder (class)

build

with_username

with_password

with_query

with_rows

with_order_by

with_start

RequestQueryBuilder (class)

build

and_

or_

not_

group_

begin_position

cloud_cover_percentage

collection

end_position

file_name

footprint

ingestion_date

last_orbit_number

last_relative_orbit_number

orbit_direction

orbit_number

platform_name

polarisation_mode

product_type

relative_orbit_number

sensor_operational_mode

swath_identifier

timeliness

SentinelProductRequest (NamedTuple/class)

Properties:

QuerySentinelProductsResponse (NamedTuple/class)

raise_error

on_success

on_failure

Features

Development Documentation

Credits

About

Topics

Resources

License

Stars

Watchers

Forks

Releases 1

Contributors 4

Languages

`query_sentinel_hub`

range_value (`function`)

SentinelProductRequestBuilder (`class`)

`build`

`with_username`

`with_password`

`with_query`

`with_rows`

`with_order_by`

`with_start`

RequestQueryBuilder (`class`)

`build`

`and_`

`or_`

`not_`

`group_`

`begin_position`

`cloud_cover_percentage`

`collection`

`end_position`

`file_name`

`footprint`

`ingestion_date`

`last_orbit_number`

`last_relative_orbit_number`

`orbit_direction`

`orbit_number`

`platform_name`

`polarisation_mode`

`product_type`

`relative_orbit_number`

`sensor_operational_mode`

`swath_identifier`

`timeliness`

SentinelProductRequest (`NamedTuple`/`class`)

QuerySentinelProductsResponse (`NamedTuple`/`class`)

`raise_error`

`on_success`

`on_failure`