Python API¶

Quickstart¶

# connect to the API
from sentinelsat.sentinel import SentinelAPI, get_coordinates
api = SentinelAPI('user', 'password', 'https://scihub.copernicus.eu/dhus')

# download single scene by known product id
api.download(<product_id>)

# search by polygon, time, and SciHub query keywords
products = api.query(get_coordinates('map.geojson'), \
                     '20151219', date(2015, 12, 29), \
                     platformname = 'Sentinel-2', \
                     cloudcoverpercentage = '[0 TO 30]'})

# download all results from the search
api.download_all(products)

# GeoJSON FeatureCollection containing footprints and metadata of the scenes
api.get_footprints(products)

Valid search query keywords can be found at the ESA SciHub documentation.

Logging¶

Sentinelsat logs to sentinelsat and the API to sentinelsat.SentinelAPI.

There is no predefined `logging<https://docs.python.org/3/library/logging.html>`_ handler, so in order to have your script print the log messages, either use logging.baseConfig

import logging

logging.basicConfig(format='%(message)s', level='INFO')

or add a custom handler for sentinelsat (as implemented in cli.py)

import logging

logger = logging.getLogger('sentinelsat')
logger.setLevel('INFO')

h = logging.StreamHandler()
h.setLevel('INFO')
fmt = logging.Formatter('%(message)s')
h.setFormatter(fmt)
logger.addHandler(h)

API¶

exception sentinelsat.sentinel.InvalidChecksumError¶: MD5 checksum of local file does not match the one from the server.

class sentinelsat.sentinel.SentinelAPI(user, password, api_url='https://scihub.copernicus.eu/apihub/')¶

Class to connect to Sentinel Data Hub, search and download imagery.

Parameters:

user : string

username for DataHub

password : string

password for DataHub

api_url : string, optional

URL of the DataHub defaults to ‘https://scihub.copernicus.eu/apihub‘

Attributes

session	(requests.Session object) Session to connect to DataHub
api_url	(str) URL to the DataHub
page_size	(int) number of results per query page current value: 100 (maximum allowed on ApiHub)

Methods

`download`(id[, directory_path, checksum, ...])	Download a product using homura.
`download_all`(products[, directory_path, ...])	Download all products returned in query().
`format_query`(area[, initial_date, end_date])	Create the SciHub API query string
`get_product_odata`(id)	Access SciHub OData API to get info about a Product.
`get_products_size`(products)	Return the total filesize in GB of all products in the query
`load_query`(query[, start_row])	Do a full-text query on the SciHub API using the OpenSearch format specified in
`query`(area[, initial_date, end_date])	Query the SciHub API with the coordinates of an area, a date interval and any other search keywords accepted by the SciHub API.
`to_dataframe`(products)
`to_dict`(products[, parse_values])	Return the products from a query response as a dictionary with the values in their appropriate Python types.
`to_geodataframe`(products)
`to_geojson`(products)	Return the footprints of the resulting scenes in GeoJSON format

download(id, directory_path='.', checksum=False, check_existing=False, **kwargs)¶

Download a product using homura.

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.

Further keyword arguments are passed to the homura.download() function.

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, optional

If True, verify the downloaded file’s integrity by checking its MD5 checksum. Throws InvalidChecksumError if the checksum does not match. Defaults to False.

check_existing : bool, optional

If True and a fully downloaded file with the same name exists on the disk, verify its integrity using its MD5 checksum. Re-download in case of non-matching checksums. Defaults to False.

Returns:

path : string

Disk path of the downloaded file,

product_info : dict

Dictionary containing the product’s info from get_product_info().

Raises:

InvalidChecksumError

If the MD5 checksum does not match the checksum on the server.

download_all(products, directory_path='.', max_attempts=10, checksum=False, check_existing=False, **kwargs)¶

Download all products returned in query().

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 products returned with self.query()

directory_path : string

Directory where the downloaded files will be downloaded

max_attempts : int, optional

Number of allowed retries before giving up downloading a product. Defaults to 10.

Returns:

dict[string, dict|None]

A dictionary with an entry for each product mapping the downloaded file path to its product info (returned by get_product_info()). Product info is set to None if downloading the product failed.

Other Parameters:

See download().

static format_query(area, initial_date=None, end_date=datetime.datetime(2017, 6, 1, 14, 46, 52, 800246), **keywords)¶: Create the SciHub API query string

get_product_odata(id)¶: Access SciHub 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 receives the Start ContentDate of the API.

static get_products_size(products)¶: Return the total filesize in GB of all products in the query

load_query(query, start_row=0)¶: Do a full-text query on the SciHub API using the OpenSearch format specified in https://scihub.copernicus.eu/twiki/do/view/SciHubUserGuide/3FullTextSearch

query(area, initial_date=None, end_date=datetime.datetime(2017, 6, 1, 14, 46, 52, 800193), **keywords)¶: Query the SciHub API with the coordinates of an area, a date interval and any other search keywords accepted by the SciHub API.

static to_dict(products, parse_values=True)¶: Return the products from a query response as a dictionary with the values in their appropriate Python types.

static to_geojson(products)¶: Return the footprints of the resulting scenes in GeoJSON format

exception sentinelsat.sentinel.SentinelAPIError(http_status=None, code=None, msg=None, response_body=None)¶: Invalid responses from SciHub.

sentinelsat.sentinel.get_coordinates(geojson_file, feature_number=0)¶

Return the coordinates of a polygon of a GeoJSON file.

Parameters:

geojson_file : str

location of GeoJSON file_path

feature_number : int

Feature to extract polygon from (in case of MultiPolygon FeatureCollection), defaults to first Feature

Returns:

polygon coordinates

string of comma separated coordinate tuples (lon, lat) to be used by SentinelAPI