Data API Documentation

Here we document how to request data from our data API and specify the format of the returned data. This document is an in-depth reference. For an easy interface to build your request URL, see the URL Builder tool.

Changes Oct 6, 2021

  • Added Raw data retrieval.
  • For requests that do not specify stations (e.g. /data/hourly.csv), only those stations with data are returned. If a given station has not been reporting for a while but is still nominally active, it will not show up in the data.
  • The precip field in latest minutely data is now split into precip5 and precip60 fields according to which observation timestep the value comes from.

Changes Sep 23, 2021

  • Missing times were mistakenly rendered as "00:00". It now shows up as "" as documented.
  • Stations which are considered active but whose data is behind no longer show up as wholly 'missing' entries. They are gone in their entirety from the data.
  • -999.0 has become -999.
  • The duplicate daily field st15MinTime has been de-duplicated.
  • JSON format fixes:
    • The stations array is no longer empty.

Changes Sep 15, 2021

  • Fixed typoed key in JSON instrument metadata: "anemometer:" to "anemometer".
  • Added the network field to JSON station metadata.
  • Renamed the headers query parameter to header for better semantics, and renamed flds to fields and stns to stations for unnecessary brevity. The old names will remain for compatibility.
  • Requests for data past the end of station data no longer error out. Instead, an error is only generated if you request past the end of the year.

Changes August 5, 2021

URL Structure and Query Parameters

Data request URLs for all stations look like:

https://coagmet.colostate.edu/data/product.fmt?param=value

or for just one station:

https://coagmet.colostate.edu/data/product/stnid.fmt?param=value

Variable parts of the URL are:

  • product - 5min/hourly/latest, daily/latest daily, gdd, soil moisture, or metadata.
  • fmt - json or csv
  • stnid - 5-character station id. See the list on the URL Builder page.
  • param=value… - query parameters, documented below.

Query parameters are the part of the URL (web address) after the ? and are separated by &. They change various aspects of the data produced.

Raw vs QC

Our data is examined daily for problems and edits are made where reasonable and bad data is marked missing. This quality control process results in our standard data product, labeled “QC”. The un-edited data we call “raw”. We make raw data available for 5 minute, hourly and daily weather observations (which are retrieved By Date) since that is what we measure. Latest data is effectively raw since our QC process is manual and not done continuously. GDD is calculated with QC'd data. Soil moisture is not subject to a QC process.

The default is to return quality-controlled data. To retrieve raw data instead, you will need to add _raw to the URL after the product name above. In the URL Builder, you select QC or Raw in the Which Data box.

Station(s)

If you want data for all active stations, use the first URL form above. If you want data for one particular station, use the second form. If you want to select multiple particular stations (but not all), use the first form and add the

stations=id,id,…

query parameter, where id is a 5-character station id such as gby01 for our Granby station.

Inactive Stations

By default, "all stations" only includes stations currently in operation. If you also want inactive stations (without having to list their ids individually), use

inactive=yes

Date Ranges

The general way to specify dates is with the from= and to= parameters with ISO 8601 dates. These can take several forms:

  • MM
  • YYYY
  • YYYY-MM
  • YYYY-MM-DD
  • YYYY-MM-DDTHH:MM

Where YYYY is the four-digit year, MM is the month (01-12), DD is the day of the month (01-31), HH is the hour of the day (00-23) and MM is the minute (00-59). The year by itself is the same as January 1 of that year.

If only the month is given, the from month will start on the first day of the month; the to month will end on the last day of the month. The year defaults to this year, but you can set the year with the year= query parameter. If only the year is given, the from date will be January 1 of that year whereas the to date will be December 31 of that year.

If you do not give a to date, the default is today. If you do not give a from date, the default is a number of days before the to date, with the number of days based on the data timestep. For daily data this is 7 days; for hourly data it is 5 days; and for 5-minute data it is 3 days. You can override the default number of days with the span= query parameter. If you give only one of from= or to=, the other date will be set based on this span.

