GRASS logo

NAME

m.cdo.download - Downloads data from NCEI's Climate Data Online (CDO) using their v2 API.

KEYWORDS

NOAA, NCEI, Climate Data Online, CDO

SYNOPSIS

m.cdo.download
m.cdo.download --help
m.cdo.download [-cju] fetch=string [datasetid=string[,string,...]] [datacategoryid=string[,string,...]] [datatypeid=string[,string,...]] [locationcategoryid=string[,string,...]] [locationid=string[,string,...]] [stationid=string[,string,...]] [startdate=string] [enddate=string] [extent=east,north[,east,north,...]] [units=string] [includemetadata=string] [sortfield=string] [sortorder=string] [limit=integer] [offset=integer] [fields=string[,string,...]] [separator=character] [indent=integer] [output=name] [--overwrite] [--help] [--verbose] [--quiet] [--ui]

Flags:

-c
Do not include column names in output
-j
Print output in JSON
-u
Print the request URL and exit
--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:

fetch=string [required]
Fetch available metadata or actual data for this specific item
Options: datasets, datacategories, datatypes, locationcategories, locations, stations, data
Default: data
datasetid=string[,string,...]
Dataset ID
datacategoryid=string[,string,...]
Data category ID
datatypeid=string[,string,...]
Data type ID
locationcategoryid=string[,string,...]
Location category ID
locationid=string[,string,...]
Location ID
stationid=string[,string,...]
Station ID
startdate=string
Start date in YYYY-MM-DD or date time in YYYY-MM-DDThh:mm:ss (for data only)
enddate=string
End date in YYYY-MM-DD or date time in YYYY-MM-DDThh:mm:ss (for data only)
extent=east,north[,east,north,...]
Extent in lower-left and upper-right coordinates in degrees
units=string
Units for data (raw for no conversion)
Options: raw, standard, metric
Default: metric
includemetadata=string
Include metadata when actually fetching data (slower)
Options: true, false
Default: false
sortfield=string
Sort field
Options: id, name, mindate, maxdate, datacoverage
sortorder=string
Sort order
Options: asc, desc
Default: asc
limit=integer
Max number of results (0 for unlimited; can be > 1000)
Default: 0
offset=integer
1-based offset for the first result
Default: 1
fields=string[,string,...]
Fields to print
separator=character
Field separator
Special characters: pipe, comma, space, tab, newline
Default: pipe
indent=integer
Indent for JSON format (-1 for single line per record)
Default: 2
output=name
Name for output file

Table of contents

DESCRIPTION

m.cdo.download downloads data from NCEI's Climate Data Online (CDO) using their v2 API.

NOTES

This module uses the CDO Web Services v2 API to download CDO data.

To access the API services, obtain CDO API tokens from here and define an environment variable CDO_API_TOKENS. Use commas to separate multiple tokens. For example, two tokens can be stored as follows:

export CDO_API_TOKENS=aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa,bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb

EXAMPLES

List available datasets:

m.cdo.download fetch=datasets

List available dataset IDs without column names:

m.cdo.download -c fetch=datasets fields=id

List available stations within (47.5204,-122.2047)-(47.6139,-122.1065):

m.cdo.download fetch=stations extent=47.5204,-122.2047,47.6139,-122.1065

List available "precipitation" and "average temperature" data types:

m.cdo.download fetch=datatypes field=id,mindate,maxdate,name |
grep -i "|precipitation\||average temperature"

List 10 available stations with PRCP and TAVG data starting 2023-01-01:

m.cdo.download fetch=stations datatypeid=PRCP,TAVG startdate=2023-01-01 limit=10

Fetch daily PRCP and TAVG data for a station with mindate ≤ 2023-01-01 and save it into a file:

# find dataset IDs for data types PRCP and TAVG; let's use GHCND (Daily Summary)
m.cdo.download fetch=datasets datatypeid=PRCP,TAVG

# find the first station ID with mindate ≤ 2023-01-01
stationid=$(m.cdo.download -c fetch=stations datatypeid=PRCP,TAVG \
	startdate=2023-01-01 fields=id limit=1)

# fetch actual data and save it to data.txt
m.cdo.download fetch=data datasetid=GHCND datatypeid=PRCP,TAVG \
	stationid=$stationid startdate=2023-01-01 enddate=2023-10-15 \
	output=data.txt

Create a point vector map with all stations:

# from a latlong location

# download metadata for all stations
m.cdo.download stations output=cdo_stations.txt

# import cdo_stations.txt
xy=$(awk -F'|' '{
	if (NR == 1) {
		for (i = 1; i <= NF; i++)
			if ($i == "latitude")
				latind = i
			else if ($i == "longitude")
				lonind = i
		printf "x=%s y=%s", lonind, latind
		exit
	}
}' cdo_stations.txt)
v.in.ascii input=cdo_stations.txt output=cdo_stations skip=1 $xy

# rename columns
old_cols=$(db.columns table=cdo_stations exclude=cat)
new_cols=$(head -1 cdo_stations.txt | sed 's/|/ /g')

for old_new in $(echo $old_cols $new_cols |
	awk '{
		n = NF / 2
		for (i = 1; i <= n; i++)
			printf "%s,%s\n", $i, $(i + n)
	}'); do
	v.db.renamecolumn map=cdo_stations column=$old_new
done
CDO stations

SEE ALSO

m.tnm.download

AUTHOR

Huidae Cho, New Mexico State University

SOURCE CODE

Available at: m.cdo.download source code (history)

Latest change: Saturday Oct 21 23:02:07 2023 in commit: 31ae1cfa675745f06d887625deec87700bded733


Main index | Miscellaneous index | Topics index | Keywords index | Graphical index | Full index

© 2003-2023 GRASS Development Team, GRASS GIS 8.3.2dev Reference Manual