Usage

1. Download data using Python

To download the data with S2-Downloader using python code, you need first to install requests python package.

Here is an example showing how you could organize the python code.

import requests

email = '<email>'
password = '<password>'
data = {
    "name": "test",
    "aoi": {...},
    ...
}
output = '/directory/where/you/want/to/store/the/file/in/<output-name>.zip'

# Download mosaic data via a POST request
r = requests.post(
    '<the-s2-downloader-url>/download_data',
    json=data,
    auth=(email, password))

# Download whole tile via a POST request
# r = requests.post(
#     '<the-s2-downloader-url>/download_tile',
#     json=data,
#     auth=(email, password))

# Save the content on the disk
file_content = r.content
with open(output, 'wb') as f:
    f.write(file_content)

If you want to download whole tiles, just comment/delete the section under “# Download mosaic data…” and uncomment the section under “# Download whole tile…”.

2. Download data via terminal

If you have already the curl installed in your machine, you can also download your desired data using terminal. To do that, open up the terminal and execute the following code.

curl \
    --request POST \
    --url '<the-s2-downloader-url>/download_data' \
    -u <email>:<password> \
    --header 'Content-Type: application/json' \
    --data '{
        "name": "test",
        "aoi": {
            ...
        },
        ...
    }' \
    --output '</directory/where/you/want/to/store/the/file/in>/<output-name>.zip'

You need to replace <email> and <password> by your own one. You also need to pick a name for the downloaded archived file and replace <output-name> by it.

Equivalent to the download via python you can replace --url '<the-s2-downloader-url>/download_data' with --url '<the-s2-downloader-url>/download_tile' to download whole tiles.

By executing this command, it starts to download the data an you will see the logs in your terminal. Currently, the S2-Downloader supports only .zip file format which means you need to specify it in –output flag.

For detailed information about the setting the configuration of the request, please refer to this Appendix.

3. Expected Output

3.1 With AOI

The following files are saved within the defined output folder:

Output files

name	description
date_sensor_band.tif	The tif file of each band. Example: 20210905_S2B_coastal.tif for date 2021-09-05, sensor B and band 1.
date_sensor_SCL.tif	The tif file for the scl band of the according date. Example: 20210905_S2B_SCL.tif
s2DataDownloader.log	The log file containing all logs. The logging level can be set in the result settings in the config.json.
scenes_info_daterange.json	The information about the scenes for a certain date range. Example: scenes_info_2021-09-04_2021-09-05.json.

log-file

For each date the following information is saved:

{
    "20210905": {
        "item_ids": [
            {
                "id": "S2B_33UUU_20210905_0_L2A"
            }
        ],
        "nonzero_pixels": [
            100.0
        ],
        "valid_pixels": [
            100.0
        ],
        "data_available": [
            true
        ],
        "error_info": [
            ""
        ]
    }
}

log-file information

name	description
item_ids	The items (scenes) found at aws for that date.
nonzero_pixels	Percentage of pixels with non zero values.
valid_pixels	Percentage of pixels with valid data.
data_available	If false no data for this date was found.
error_info	If any error occurred during the download the error message will be saved here.

3.2 With tile ID

The difference when downloading complete tiles is that they are sorted in multiple folders with the following structure:

<utm_zone>
  <latitude_band>
    <grid_square>
      <year>
        <month>
          <platform>_<product_level>_<time>_<processing_baseline_number>_<relative_orbit_number>_<tile_number>_<product_id>
            <band_number>.tif