The start, end and now keywords.  These let you specify dates symbolically rather than having to look up stations' lifetimes. Use the from=start query parameter to start at the beginning of the station's data record. If the request is for multiple stations, the date is for the oldest station. Use to=end when you want to get data through the end of operation. If the station is still in operation, this is the same as the end of today, i.e. now. If the request is for multiple stations, the date will be for the most recent observation of any of the stations. Finally, you can use the to=now parameter to request data through the present without having to calculate the date/time or depend on defaults.

Timezone.  For a 5 minute or hourly data set, if you specify a timezone with the tz= query parameter (see below), the from and to dates/times will be converted from that timezone into MST before querying the database (we store our records in MST). When requesting daily data, the dates are always interpreted as MST.

Units

We default to US units, so add the parameter

units=m
to select metric units.

Timezone

We store times in Mountain Standard Time (MST) and that is the default timezone (UTC-7). To select the UTC/GMT timezone, use

tz=utc

If you add

tz=co

to the request, the data will be in MST or MDT (UTC-6) based on the date range of the data. Where the dates cross the daylight saving time change, the code picks MST or MDT based on which one more of the data is in. Accuracy is not guaranteed.

If you use the query parameters from= or to= and the data timestep is hourly or 5 minute, the date/time range will be interpreted in the given timezone. Daily data will use exactly the date given in MST.

CSV Header

This applies to CSV only. To output column header use

header=yes

otherwise header lines will not be added to the output.

GDD Parameters

the GDD calculation requires a base and max temperature within which the plant is able to grow. The defaults of 50-86°F (10-30°C) are usually good, but your crop may be different. You can set the base and max temperature with the

base=temp

and/or

max=temp

query parameters where temp is a temperature in Fahrenheit unless units=m was also requested, in which case the temperatures are in °C.

Fields

Most data fields are included in the default output, documented in detail below. If you want more or fewer fields, use the

fields=

query parameter. List the fields you want, separated by commas, e.g. fields=t,rh,windSpeed.

Optional Metadata

By default, station metadata does not include the instruments or owner/sponsors. To include this data, add the query parameters

instruments=yes

and/or

sponsors=yes

Data Formatting

Numbers

Numbers are some number of digits with or without a decimal point ('.'), e.g. 123.45. We do not use scientific notation, i.e. 'e' followed by an exponent. There are no commas in numbers. Missing values are given the dummy value -999.

Date and Time Formats

the default date format for CSV data is the US convention MM/DD/YYYY. For JSON we use ISO 8601 YYYY-MM-DD or YYYY-MM-DDTHH:MM. To override the default, use either

dateFmt=us

or

dateFmt=iso

Times are in the format HH:MM. Missing dates are written as an empty string, i.e. "".

Relative Humidity

This is a number formatted as a fractional value. That is, 35% relative humidity will be formatted as 0.35.

Wind and Gust Directions

This is in degrees clockwise from due north. For example, an East-northeast window (blowing to West-southwest) is 67.5. A Northwest wind would be 315.

JSON

Our JSON-formatted data is encapsulated in one outer 'object'. Except for metadata, all JSON output has the following fields:

  • "which":  "raw" or "qc" (default),
  • "frequency":  "5min", "hourly", "daily" or "latest",
  • "timestep"300, 600, 900, 3600, 86400 (5 minute, 10 minute, 15 minute, hourly and daily in seconds),
  • "timezone":  "mst" (default), "co" or "utc",
  • "tzOffset":  "-07:00" (MST), "-06:00" (MDT) or "+00:00" (UTC),
  • "units":  "us" (default) or "m",

The data fields are all arrays of their particular data type. They are parallel arrays, so that the values of one observation are stored at the same index of each array.

Numbers are as described above.

Because JSON does not have a standard date or time format, we put the values in strings. Dates are in ISO (default) or US format as described in Date and Time Formats above. Missing date/times will show up as an empty string, i.e. "".

Examples

Single Station. Request URL: https://coagmet.colostate.edu/data/hourly/gby01.json?fields=t,rh,dewpt,solarRad,precip&from=2021-01-10T10:00&to=2021-01-10T13:00

