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.to_geojson(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 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)

Sorting & Filtering¶

In addition to the search query keywords sentinelsat allows filtering and sorting of search results before download. To simplify these operations sentinelsat offers the convenience functions to_dict(), to_geojson(), to_dataframe() and to_geodataframe() which return the search results as a Python dictionary, a Pandas DataFrame or a GeoPandas GeoDataFrame, respectively. to_dataframe() and to_geodataframe() require Pandas and GeoPandas to be installed, respectively.

In this example we query Sentinel-2 scenes over a location and convert the query results to a Pandas DataFrame. The DataFrame is then sorted by cloud cover and ingestiondate. We limit the query to first 5 results within our timespan and download them, starting with the least cloudy scene. Filtering can be done with all data types, as long as you pass the id to the download function.

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

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

# convert to Pandas DataFrame
products_df = api.to_dataframe(products)

# sort and limit to first 5 sorted products
products_df_sorted = products_df.sort_values(['cloudcoverpercentage', 'ingestiondate'], ascending=[True, True])
products_df_sorted = products_df_sorted.head(5)

# download sorted and reduced products in order
for product_id in products_df_sorted["id"]:
  api.download(product_id)

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)	Return the products from a query response as a Pandas DataFrame with the values in their appropriate Python types.
`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)	Return the products from a query response as a GeoPandas GeoDataFrame with the values in their appropriate Python types.
`to_geojson`(products)	Return the products from a query response as a GeoJSON with the values in their appropriate Python types.

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, 39, 381561), **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, 39, 381513), **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_dataframe(products)¶: Return the products from a query response as a Pandas DataFrame with the values in their appropriate Python types.

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_geodataframe(products)¶: Return the products from a query response as a GeoPandas GeoDataFrame with the values in their appropriate Python types.

static to_geojson(products)¶: Return the products from a query response as a GeoJSON with the values in their appropriate Python types.

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