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.
Our data API is brand new and in beta testing. If there is some aspect where we could do better or a feature to consider, please let us know: Email Zach.Schwalbe@colostate.edu.
Bugfixes Feb 9, 2021
- Some timestamps were negative or greater than 23:59:59, causing parse errors. These odd cases are now handled (though they're probably bad data).
- Some station IDs in the observation data are returned from the database in uppercase, causing a lookup failure. These are now normalized to lowercase.
Changes and Bugfixes Jan 13, 2021
Another round of fixed bugs and formatting changes:
- Missing data - when whole observations are missing, they now show up in the data.
- For multi-station output in JSON format, each station's data is now in their own sub-objects. The
time
field is still at the top level since it is the same across all stations, and there is astations
field to make the list of included stations explicit. We hope this change makes it easier to work with the data rather than you having to write your own logic to split apart each stations' data. If you do want a combined collection of observations, the CSV format has that organization. - The
count
field has been removed from JSON output. This value is already available in the arrays'.length
value. - New field
"timestep"
in JSON data and and metadata - for data, this is the number of seconds between observations for the requested frequency; for metadata it is the number of seconds between observations in the finest resolution the station has.
Changes and Bugfixes Dec 16, 2020
We have fixed same bugs and updated behavior:
- The
station
field was missing from some output. This has been restored. - Missing dates in CSV were not showing up as empty quotes (
""
). This has been fixed. - Missing dates in JSON now show up as an empty string (
""
) for uniformity with CSV - Missing numeric values are no longer marked as
null
in JSON output;-999
is used to help Javascript interpreters keep things monomorphic - When whole observations are missing, they now appear in the output. The missing fields have their missing value:
-999
for numbers and""
for dates. - In station metadata, "active" now has the boolean value true or false in JSON format.
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
orcsv
- 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.
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
stns=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 frequency. 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.
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=mto 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 frequency 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.
Headers
this applies to CSV only. To output column headers use
headers=yes
otherwise headers 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
flds=
query parameter. List the fields you want, separated by commas, e.g. flds=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
,3600
,86400
(5 minute, 10 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?flds=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?flds=t,rh,dewpt,solarRad,precip&stns=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] } }
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
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.
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.
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 frequency, 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 |
st5cm | soil temperature 5cm down | °F | °C |
st15cm | soil temperature 15cm down | °F | °C |
gustSpeed | gust speed | mph | m/s |
gustTime* | gust time | HH:MM | HH:MM |
gustDir | gust direction | °N | °N |
* fields not present in default request
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 (insolation) | 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 ref. evapotranspiration (ET) | in | mm |
etrPK | Penman-Kimberly ref. ET | in | mm |
etrHourly | hourly ASCE ET | in | mm |
etoASCE | ASCE small thing ET | in | mm |
st5Max | 5cm 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 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
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: 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 |
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 | a list of sponsors 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