{
  "which": "qc",
  "frequency": "hourly",
  "timestep": 3600,
  "timezone": "mst",
  "tzOffset": "-07:00",
  "units": "us",
  "station": "gby01",
  "time": ["2021-01-10T10:00","2021-01-10T11:00","2021-01-10T12:00","2021-01-10T13:00"],
  "t": [-3.9,4.6,14.5,17.8],
  "rh": [0.825,0.74,0.496,0.469],
  "dewpt": [-7.9,-1.9,-1.0,0.9],
  "solarRad": [254.0,389.0,459.7,472.3],
  "precip": [0.0,0.0,0.0,0.0]
}

Multiple Stations. Request URL: https://coagmet.colostate.edu/data/hourly.json?fields=t,rh,dewpt,solarRad,precip&stations=ctr01,drg01&from=2021-01-10T10:00&to=2021-01-10T13:00

{
  "which": "qc",
  "frequency": "hourly",
  "timestep": 3600,
  "timezone": "mst",
  "tzOffset": "-07:00",
  "units": "us",
  "stations": ["ctr01","drg01","egl01","gby01"],
  "time": ["2021-01-10T10:00","2021-01-10T11:00","2021-01-10T12:00","2021-01-10T13:00"],
  "ctr01": {
    "t": [14.1,18.4,21.7,-999.0],
    "rh": [0.798,0.723,0.716,-999.0],
    "dewpt": [9.0,11.0,14.0,-999.0],
    "solarRad": [319.5,435.5,504.5,-999.0],
    "precip": [0.0,0.0,0.01,-999.0]
  },
  "drg01": {
    "t": [25.6,31.6,35.3,35.4],
    "rh": [0.817,0.635,0.55,0.541],
    "dewpt": [20.7,20.6,20.7,20.4],
    "solarRad": [186.3,384.2,344.5,260.0],
    "precip": [0.0,0.0,0.0,0.0]
  }
}

XML

We have developed XML formats for weather data and station metadata. Their structure is documented in data.xsd and metadata.xsd. The names and values are otherwise the same as the JSON format, though dates and text values are not quoted.

CSV

Numbers are as described above.

Dates are always quoted whether US format MM/DD/YYYY (default) or ISO 8601 YYYY-MM-DD. Times are formatted MM/DD/YYYY HH:MM for US or YYYY-MM-DDTHH:MM for ISO. If you requested tz=utc, a " Z" will be appended to the time to indicate that. Missing dates will show up as empty quotes, i.e. "".

Example

Request URL: https://coagmet.colostate.edu/data/hourly.csv?header=yes&fields=t,rh,dewpt,solarRad,precip&stations=ctr01,drg01&from=2021-01-10T10:00&to=2021-01-10T13:00

Station,"Date and Time","Air temp",RH,Dewpoint,"Solar rad",Precip
id,"date time","deg F","%","deg F",W/m2,in
ctr01,"01/10/2021 10:00",14.1,0.798,9.0,319.5,0.0
ctr01,"01/10/2021 11:00",18.4,0.723,11.0,435.5,0.0
ctr01,"01/10/2021 12:00",21.7,0.716,14.0,504.5,0.01
ctr01,"01/10/2021 13:00",-999.0,-999.0,-999.0,-999.0,-999.0
drg01,"01/10/2021 10:00",25.6,0.817,20.7,186.3,0.0
drg01,"01/10/2021 11:00",31.6,0.635,20.6,384.2,0.0
drg01,"01/10/2021 12:00",35.3,0.55,20.7,344.5,0.0
drg01,"01/10/2021 13:00",35.4,0.541,20.4,260.0,0.0

Note the optional header lines and -999.0 missing value.

CoAgMET Data

Specifies data for the CoAgMET network. Also see data for the Northern Water network.

Latest Data

URLs for the latest data for all or just one station, respectively:

https://coagmet.colostate.edu/data/latest.fmt?param=value…
https://coagmet.colostate.edu/data/latest/stnid.fmt?param=value

The latest data has the same fields as 5 minute and hourly data. It consists of the newest observations for each station, usually a 5 minute observation, but some stations only have hourly data available.

Special Handling of Precipitation

Field Description US Metric
precip5 precipitation in ⋅ 5min mm ⋅ 5min
precip60 precipitation in ⋅ 60min mm ⋅ 60min

