JRC Global Surface Water Download

Download surface water data from the JRC Global Surface Water Explorer — derived from 30+ years of Landsat imagery at 30m resolution.

Overview

The JRC Global Surface Water dataset maps the location and temporal distribution of surface water from 1984 to 2024. It uses the entire Landsat 5, 7, and 8 archive to produce 6 data layers describing surface water dynamics.

Data Layers

Layer	ID	Description
occurrence	occurrence	Percentage of water detection (0-100%)
change	change	Change in water occurrence (gain/loss)
seasonality	seasonality	Number of months with water (1-12)
recurrence	recurrence	Frequency of water recurrence (1-11)
transition	transition	Transitions between water classes
extent	extent	Maximum water extent (binary)
max_extent	max_extent	Maximum water extent layer

Features

• 6 data layers: occurrence, change, seasonality, recurrence, transition, extent
• 30m resolution: full Landsat resolution
• Bbox clipping: download only your area of interest
• GeoTIFF output: standard georeferenced raster
• Multiple access methods: HTTP direct download or GEE-based access
• Fallback options: works with or without Google Earth Engine

Access Methods

Method 1: Direct HTTP Download (Recommended)

The JRC data is tiled globally. This skill generates download URLs for the tiles intersecting your bbox and downloads them as GeoTIFF.

Method 2: Google Earth Engine (Optional)

If you have geemap or earthengine-api installed, you can use GEE for more flexible subsetting:

import ee
ee.Initialize()
dataset = ee.Image('JRC/GSW1_4/GlobalSurfaceWater')
occurrence = dataset.select('occurrence')

Usage

# Download water occurrence for a region
python scripts\global_surface_water.py download \
  --layer occurrence \
  --bbox 116.0 39.5 116.8 40.2 \
  --output ./water/beijing_occurrence.tif

# Download seasonality layer
python scripts\global_surface_water.py download \
  --layer seasonality \
  --bbox 73 18 135 54 \
  --output ./water/china_seasonality.tif

# Download all layers for a small area
python scripts\global_surface_water.py download \
  --layer all \
  --bbox 116.3 39.8 116.5 40.0 \
  --output ./water/beijing_all/

# List available layers
python scripts\global_surface_water.py list-layers

# Show dataset info
python scripts\global_surface_water.py info

Parameters

• --layer: Layer name (occurrence, change, seasonality, recurrence, transition, extent, max_extent, all)
• --bbox: Bounding box as west south east north
• --output: Output file path or directory
• --version: Dataset version (default: v1_4)
• --tile-size: Tile size in degrees (default: 10)

Data Tiling

The JRC Global Surface Water data is organized in 10° × 10° tiles. Each tile is approximately 300-600 MB. The skill automatically identifies which tiles intersect your bounding box and downloads them.

Installation

# Install dependencies
pip install requests>=2.28.0 tqdm

# Or install from requirements.txt
pip install -r scripts/requirements.txt

Data Source

• Dataset: JRC/GSW1_4/GlobalSurfaceWater
• Portal: https://global-surface-water.appspot.com/
• GEE Catalog: https://developers.google.com/earth-engine/datasets/catalog/JRC_GSW1_4_GlobalSurfaceWater
• License: CC-BY 4.0 (EC JRC)
• Rate Limit: No strict limit; recommended max 5 tile requests/minute
• CRS: WGS84 (EPSG:4326)
• Data type: uint8 (8-bit unsigned integer)
• NoData value: 0 (for most layers)

Citation Format

@article{pekel2016high,
  title={High-resolution mapping of global surface water and its long-term changes},
  author={Pekel, J.F. and Cottam, A. and Gorelick, N. and Belward, A.S.},
  journal={Nature},
  volume={540},
  pages={418--422},
  year={2016},
  doi={10.1038/nature20584}
}

Layer Definitions

Transition layer classes:

Value	Description
1	Permanent water
2	New permanent water (gained)
3	Lost permanent water
4	Seasonal water
5	New seasonal water
6	Lost seasonal water
7	Permanent to seasonal
8	Seasonal to permanent
9	Ephemeral permanent
10	Ephemeral seasonal
11	No water

Recurrence scale (1–11):

Value	Meaning
1	Seasonal (least frequent)
2–5	Low recurrence
6–8	Moderate recurrence
9–10	High recurrence
11	Permanent (most frequent)

Change layer values:

Value	Meaning
0	No change
1	New water (gain)
2	Lost water

extent vs max_extent:

• extent: Maximum observed water extent during the entire observation period (single binary layer).
• max_extent: Same as extent but includes additional processing for data quality.

Large-Area Download Planning

• Tile size: 10° × 10° tiles
• Storage estimate: ~1 GB per 10° × 10° tile at 30m resolution (all 7 layers)
• Planning: For large regions, calculate number of intersecting tiles × ~1 GB to estimate storage needs.
• Tip: Download one layer at a time for large areas to manage disk space.

Visualization

