v.in.gsriver - GRASS manual

NAME

v.in.gsriver - Downloads and imports the GSriver global river vector dataset.

KEYWORDS

vector, import, hydrology, rivers, network

SYNOPSIS

v.in.gsriver

v.in.gsriver --help

v.in.gsriver [-rkp] output=name continent=string[,string,...] [input=name] [download_dir=name] [--overwrite] [--help] [--verbose] [--quiet] [--ui]

Flags:

-r: Restrict import to the current computational region extent
-k: Keep downloaded and extracted files (do not delete download_dir)
-p: Patch multiple imported continents into a single output map
--overwrite: Allow output files to overwrite existing files
--help: Print usage summary
--verbose: Verbose module output
--quiet: Quiet module output
--ui: Force launching GUI dialog

Parameters:

output=name [required]: Name for output vector map (a continent suffix is appended when several continents are imported)
continent=string[,string,...] [required]: GSriver continent tile(s) to import; Options: africa, asia_europe, north_america, oceania, russia, south_america; africa: Africa; asia_europe: Asia and Europe (excluding Russia); north_america: North America; oceania: Oceania; russia: Russia; south_america: South America
input=name: Path to an already downloaded GSriver zip file (single continent only, skips download)
download_dir=name: Directory to store downloaded and extracted files (default: a temporary directory, removed afterwards)

DESCRIPTION
NOTES
EXAMPLES
REFERENCES
SEE ALSO
AUTHOR

DESCRIPTION

v.in.gsriver downloads and imports tiles of the GSriver global river vector dataset (Liu et al., 2025, Scientific Data, doi:10.1038/s41597-025-06399-2). GSriver is an improved global river network built by fusing HydroRIVERS, OpenStreetMap waterways, and the Global River Topology (GRIT) dataset. It is distributed as continent-scale ESRI Shapefiles in WGS84 (EPSG:4326), hosted on figshare: https://figshare.com/articles/dataset/GSriver/30119851.

Data are downloaded per continent tile (option continent):

africa — Africa (166,335 rivers)
asia_europe — Asia and Europe, excluding Russia (209,528 rivers)
north_america — North America (134,242 rivers)
oceania — Oceania (45,738 rivers)
russia — Russia, distributed separately due to shapefile size limits (95,122 rivers)
south_america — South America (97,664 rivers)

Multiple continents can be given as a comma-separated list. Each continent is imported into its own map (named output_continent) unless the -p flag is used to patch all requested continents into a single output map with v.patch.

Each imported river feature carries the following attributes (see the figshare dataset description for full details):

HydroID — upstream HydroRIVERS reach ID, unique river identifier
Nextdown — downstream receiving river code (0 = sea/lake/inland termination)
MAINRIVID — watershed ID
Hydrocount — number of original HydroRIVERS reaches merged
Rclass, RclassDISP — river classification / display level
Rlenth — river length (km)
Hydrolenth — original HydroRIVERS reach length before fusion (km)
Rcatch — drainage area of this reach, excluding tributaries (km²)
TCatch — total drainage area including tributaries (km²)
OSMratio, GRITratio, Hydroratio — percentage of vertices contributed by each source dataset
Rname, NameList — river name(s)
OrignCNT — country of river origin

If the data have already been downloaded, the input option can point to a local GSriver-*-shp.zip file to skip the download (requires exactly one continent value, to identify which tile it is). Downloaded zip files are verified against the published MD5 checksums.

By default, downloaded and extracted files are placed in a temporary directory removed at the end of the run; use download_dir to control the location, and the -k flag to keep the files (e.g. for reuse across several imports).

Use the -r flag to limit the import to the current computational region (passed through to v.in.ogr -r), which considerably speeds up import when only a subset of a continent is needed.

NOTES

Continent zip files range from about 250 MB (Oceania) to 1.4 GB (Asia and Europe) — importing several continents, or an entire continent without -r, is data- and time-intensive. GSriver is licensed CC BY 4.0; cite the source publication when using the data.

EXAMPLES

Import Africa only, into a project in a matching or compatible CRS:

v.in.gsriver output=rivers_africa continent=africa

Import North America but restrict to the current region, keeping the downloaded files for later reuse:

g.region n=50 s=25 w=-125 e=-65
v.in.gsriver output=rivers_na continent=north_america -r -k \
    download_dir=$HOME/gsriver_cache

Import and merge Asia/Europe and Russia into a single map:

v.in.gsriver output=rivers_eurasia continent=asia_europe,russia -p

Import from a previously downloaded zip file, skipping the network download:

v.in.gsriver output=rivers_oceania continent=oceania \
    input=$HOME/Downloads/GSriver-OA-shp.zip

REFERENCES

Liu, Y., Wang, J., Liu, C. et al. An improved global river vector dataset based on multi-source river data fusion. Scientific Data (2025). doi:10.1038/s41597-025-06399-2

AUTHOR

Yann Chemin

SOURCE CODE

Available at: v.in.gsriver source code (history)

Accessed: Sunday Sep 13 08:30:14 2026