Because there is a mix of 5 minute and hourly timesteps, and precipitation is a total over the whole timestep, we need to treat it specially. When the observation is 5 minute data, the field is renamed precip5; hourly precip is renamed precip60.

Note that if you request JSON-formatted data for one station, the data will not be in arrays.

Latest Daily Data

URLs for the latest daily data for all or just one station, respectively:

https://coagmet.colostate.edu/data/latest/daily.fmt?param=value…
https://coagmet.colostate.edu/data/latest/daily/stnid.fmt?param=value

The latest daily data has the same fields as daily data. For JSON-formatted data for one station, the fields will not be in arrays.

5 Minute and Hourly Data

5 minute URLs for all or just one station, respectively:

https://coagmet.colostate.edu/data/5min.fmt?param=value…
https://coagmet.colostate.edu/data/5min/stnid.fmt?param=value

Hourly URLs for all or just one station:

https://coagmet.colostate.edu/data/hourly.fmt?param=value…
https://coagmet.colostate.edu/data/hourly/stnid.fmt?param=value

Despite the difference in timestep, 5-minute and hourly data have the same fields, they are just averaged over a different time span.

Field Description US Metric
station station id stn01 stn01
time observation date and time MM/DD/YYYY YYYY-MM-DDTHH:MM:SS
t air temperature °F °C
rh relative humidity 0.35 0.35
dewpt dew point °F °C
vp* vapor pressure kPa kPa
solarRad solar radiation W/m2 W/m2
rso* clear-sky solar radiation W/m2 W/m2
windSpeed wind speed mph m/s
windDir wind direction °N °N
windStdDev* wind direction std. dev. mph m/s
precip precipitation in mm
accumPrecip* accumulated precip in mm
gustSpeed gust speed mph m/s
gustTime* gust time HH:MM HH:MM
gustDir gust direction °N °N
st5cm soil temperature 5cm down °F °C
st15cm soil temperature 15cm down °F °C
hourlyETr ASCE Hourly ETr in mm
hourlyETo ASCE Hourly ETo in mm

* fields not present in default request
fields only available in hourly data

Daily Data

URLs for daily data for all or just one station, respectively:

https://coagmet.colostate.edu/data/daily.fmt?param=value…
https://coagmet.colostate.edu/data/daily/stnid.fmt?param=value
Field Description US Metric
station station id stn01 stn01
date observation date MM/DD/YYYY YYYY-MM-DDTHH:MM:SS
tAvg average air temp °F °C
tMax max air temp °F °C
tMaxTime time of max air temp HH:MM HH:MM
tMin min air temp °F °C
tMinTime time of min air temp HH:MM HH:MM
rhMax max relative humidity 0.35 0.35
rhMaxTime time of max rh HH:MM HH:MM
rhMin min relative humidity 0.35 0.35
rhMinTime time of min rh HH:MM HH:MM
vp* vapor pressure kPa kPa
solarRad solar radiation W/m2 W/m2
rso* clear-sky solar radiation W/m2 W/m2
precip precipitation in mm
windRun total distance wind traveled mi km
gustSpeed max wind gust mph m/s
gustTime time of max wind gust HH:MM HH:MM
gustDir gust direction °N °N
etrASCE ASCE ET tall ref. (alfalfa) in mm
etrPK Penman-Kimberly ref. ET in mm
etrHourly hourly ASCE ET in mm
etoASCE ASCE ET short ref. (turf) in mm
st5Max 5cm max soil temperature °F °C
st5MaxTime time of max 5cm soil temp HH:MM HH:MM
st5Min 5cm min soil temp °F °C
st5MinTime time of min 5cm soil temp HH:MM HH:MM
st15Max 15cm max soil temperature °F °C
st15MaxTime time of max 15cm soil temp HH:MM HH:MM
st15Min 15cm min soil temp °F °C
st15MinTime time of min 15cm soil temp HH:MM HH:MM

* fields not present in default request

Northern Water Data

Specifies data for the Northern Water network. Also see data for the CoAgMET network. The instruments on Northern Water stations are somewhat different from CoAgMET's so there is a separate namespace for NW data.

Latest Data - Northern Water

URLs for the latest data for all or just one station, respectively:

