API Reference¶
-
class
SentinelAPI
(user, password, api_url='https://apihub.copernicus.eu/apihub/', show_progressbars=True, timeout=60)[source]¶ Class to connect to Copernicus Open Access Hub, search and download imagery.
Parameters: - user (string) – username for DataHub set to None to use ~/.netrc
- password (string) – password for DataHub set to None to use ~/.netrc
- api_url (string, optional) – URL of the DataHub defaults to ‘https://apihub.copernicus.eu/apihub’
- show_progressbars (bool) – Whether progressbars should be shown or not, e.g. during download. Defaults to True.
- timeout (float or tuple, default 60) – How long to wait for DataHub response (in seconds). Tuple (connect, read) allowed. Set to None to wait indefinitely.
-
session
¶ Session to connect to DataHub
Type: requests.Session
-
api_url
¶ URL to the DataHub
Type: str
-
page_size
¶ Number of results per query page. Current value: 100 (maximum allowed on ApiHub)
Type: int
-
timeout
¶ How long to wait for DataHub response (in seconds).
Type: float or tuple
-
logger
= <Logger sentinelsat.SentinelAPI (WARNING)>¶
-
concurrent_dl_limit
¶ Maximum number of concurrent downloads allowed by the server.
Type: int
-
concurrent_lta_trigger_limit
¶ Maximum number of concurrent Long Term Archive retrievals allowed.
Type: int
-
dl_retry_delay
¶ Number of seconds to wait between retrying of failed downloads.
Type: float, default 10
-
lta_retry_delay
¶ Number of seconds to wait between requests to the Long Term Archive.
Type: float, default 60
-
lta_timeout
¶ Maximum number of seconds to wait for triggered products to come online. Defaults to no timeout.
Type: float, optional
-
dl_limit_semaphore
¶
-
lta_limit_semaphore
¶
-
dhus_version
¶
-
query
(area=None, date=None, raw=None, area_relation='Intersects', order_by=None, limit=None, offset=0, **keywords)[source]¶ Query the OpenSearch API with the coordinates of an area, a date interval and any other search keywords accepted by the API.
Parameters: - area (str, optional) – The area of interest formatted as a Well-Known Text string.
- date (tuple of (str or datetime) or str, optional) –
A time interval filter based on the Sensing Start Time of the products. Expects a tuple of (start, end), e.g. (“NOW-1DAY”, “NOW”). The timestamps can be either a Python datetime or a string in one of the following formats:
- yyyyMMdd
- yyyy-MM-ddThh:mm:ss.SSSZ (ISO-8601)
- yyyy-MM-ddThh:mm:ssZ
- NOW
- NOW-<n>DAY(S) (or HOUR(S), MONTH(S), etc.)
- NOW+<n>DAY(S)
- yyyy-MM-ddThh:mm:ssZ-<n>DAY(S)
- NOW/DAY (or HOUR, MONTH etc.) - rounds the value to the given unit
Alternatively, an already fully formatted string such as “[NOW-1DAY TO NOW]” can be used as well.
- raw (str, optional) – Additional query text that will be appended to the query.
- area_relation ({'Intersects', 'Contains', 'IsWithin'}, optional) –
What relation to use for testing the AOI. Case insensitive.
- Intersects: true if the AOI and the footprint intersect (default)
- Contains: true if the AOI is inside the footprint
- IsWithin: true if the footprint is inside the AOI
- order_by (str, optional) – A comma-separated list of fields to order by (on server side). Prefix the field name by ‘+’ or ‘-’ to sort in ascending or descending order, respectively. Ascending order is used if prefix is omitted. Example: “cloudcoverpercentage, -beginposition”.
- limit (int, optional) – Maximum number of products returned. Defaults to no limit.
- offset (int, optional) – The number of results to skip. Defaults to 0.
- **keywords – Additional keywords can be used to specify other query parameters, e.g. relativeorbitnumber=70. See https://scihub.copernicus.eu/twiki/do/view/SciHubUserGuide/3FullTextSearch for a full list.
Range values can be passed as two-element tuples, e.g. cloudcoverpercentage=(0, 30). None can be used in range values for one-sided ranges, e.g. orbitnumber=(16302, None). Ranges with no bounds (orbitnumber=(None, None)) will not be included in the query.
Multiple values for the same query parameter can be provided as sets and will be handled as logical OR, e.g. orbitnumber={16302, 1206}.
The time interval formats accepted by the date parameter can also be used with any other parameters that expect time intervals (that is: ‘beginposition’, ‘endposition’, ‘date’, ‘creationdate’, and ‘ingestiondate’).
Returns: Products returned by the query as a dictionary with the product ID as the key and the product’s attributes (a dictionary) as the value. Return type: dict[string, dict]
-
static
format_query
(area=None, date=None, raw=None, area_relation='Intersects', **keywords)[source]¶ Create a OpenSearch API query string.
-
count
(area=None, date=None, raw=None, area_relation='Intersects', **keywords)[source]¶ Get the number of products matching a query.
Accepted parameters are identical to
SentinelAPI.query()
.This is a significantly more efficient alternative to doing len(api.query()), which can take minutes to run for queries matching thousands of products.
Returns: The number of products matching a query. Return type: int
-
static
to_geojson
(products)[source]¶ Return the products from a query response as a GeoJSON with the values in their appropriate Python types.
-
static
to_dataframe
(products)[source]¶ Return the products from a query response as a Pandas DataFrame with the values in their appropriate Python types.
-
static
to_geodataframe
(products)[source]¶ Return the products from a query response as a GeoPandas GeoDataFrame with the values in their appropriate Python types.
-
get_product_odata
(id, full=False)[source]¶ Access OData API to get info about a product.
Returns a dict containing the id, title, size, md5sum, date, footprint and download url of the product. The date field corresponds to the Start ContentDate value.
If full is set to True, then the full, detailed metadata of the product is returned in addition to the above.
Parameters: - id (string) – The UUID of the product to query
- full (bool) – Whether to get the full metadata for the Product. False by default.
Returns: A dictionary with an item for each metadata attribute
Return type: dict[str, Any]
Notes
For a full list of mappings between the OpenSearch (Solr) and OData attribute names see the following definition files: https://github.com/SentinelDataHub/DataHubSystem/blob/master/addon/sentinel-1/src/main/resources/META-INF/sentinel-1.owl https://github.com/SentinelDataHub/DataHubSystem/blob/master/addon/sentinel-2/src/main/resources/META-INF/sentinel-2.owl https://github.com/SentinelDataHub/DataHubSystem/blob/master/addon/sentinel-3/src/main/resources/META-INF/sentinel-3.owl
-
is_online
(id)[source]¶ Returns whether a product is online
Parameters: id (string) – UUID of the product, e.g. ‘a8dd0cfd-613e-45ce-868c-d79177b916ed’ Returns: True if online, False if in LTA Return type: bool
-
download
(id, directory_path='.', checksum=True, nodefilter=None)[source]¶ Download a product.
Uses the filename on the server for the downloaded file, e.g. “S1A_EW_GRDH_1SDH_20141003T003840_20141003T003920_002658_002F54_4DD1.zip”.
Incomplete downloads are continued and complete files are skipped.
Parameters: - id (string) – UUID of the product, e.g. ‘a8dd0cfd-613e-45ce-868c-d79177b916ed’
- directory_path (string, optional) – Where the file will be downloaded
- checksum (bool, default True) – If True, verify the downloaded file’s integrity by checking its checksum. Throws InvalidChecksumError if the checksum does not match.
- nodefilter (callable, optional) – The callable is used to select which files of each product will be downloaded.
If None (the default), the full products will be downloaded.
See
sentinelsat.products
for sample node filters.
Returns: product_info – Dictionary containing the product’s info from get_product_odata() as well as the path on disk.
Return type: dict
Raises: InvalidChecksumError
– If the MD5 checksum does not match the checksum on the server.LTATriggered
– If the product has been archived and its retrieval was successfully triggered.LTAError
– If the product has been archived and its retrieval failed.
-
trigger_offline_retrieval
(uuid)[source]¶ Triggers retrieval of an offline product from the Long Term Archive.
Parameters: uuid (string) – UUID of the product
Returns: True, if the product retrieval was successfully triggered. False, if the product is already online.
Return type: bool
Raises: LTAError
– If the request was not accepted due to exceeded user quota or server overload.ServerError
– If an unexpected response was received from server.UnauthorizedError
– If the provided credentials were invalid.
Notes
-
download_all
(products, directory_path='.', max_attempts=10, checksum=True, n_concurrent_dl=None, lta_retry_delay=None, fail_fast=False, nodefilter=None)[source]¶ Download a list of products.
Takes a list of product IDs as input. This means that the return value of query() can be passed directly to this method.
File names on the server are used for the downloaded files, e.g. “S1A_EW_GRDH_1SDH_20141003T003840_20141003T003920_002658_002F54_4DD1.zip”.
In case of interruptions or other exceptions, downloading will restart from where it left off. Downloading is attempted at most max_attempts times to avoid getting stuck with unrecoverable errors.
Parameters: - products (list) – List of product IDs
- directory_path (string) – Directory where the downloaded files will be downloaded
- max_attempts (int, default 10) – Number of allowed retries before giving up downloading a product.
- checksum (bool, default True) – If True, verify the downloaded files’ integrity by checking its MD5 checksum. Throws InvalidChecksumError if the checksum does not match. Defaults to True.
- n_concurrent_dl (integer, optional) – Number of concurrent downloads. Defaults to
SentinelAPI.concurrent_dl_limit
. - lta_retry_delay (float, default 60) – Number of seconds to wait between requests to the Long Term Archive.
- fail_fast (bool, default False) – if True, all other downloads are cancelled when one of the downloads fails.
- nodefilter (callable, optional) – The callable is used to select which files of each product will be downloaded.
If None (the default), the full products will be downloaded.
See
sentinelsat.products
for sample node filters.
Notes
By default, raises the most recent downloading exception if all downloads failed. If
fail_fast
is set to True, raises the encountered exception on the first failed download instead.Returns: - dict[string, dict] – A dictionary containing the return value from download() for each successfully downloaded product.
- dict[string, dict] – A dictionary containing the product information for products successfully triggered for retrieval from the long term archive but not downloaded.
- dict[string, dict] – A dictionary containing the product information of products where either downloading or triggering failed. “exception” field with the exception info is included to the product info dict.
-
download_all_quicklooks
(products, directory_path='.', n_concurrent_dl=4)[source]¶ Download quicklook for a list of products.
Takes a dict of product IDs: product data as input. This means that the return value of query() can be passed directly to this method.
File names on the server are used for the downloaded images, e.g. “S2A_MSIL1C_20200924T104031_N0209_R008_T35WMV_20200926T135405.jpeg”.
Parameters: - products (dict) – Dict of product IDs, product data
- directory_path (string) – Directory where the downloaded images will be downloaded
- n_concurrent_dl (integer) – Number of concurrent downloads
Returns: - dict[string, dict] – A dictionary containing the return value from download_quicklook() for each successfully downloaded quicklook
- dict[string, dict] – A dictionary containing the error of products where either quicklook was not available or it had an unexpected content type
-
download_quicklook
(id, directory_path='.')[source]¶ Download a quicklook for a product.
Uses the filename on the server for the downloaded image name, e.g. “S1A_EW_GRDH_1SDH_20141003T003840_20141003T003920_002658_002F54_4DD1.jpeg”.
Already downloaded images are skipped.
Parameters: - id (string) – UUID of the product, e.g. ‘a8dd0cfd-613e-45ce-868c-d79177b916ed’
- directory_path (string, optional) – Where the image will be downloaded
Returns: quicklook_info – Dictionary containing the quicklooks’s response headers as well as the path on disk.
Return type: dict
-
static
get_products_size
(products)[source]¶ Return the total file size in GB of all products in the OpenSearch response.
-
static
check_query_length
(query)[source]¶ Determine whether a query to the OpenSearch API is too long.
The length of a query string is limited to approximately 3898 characters but any special characters (that is, not alphanumeric or -_.*) will take up more space.
Parameters: query (str) – The query string Returns: Ratio of the query length to the maximum length Return type: float
-
check_files
(paths=None, ids=None, directory=None, delete=False)[source]¶ Verify the integrity of product files on disk.
Integrity is checked by comparing the size and checksum of the file with the respective values on the server.
The input can be a list of products to check or a list of IDs and a directory.
In cases where multiple products with different IDs exist on the server for given product name, the file is considered to be correct if any of them matches the file size and checksum. A warning is logged in such situations.
The corrupt products’ OData info is included in the return value to make it easier to re-download the products, if necessary.
Parameters: - paths (list[string]) – List of product file paths.
- ids (list[string]) – List of product IDs.
- directory (string) – Directory where the files are located, if checking based on product IDs.
- delete (bool) – Whether to delete corrupt products. Defaults to False.
Returns: A dictionary listing the invalid or missing files. The dictionary maps the corrupt file paths to a list of OData dictionaries of matching products on the server (as returned by
SentinelAPI.get_product_odata()
).Return type: dict[str, list[dict]]
-
get_stream
(id, **kwargs)[source]¶ Exposes requests response ready to stream product to e.g. S3.
Parameters: - id (string) – UUID of the product, e.g. ‘a8dd0cfd-613e-45ce-868c-d79177b916ed’
- **kwargs – Any additional parameters for
requests.get()
Raises: LTATriggered
– If the product has been archived and its retrieval was successfully triggered.LTAError
– If the product has been archived and its retrieval failed.
Returns: Opened response object
Return type: requests.Response
-
geojson_to_wkt
(geojson_obj, decimals=4)[source]¶ Convert a GeoJSON object to Well-Known Text. Intended for use with OpenSearch queries. 3D points are converted to 2D.
Parameters: - geojson_obj (dict) – a GeoJSON object
- decimals (int, optional) – Number of decimal figures after point to round coordinate to. Defaults to 4 (about 10 meters).
Returns: Well-Known Text string representation of the geometry
Return type: str
-
format_query_date
(in_date)[source]¶ Format a date, datetime or a YYYYMMDD string input as YYYY-MM-DDThh:mm:ssZ or validate a date string as suitable for the full text search interface and return it.
None will be converted to ‘*’, meaning an unlimited date bound in date ranges.
Parameters: in_date (str or datetime or date or None) – Date to be formatted Returns: Formatted string Return type: str Raises: ValueError
– If the input date type is incorrect or passed date string is invalid
-
placename_to_wkt
(place_name)[source]¶ - Geocodes the place name to rectangular bounding extents using Nominatim API and
- returns the corresponding ‘ENVELOPE’ form Well-Known-Text.
Parameters: place_name (str) – the query to geocode Raises: ValueError
– If no matches to the place name were found.Returns: - wkt_envelope (str) – Bounding box of the location as an ‘ENVELOPE(minX, maxX, maxY, minY)’ WKT string.
- info (Dict[str, any]) – Matched location’s metadata returned by Nominatim.
-
class
SentinelProductsAPI
(*args, **kwargs)[source]¶ Bases:
sentinelsat.sentinel.SentinelAPI
Deprecated since version 1.1.0: SentinelProductsAPI functionality has been merged into SentinelAPI and Downloader and will be removed in a future release.
-
make_size_filter
(max_size)[source]¶ Generate a nodefilter function to download only files below the specified maximum size.
New in version 0.15.
-
make_path_filter
(pattern, exclude=False)[source]¶ Generate a nodefilter function to download only files matching the specified pattern.
Parameters: - pattern (str) – glob patter for files selection
- exclude (bool, optional) – if set to True then files matching the specified pattern are excluded. Default False.
- versionadded: (.) – 0.15:
-
all_nodes_filter
(node_info)[source]¶ Node filter function to download all files.
This function can be used to download a Sentinel product as a directory instead of downloading a single zip archive.
New in version 0.15.
Exceptions¶
-
exception
SentinelAPIError
(msg='', response=None)[source]¶ Bases:
Exception
Invalid response from DataHub. Base class for more specific exceptions.
-
msg
¶ The error message.
Type: str
-
response
¶ The response from the server as a requests.Response object.
Type: requests.Response
-
-
exception
LTAError
(msg='', response=None)[source]¶ Bases:
sentinelsat.exceptions.SentinelAPIError
Error raised when retrieving a product from the Long Term Archive
-
exception
LTATriggered
(uuid)[source]¶ Bases:
sentinelsat.exceptions.SentinelAPIError
Download failed due to product being in the Long Term Archive and retrieval from LTA was triggered
-
exception
ServerError
(msg='', response=None)[source]¶ Bases:
sentinelsat.exceptions.SentinelAPIError
Error raised when the server responded in an unexpected manner, typically due to undergoing maintenance
Bases:
sentinelsat.exceptions.SentinelAPIError
Error raised when attempting to retrieve a product with incorrect credentials
-
exception
QuerySyntaxError
(msg, response)[source]¶ Bases:
sentinelsat.exceptions.SentinelAPIError
,SyntaxError
Error raised when the query string could not be parsed on the server side
-
exception
QueryLengthError
(msg='', response=None)[source]¶ Bases:
sentinelsat.exceptions.SentinelAPIError
Error raised when the query string length was excessively long
-
exception
InvalidKeyError
(msg, response)[source]¶ Bases:
sentinelsat.exceptions.SentinelAPIError
,KeyError
Error raised when product with given key was not found on the server