GSWE Download Script — Instructions

1. Overview

This Python 3 script downloads tiles of the Global Surface Water Explorer (GSWE) dataset from the European Commission distribution endpoint. It walks the standard 10°×10° tile grid, downloads one GeoTIFF (.tif) per tile, skips files that are already present locally, and reports tiles that are not available on the server.

Two download modes are available, selected by the second parameter:

Aggregated products — one file per tile for the long-term GSWE layers (Section 3).
Monthly History time series — the monthlyhistory option, one file per tile, per month, per year (Section 4).

2. Requirements and general usage

Python 3 with the standard library (no extra packages required). General syntax:

python downloadWaterData_Python3_v1_5.py \
       <destination_folder> <dataset_name> [years] [tileIDs]

The destination folder is created automatically if it does not exist.
The tile grid uses 10° cells: longitudes 180W → 170E, latitudes 50S → 80N (360 tiles).
Existing files are skipped; missing tiles are reported as not found.
The optional years and tileIDs parameters apply to the monthlyhistory mode (Section 4).

3. Aggregated products

When the second parameter is any aggregated dataset name, the script downloads a single file per tile from the aggregated (VER1-5) distribution:

https://s3.waw4-1.cloudferro.com/swift/v1/global-surface-water/
    download2024/Aggregated/VER1-5/<dataset_name>/
    <dataset_name>_<lng>_<lat>_v1_5_2024.tif

The dataset name must match the product folder on the server. The GSWE products are:

Dataset name	Product	Description
occurrence	Water Occurrence	Frequency with which water was present at each pixel over the full observation record (percentage).
change	Occurrence Change Intensity	Change in water occurrence between two epochs — increases and decreases in surface water presence.
seasonality	Seasonality	Number of months per year that water was present (0–12), distinguishing seasonal from permanent water.
recurrence	Recurrence	Inter-annual behaviour: how often water returns from year to year (percentage).
transitions	Transitions	Class of change between the first and last year (e.g. new/lost permanent, new/lost seasonal, conversions).
extent	Maximum Water Extent	Union of all locations ever detected as water over the observation record.

Aggregated examples

Command	Result
`... ./out occurrence`	Water occurrence, one file per tile, all 360 tiles.
`... ./out seasonality`	Seasonality, one file per tile, all 360 tiles.
`... ./out transitions`	Transitions, one file per tile, all 360 tiles.

4. Monthly History (monthlyhistory) option

Passing monthlyhistory as the second parameter downloads the Monthly History GeoTIFF time series instead of an aggregated product. The downloaded .tif files are selected according to the second, third and fourth parameters.

Command syntax

python downloadWaterData_Python3_v1_5.py \
       <destination_folder> monthlyhistory [years] [tileIDs]

Parameters

#	Parameter	Required	Description
1	destination_folder	Yes	Local folder where the files are saved. Created automatically if it does not exist.
2	monthlyhistory	Yes	Dataset name. The literal value `monthlyhistory` activates the monthly time-series download mode.
3	years	Optional	Comma-separated list of years to download, e.g. `2023` or `2022,2024`. If omitted, all years are downloaded (2022, 2023, 2024).
4	tileIDs	Optional	Comma-separated list of tile IDs in `<lng>_<lat>` form, e.g. `100W_80N` or `0E_0N,10E_0N`. If omitted, all tiles are downloaded (360 tiles).

All 12 months (01–12) are downloaded for every selected year and tile. If both the years and the tile IDs are omitted, the script downloads the complete monthly history for all years and all tiles.

File naming and source

Each downloaded file follows the pattern:

monthlyhistory_<lng>_<lat>_v1_5_<YYYY>_<MM>.tif

and is retrieved from the CloudFerro endpoint:

https://s3.waw4-1.cloudferro.com/swift/v1/global-surface-water/
    download2024/monthlyhistory/VER1-5/<YYYY>/<YYYY>_<MM>/
    monthlyhistory_<lng>_<lat>_v1_5_<YYYY>_<MM>.tif

Monthly History examples

Command	Result
`... ./out monthlyhistory`	All years (2022, 2023, 2024), all tiles, all 12 months.
`... ./out monthlyhistory 2023`	Only 2023, all tiles, all 12 months.
`... ./out monthlyhistory 2022,2024`	Years 2022 and 2024, all tiles, all 12 months.
`... ./out monthlyhistory 2023 100W_80N`	Only 2023, only tile `100W_80N`, all 12 months.
`... ./out monthlyhistory 2022,2023,2024 0E_0N,10E_0N`	All years, tiles `0E_0N` and `10E_0N`, all 12 months.

This script is produced by the European Commission to download the Global Surface Water Explorer (GSWE) dataset. It is released WITHOUT ANY WARRANTY of any kind, express or implied, including but not limited to the warranties of merchantability and fitness for a particular purpose. Use it AT YOUR OWN RISK. © 2025, European Union.