https://coagmet.colostate.edu/data/nw/latest.fmt?param=value…
https://coagmet.colostate.edu/data/nw/latest/stnid.fmt?param=value

The latest data has the same fields as 15 minute data. It consists of the newest observations for each station. The data can be 30-60min behind or so.

Note that if you request JSON-formatted data for one station, the data will not be in arrays.

Latest Daily Data - Northern Water

URLs for the latest daily data for all or just one station, respectively:

https://coagmet.colostate.edu/data/nw/latest/daily.fmt?param=value…
https://coagmet.colostate.edu/data/nw/latest/daily/stnid.fmt?param=value

The latest daily data has the same fields as daily data. For JSON-formatted data for one station, the fields will not be in arrays.

15 Minute Data - Northern Water

15 minute URLs for all or just one station:

https://coagmet.colostate.edu/data/nw/15min.fmt?param=value…
https://coagmet.colostate.edu/data/nw/15min/stnid.fmt?param=value
Field Description US Metric
station station id stn01 stn01
time observation date and time MM/DD/YYYY YYYY-MM-DDTHH:MM:SS
t average air temperature °F °C
tMax* maximum air temperature °F °C
tMin* minimum air temperature °F °C
tBucket* temp. of Revere weighing bucket °F °C
tCorrection* average temperature correction °F °C
rh relative humidity 0.35 0.35
dewpt dew point °F °C
vp* vapor pressure kPa kPa
precip difference in accum. precip gauge in mm
accumPrecip* accumulated precip field in mm
rain* rain total in mm
precipNew* new weight of accum. precip in mm
solarRad solar radiation W/m2 W/m2
rso* clear-sky solar radiation W/m2 W/m2
windSpeed wind speed mph m/s
windDir wind direction °N °N
windStdDev* wind direction std. dev. mph m/s
gustSpeed gust speed mph m/s
gustTime gust time HH:MM HH:MM
windRun* total distance wind traveled mi km
st10cm soil temperature 10cm down °F °C

* fields not present in default request

Hourly Data - Northern Water

Hourly URLs for all or just one station:

https://coagmet.colostate.edu/data/nw/hourly.fmt?param=value…
https://coagmet.colostate.edu/data/nw/hourly/stnid.fmt?param=value
Field Description US Metric
station station id stn01 stn01
time observation date and time MM/DD/YYYY YYYY-MM-DDTHH:MM:SS
t air temperature °F °C
rh relative humidity 0.35 0.35
dewpt dew point °F °C
vp* vapor pressure kPa kPa
solarRad solar radiation W/m2 W/m2
rso* clear-sky solar radiation W/m2 W/m2
precip precipitation in mm
accumPrecip* accumulated precip field in mm
windSpeed wind speed mph m/s
windDir wind direction °N °N
windStdDev* wind direction std. dev. mph m/s
gustSpeed gust speed mph m/s
gustTime gust time HH:MM HH:MM
st10cm soil temperature 10cm down °F °C
hourlyETr* ASCE ET, tall ref. (alfalfa) in mm
hourlyETo* ASCE ET, short ref. (turf) in mm

* fields not present in default request

Daily Data - Northern Water

URLs for daily data for all or just one station, respectively:

https://coagmet.colostate.edu/data/nw/daily.fmt?param=value…
https://coagmet.colostate.edu/data/nw/daily/stnid.fmt?param=value
Field Description US Metric
station station id stn01 stn01
date observation date MM/DD/YYYY YYYY-MM-DDTHH:MM:SS
tAvg average air temp °F °C
tMax max air temp °F °C
tMaxTime time of max air temp HH:MM HH:MM
tMin min air temp °F °C
tMinTime time of min air temp HH:MM HH:MM
rhMax max relative humidity 0.35 0.35
rhMaxTime time of max rh HH:MM HH:MM
rhMin min relative humidity 0.35 0.35
rhMinTime time of min rh HH:MM HH:MM
vp* vapor pressure kPa kPa
solarRad solar radiation W/m2 W/m2
rso* clear-sky solar radiation W/m2 W/m2
precip precipitation in mm
accumPrecip* accumulated precip field in mm
windRun total distance wind traveled mi km
gustSpeed max wind gust mph m/s
gustTime time of max wind gust HH:MM HH:MM
etrASCE ASCE ET tall ref. (alfalfa) in mm
etrPK Penman-Kimberly ref. ET in mm
etrHourly hourly ASCE ET in mm
etoASCE ASCE ET. short ref. (turf) in mm
st10Max 10cm max soil temperature °F °C
st10MaxTime time of max 10cm soil temp HH:MM HH:MM
st10Min 10cm min soil temp °F °C
st10MinTime time of min 10cm soil temp HH:MM HH:MM

