.. _usage:

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.

..  code-block:: python

    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.

..  code-block:: shell

    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 <https://fernlab.git-pages.gfz-potsdam.de/products/data-portal/s2_downloader_api/doc/readme.html#appendix-the-json-body>`_.


3. Expected Output
------------------

3.1 With AOI
^^^^^^^^^^^^

The following files are saved within the defined output folder:

.. csv-table:: Output files
    :header: "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:

.. code-block:: json

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

.. csv-table:: log-file information
    :header: "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