• Occurrence: Use single-band pseudocolor in QGIS (blue→white gradient for 0–100%).
• Change: Apply discrete color map: green = gain, red = loss, transparent = no change.
• Recurrence: Use graduated color ramp (yellow→dark blue) for 1–11 scale.
• Extent: Binary display — blue = water, transparent = land.

Troubleshooting

Error	Cause	Solution
ConnectionError	Network issue or API down	Check internet connection, retry in 1 minute
HTTP 429	Rate limit exceeded	Wait 60 seconds before retrying
HTTP 404	Invalid parameters or date range	Check parameter names and date format
ValueError: bbox	Invalid bounding box	Ensure format is west,south,east,north
Empty output	No data for query region/time	Try different date range or check coordinates
ModuleNotFoundError	Missing dependency	Run pip install requests tqdm
Disk full	Large tile downloads	Free space or reduce bbox size

---

Advanced Usage

Batch Tile Download

# Download occurrence layer for multiple tiles
for tile in "40N_110E" "40N_120E" "30N_110E" "30N_120E"; do
  lat=$(echo $tile | grep -oP '^\d+')
  lon=$(echo $tile | grep -oP '_\K\d+')
  python scripts\global_surface_water.py download     --layer occurrence --tile $tile     --output water_${tile}.tif
done

CI/CD Integration (GitHub Actions)

# .github/workflows/update-water.yml
name: Update Surface Water
on:
  schedule:
    - cron: '0 0 1 1 *'  # Yearly
jobs:
  download:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: '3.11'
      - run: pip install requests
      - run: |
          python scripts\global_surface_water.py download \
            --layer occurrence --tile 40N_110E \
            --output data/water_occ_40N_110E.tif

GIS Integration (QGIS/GDAL)

# Mosaic multiple tiles
gdal_merge.py -o water_china.tif water_*.tif

# Reproject to UTM
gdalwarp -t_srs EPSG:32649 water_china.tif water_china_utm.tif

PostgreSQL/PostGIS Import

raster2pgsql -s 4326 -I -C water_china.tif public.jrc_water | psql -d gis_db

Performance Tips

• Tiles are 10°×10°; plan storage (~1-5 GB per layer per tile)
• Use gdal_translate -a_nodata 0 to set nodata for visualization
• For change detection, download change layer and filter pixels with value 1 (gain) or 2 (loss)

---

中文说明

下载 JRC 全球地表水数据 —— 基于 30+ 年 Landsat 影像（1984-2024），30 米分辨率。

数据图层

图层	ID	描述
occurrence	occurrence	水体出现频率 (0-100%)
change	change	水体变化（增加/减少）
seasonality	seasonality	有水月份数 (1-12)
recurrence	recurrence	水体重现频率 (1-11)
transition	transition	水体类型转换
extent	extent	最大水体范围（二值）
max_extent	max_extent	最大水体范围图层

核心功能

• 6 种数据图层：出现频率、变化、季节性、重现性、转换、范围
• 30 米分辨率：完整 Landsat 分辨率
• 区域裁剪：仅下载感兴趣区域
• GeoTIFF 输出：标准地理参考栅格
• 多种获取方式：HTTP 直链下载或 GEE 方式
• 回退选项：有无 Google Earth Engine 均可使用

获取方式

方式一：HTTP 直链下载（推荐）

JRC 数据按全球分块存储。本工具自动生成与您的边界框相交的数据块下载链接， 并下载为 GeoTIFF 格式。

方式二：Google Earth Engine（可选）

如果已安装 geemap 或 earthengine-api，可使用 GEE 进行更灵活的裁剪：

import ee
ee.Initialize()
dataset = ee.Image('JRC/GSW1_4/GlobalSurfaceWater')
occurrence = dataset.select('occurrence')

使用示例

# 下载北京区域水体出现频率
python scripts\global_surface_water.py download \
  --layer occurrence \
  --bbox 116.0 39.5 116.8 40.2 \
  --output ./water/beijing_occurrence.tif

# 下载中国区域季节性图层
python scripts\global_surface_water.py download \
  --layer seasonality \
  --bbox 73 18 135 54 \
  --output ./water/china_seasonality.tif

# 下载小区域所有图层
python scripts\global_surface_water.py download \
  --layer all \
  --bbox 116.3 39.8 116.5 40.0 \
  --output ./water/beijing_all/

# 列出可用图层
python scripts\global_surface_water.py list-layers

# 查看数据集信息
python scripts\global_surface_water.py info

数据分块

JRC 全球地表水数据按 10° × 10° 分块存储。每个数据块约 300-600 MB。 工具自动识别与您的边界框相交的数据块并下载。

数据来源

• 数据集: JRC/GSW1_4/GlobalSurfaceWater
• 门户: https://global-surface-water.appspot.com/
• GEE 目录: https://developers.google.com/earth-engine/datasets/catalog/JRC_GSW1_4_GlobalSurfaceWater
• 许可证: CC-BY 4.0 (EC JRC)
• 引用: Pekel, J.F., Cottam, A., Gorelick, N., Belward, A.S., 2016. High-resolution mapping of global surface water and its long-term changes. Nature, 540, 418-422.