* fields not present in default request

Growing Degree Days (GDD) Data

URLs for GDD data for just one station:

https://coagmet.colostate.edu/data/gdd/stnid.fmt?param=value

Growing degree days is a somewhat involved calculation, so we only support single station requests. If your crop grows over an unusual temperature range (outside 50-86°F), you can set the temperature parameters.

Field Description US Metric
station station id stn01 stn01
time observation date and time MM/DD/YYYY YYYY-MM-DDTHH:MM:SS
gdd cumulative GDD since planting date °F °C
daily daily fraction of GDD °F °C
hist historical avg GDD °F °C

No fields are missing from the default output.

Soil Moisture Data

URLs for hourly soil moisture data for all or just one station, respectively:

https://coagmet.colostate.edu/data/hourly/soilmoisture.fmt?param=value
https://coagmet.colostate.edu/data/hourly/soilmoisture/stnid.fmt?param=value

URLs for daily soil moisture data for all or just one station:

https://coagmet.colostate.edu/data/daily/soilmoisture.fmt?param=value
https://coagmet.colostate.edu/data/daily/soilmoisture/stnid.fmt?param=value

Hourly and daily soil moisture have all the same fields, just averaged over different time spans. This is somewhat specialized data, so we have only made it available in metric units whether you include the units=m query parameter or not.

Field Description Units
station station id stn01
time observation date and time YYYY-MM-DDTHH:MM:SS
vwc4 4" volumetric water content m3/m3
ec4 4" electrical conductivity m3/m3
st4 4" soil temperature °C
vwc24 24" volumetric water content m3/m3
ec24 24" electrical conductivity m3/m3
st24 24" soil temperature °C

No fields are missing from the default output.

Station Metadata

URLs for metadata for all or just one station:

https://coagmet.colostate.edu/data/metadata.fmt?param=value
https://coagmet.colostate.edu/data/metadata/stnid.fmt?param=value

Metadata has a slightly different structure from our normal data products. Each station id is a key in the outermost object that wraps all data. The station's metadata is in its own object under that station id key.

Query parameters that apply to station metadata:

  • instruments=yes - includes the instrument fields (see below).
  • sponsors=yes - includes the owner and sponsors fields (also see below).
  • units=m - station elevation and anemometer height will be in meters.

The metadata fields cannot be individually selected. Instead, the default fields are listed in the first table. The other tables are the fields included when instruments or sponsors parameters are enabled.

Field Description US Metric
station station id stn01 stn01
name station name
location text description of the station's location
lat °N °N
lon °E °E
elevation station elevation above sea level ft m
anemometerHeight height of wind sensor above ground level ft m
active is the station in operation? JSON/XML: true/false, CSV: active/inactive
irrigation type of irrigation near the station full/part/dry/unknown
firstObs first date of data available MM/DD/YYYY YYYY-MM-DD
lastObs last date of data available MM/DD/YYYY YYYY-MM-DD
timestep The time between observations seconds seconds
network whether the station belongs to the "Coag" (CoAgMET) or "NW" (Northern Water) network

Instruments

Field Description
logger the data logger that records and transmits observations
tempRH the temp/rh instrument
anemometer wind speed and direction sensor
soilThermometer soil thermometer
rainGauge rain gauge

Owner and Sponsors

Field Description
owner who owns the station*
sponsors (JSON) a list of sponsors for the station
sponsor (XML) one sponsor for the station

* We operate the weather stations, without necessarily owning them. In JSON, this is an array of strings. In CSV, each sponsor is a separate quoted string. There can be up to 5 sponsors, so the header (if any) will be …,Owner,Sponsor1,Sponsor2,…,Sponsor5