get started!

Mesonet API | Reference | Accepted Variables | Code Examples | Release Notes

API Reference


API Resources

The Mesonet API exposes seven resources which can be queried via http GET requests. There are no services on the root (/) of the API. Do not add a trailing slash on the name of any resource.

Service Function and purpose
/auth Create tokens from an API key
/stations/[] Get station metadata, observational data, statistics, accumulated precipitation, and latency. Select stations by metadata.
/networks Get information about networks of stations
/networktypes Get information about network categorizations and uses
/qcsegments Get start and end points of data checks for a station(s).
/qctypes List available data check tests.
/variables List available variables within the system, units and descriptions.

All resources of Mesonet API are served from this root HTTPS address:

https://api.synopticlabs.org/v2

Some notes about this document

/auth

https://api.synopticlabs.org/v2/auth

Interface for account management services. Should not be used by clients, as it interfaces with your private API key, not tokens. This API follows the authentication procedure described in the guides. All queries must be made with a &token= argument

Accepted Parameters

Query String Type Description & Example
apikey string API Key, the API key which will be associated with the produced token.
Example: &apikey=[apikey]
disableToken string A token associated with the API key that is to be permanently disabled. Only the key associated with the token can disable the token.
Example: &apikey=[apikey]&disableToken=[token]
list bool Either a 1 or a 0, returns a list of the tokens associated with the provided API key.
Example: &apikey=[apikey]&list=1
output String Defaults to JSON. XML format is another output option with the same restrictions as JSON
Example: &output=xml
callback string Function name for use in JSONP requests
Example: &callback=somefunction

/stations/ Resources

https://api.synopticlabs.org/v2/stations/

Retrieve station metadata and observation data. Thus, the Stations resource is the primary feature of Mesonet API. The formatting of JSON outputs from the /stations resource is presented later on in this documentation.

The /stations resource by itself does not return anything (it will actually return a 404 Page), but it encapsulates 7 other resources:

Resource Function and purpose
metadata Returns metadata and extended metadata for stations.
timeseries Returns data for a station or set of stations based on a start and end date/time.
climatology Returns data for a station or set of stations based on a start month/day/hour/minute and end month/day/hour/minute over every year data are present in our databases.
statistics Returns statistics about "timeseries" or "climatology" of data; includes count, minimum, standard deviation, median, mean, and maximum.
precipitation Returns accumulated precipitation for a station or set of stations.
nearesttime Returns three possible values for a station or set of stations: the latest observation, the observation closest to a time before a time, the observation closest to a time before or after a time.
latency Returns data latency values for a station or set of stations based on a start and end date/time.

Selection parameters

These are used in all /stations resources for filtering the stations that the requested services are performed on.

Query String Type Description & Example
stid or stids String Single or comma separated list of SynopticLabs station IDs. To find stations IDs. Can be used with other query parameters.
Example: &stid=mtmet,kslc,fps
state String Single or comma separated list of abbreviated 2 character states. If country is not included, default is United States.
Example: &state=ut,wy,dc
country String Single or comma separated list of abbreviated 2 or 3 character countries.
Example: &country=us,ca,mx
nwszone String Single or comma separated list of National Weather Service Zones.
Example: &nwszone=UT003,CA041
nwsfirezone String Single or comma separated list of National Weather Service Fire Zones.
Example: &nwsfirezone=LOX241
cwa String Single or comma separated list of National Weather Service County Warning Areas.
Example: &cwa=LOX
gacc String Single or comma separated list of Geographic Area Coordination Centers.
Example: &gacc=GB
subgacc String Single or comma separated list of Sub Geographic Area Coordination Centers.
Example: &subgacc=EB07
county String Single or comma separated list of counties. Use the &state parameter to filter by state in the case of duplicate county names (such as King).
Example: &county=king&state=wa
vars String Single or comma separated list of sensor variables found here. The request will return all stations matching at least one of the variables provided. This is useful for filtering all stations that sense only certain variables, such as wind speed, or pressure. Do not specify vars twice in a query string.
Example: &vars=wind_speed,pressure
network Number Single or comma separated list of network IDs. The ID can be found be using the /networks resource.
Example: &network=153
radius Number A comma separated list of three values of the type [latitude,longitude,miles] or [stn_id,miles]. Coordinates are in decimal degrees. Returns all stations within radius of the point (or station, given by the station ID) and provides the distance of the station from given location by 'Distance' with units of miles. Adding &limit=nn to the query will limit the number of returned stations to nn stations.
Example: &radius=41.5,-120.25,20, &radius=wbb,10, &radius=41.5,-120.25,20&limit=10
bbox Number A bounding box defined by the lower left and upper right corners in decimal degrees latitude and longitude coordinates, in the form of [lonmin,latmin,lonmax,latmax]. Recall that for regions involving the western and southern hemispheres that the coordinates are negative values (e.g., 120 W is -120, 20 S is -20).
Example: &bbox=-120,40,-119,41
status String A value of either active or inactive returns only stations that are currently set as active in the archive. By default, omitting this parameter will return all stations.
Example: &status=active
complete Boolean A value of 1 or 0. When set to 1 an extended list of metadata attributes for each returned station is provided. This result is useful for exploring the zones and regions in which a station resides. Default is 0.
Example: &complete=1

/stations/metadata

https://api.synopticlabs.org/v2/stations/metadata

These parameters can alter the default metadata output from the API.

Query String Type Description & Example
sensorvars Boolean A value of 1 or 0. Default is 0. When set to 1, metadata queries will return a complete list of variables ever reported at a station as well as the period of record for those specific variables. Note: This may include variables not in the OBSERVATIONS element.
Example: &sensorvars=1
obrange String A string of numbers representing a date-time group. Should always be formatted as YYYYmmdd. Filters station metadata for only stations which were in operation for the specified time period. Users can specify one date-time group to find data for that specific date or provide a comma-separated list of two date-time groups to find stations reporting during that time period.
Example: &obrange=20150101, &obrange=20040101,20060101

Output formatting and usability parameters

Query String Type Description & Example
timeformat String A format string for returning customized date-time groups for observation times and period of record. Can include words and letters.
Example: &timeformat=%m/%d/%Y at %H:%M, &timeformat=%Y%m%d%H:%M
output String Defaults to JSON. XML format and geoJSON are also output options with the same restrictions as JSON
Example: Examples: &output=xml, &output=geojson
callback string Function name for use in JSONP requests
Example: &callback=somefunction

/stations/timeseries

https://api.synopticlabs.org/v2/stations/timeseries

These parameters can be used in combination with the station selection parameters to acquire timeseries data from a set of stations.

Query String Type Description & Example
start Number Required: The start date and time in the form of YYYYMMDDhhmm to return observations, where YYYY is year, MM is month, DD is day, hh is hour, and mm is minutes. The start parameter must be used with the end parameter. All times are requested in UTC, but may be returned in either UTC or Local time format for each station. See the obtimezone parameter.
Example: &start=201306011800&end=201306021215
end Number Required: The end date and time in the form of YYYYMMDDhhmm to return observations, where YYYY is year, MM is month, DD is day, hh is hour, and mm is minutes. The start parameter must be used with the end parameter. All times are requested in UTC, but may be returned in either UTC or Local time format for each station. See the obtimezone parameter.
Example: &start=201306011800&end=201306021215
obtimezone String Optional: A value of either UTC or local. If omitted the default is UTC. Set the timezone used on the observation output (input times are always UTC)
Example: &obtimezone=local
showemptystations Number Optional: When set to "1" will show stations even when there are no observations that match the time period. The JSON OBSERVATION object will be empty. By default, stations without observations are omitted from the response.
Example: Example: &showemptystations=1
units String or set of strings and pipes separated by commas Optional: By default, data will come back in metric units. For basic usage, set it equal to ENGLISH. For more granularity, the user can specify what units each convertable variable should be in, with the variable group, followed by a pipe character |, and then the unit abbreviation. Valid combinations are as follows: temp|C, temp|F, temp|K; speed|mps, speed|mph, speed|kph, speed|kts; pres|pa, pres|mb; height|m, height|ft; precip|mm, precip|cm, precip|in; alti|pa, alti|inhg.
Example: &units=temp|F,speed|kph,metric
recent Number Optional: In lieu of a start and end date/time, by using this parameter, the request will return a time series of values for the latest X minutes.
Example: &recent=60
qc String Optional: Returns data checks for the vars requested. It is possible to target a particular SynopticLabs data check or ask for the entire SynopticLabs test suite, i.e. &qc=on. Regardless if any data checks are returned, a QC_FLAGGED=<bool> key will appear in the JSON response inside each STATION element. Data checks will be in a key titled QC.
Note: The existence of a data check flag for an observation is not necessarily an indication of invalid or inaccurate data. For a detailed explanation how to apply data checks and how to leverage them, please click here to read more.

Optional Output formatting and usability parameters

Query String Type Description & Example
timeformat String A format string for returning customized date-time groups for observation times and period of record. Can include words and letters.
Example: &timeformat=%m/%d/%Y at %H:%M,&timeformat=%Y%m%d%H:%M
output String Defaults to 'JSON', but can be 'CSV' if requesting a single station time series. Defaults to 'CSV' if the single station series is longer than 2 years. 'XML' format and geoJSON are also output options with the same restrictions as 'JSON'
Example: Examples: &output=csv, &output=xml, &output=geojson
callback string Function name for use in JSONP requests
Example: &callback=somefunction

/stations/climatology

https://api.synopticlabs.org/v2/stations/climatology

These parameters can be used in combination with the station selection parameters to acquire yearly climatology data from a set of stations.

Query String Type Description & Example
startclim Number Required: The start date and time in the form of MMDDhhmm to return observations, MM is month, DD is day, hh is hour, and mm is minutes. The &startclim parameter must be used with the &endclim parameter. All times are requested in UTC, but may be returned in either UTC or Local time format for each station. See the obtimezone parameter.
Example: &startclim=06011800&endclim=06021215
endclim Number Required: The end date and time in the form of MMDDhhmm to return observations, MM is month, DD is day, hh is hour, and mm is minutes. The &startclim parameter must be used with the &endclim parameter. All times are requested in UTC, but may be returned in either UTC or Local time format for each station. See the obtimezone parameter.
Example: &startclim=06011800&endclim=06021215
obtimezone String Optional: A value of either UTC or local. If omitted the default is UTC. Set the timezone used on the observation output (input times are always UTC)
Example: &obtimezone=local
showemptystations Number Optional: When set to "1" will show stations even when there are no observations that match the time period. The JSON OBSERVATION object will be empty. By default, stations without observations are omitted from the response. |&showemptystations=1
units String or set of strings and pipes separated by commas. Optional: By default, data will come back in metric units. For basic usage, set it equal to ENGLISH. For more granularity, the user can specify what units each convertible variable should be in, with the variable group, followed by a pipe character |, and then the unit abbreviation. Valid combinations are as follows: temp|C, temp|F, temp|K; speed|mps, speed|mph, speed|kph, speed|kts; pres|pa, pres|mb; height|m, height|ft; precip|mm, precip|cm, precip|in; alti|pa, alti|inhg.
Example: &units=temp|F,speed|kph,metric

Output formatting and usability parameters

Query String Type Description & Example
timeformat String Optional: A format string for returning customized date-time groups for observation times and period of record. Can include words and letters.
Example: &timeformat=%m/%d/%Y at %H:%M,&timeformat=%Y%m%d%H:%M
output String Optional: Defaults to 'JSON'. 'XML' format and geoJSON are also output options with the same restrictions as JSON
Example: &output=xml, &output=geojson
callback string Function name for use in JSONP requests
Example: &callback=somefunction

/stations/statistics

https://api.synopticlabs.org/v2/stations/statistics

These parameters can be used in combination with the station selection parameters to acquire two different types of statistics queries. Option one uses the 'start' and 'end' parameters to choose discrete periods of time over which to calculate statistics. Option two uses the startclim and endclim parameters to select yearly climatological statistics for the month and day chosen.

Query String Type Description & Example
start Number Required (option 1): The start date and time in the form of YYYYMMDDhhmm to return observations, where YYYY is year, MM is month, DD is day, hh is hour, and mm is minutes. The start parameter must be used with the end parameter. All times are requested in UTC, but may be returned in either UTC or Local time format for each station. See the obtimezone parameter. |&start=201306011800&end=201306021215
end Number Required (option 1): The end date and time in the form of YYYYMMDDhhmm to return observations, where YYYY is year, MM is month, DD is day, hh is hour, and mm is minutes. The start parameter must be used with the end parameter. All times are requested in UTC, but may be returned in either UTC or Local time format for each station. See the obtimezone parameter. |&start=201306011800&end=201306021215
type String Required: Describes what statistical values will be returned. Can be one of the following values: "avg"/"average"/"mean", "max"/"maximum", "min"/"minimum", "stdev"/"standarddeviation"/"std", "median"/"med", "count", or "all". "All" will return all of the statistics. | &type=stdev
percentile String Optional: Find the value at a certain percentile for each observation. Can be a value between 0 and 100. | &percentile=90
obtimezone String Optional: A value of either UTC or local. If omitted the default is UTC. Set the timezone used on the observation output (input times are always UTC) |&obtimezone=local
showemptystations Number Optional: When set to "1" will show stations even when there are no observations that match the time period. The JSON OBSERVATION object will be empty. By default, stations without observations are omitted from the response. |&showemptystations=1
units String or set of strings and pipes separated by commas Optional: By default, data will come back in metric units. For basic usage, set it equal to ENGLISH. For more granularity, the user can specify what units each convertible variable should be in, with the variable group, followed by a pipe character |, and then the unit abbreviation. Valid combinations are as follows: temp|C, temp|F, temp|K; speed|mps, speed|mph, speed|kph, speed|kts; pres|pa, pres|mb; height|m, height|ft; precip|mm, precip|cm, precip|in; alti|pa, alti|inhg.
Example: &units=temp|F,speed|kph,metric

Output formatting and usability parameters

Query String Type Description & Example
timeformat String Optional: A format string for returning customized date-time groups for observation times and period of record. Can include words and letters.
Example: &timeformat=%m/%d/%Y at %H:%M,&timeformat=%Y%m%d%H:%M
output String Optional: Defaults to 'JSON'. 'XML' format id also supported with the same restrictions as JSON
Example: &output=xml
callback string Function name for use in JSONP requests
Example: &callback=somefunction

/stations/precipitation

https://api.synopticlabs.org/v2/stations/precipitation OR https://api.synopticlabs.org/v2/precip

These parameters can be used in combination with the station selection parameters to acquire accumulated precipitation data from a set of stations.

Query String Type Description & Example
start Number Required: The start date and time in the form of YYYYMMDDhhmm to return observations, where YYYY is year, MM is month, DD is day, hh is hour, and mm is minutes. The start parameter must be used with the end parameter. All times are requested in UTC, but may be returned in either UTC or Local time format for each station. See the obtimezone parameter. |&start=201306011800&end=201306021215
end Number Required: The end date and time in the form of YYYYMMDDhhmm to return observations, where YYYY is year, MM is month, DD is day, hh is hour, and mm is minutes. The start parameter must be used with the end parameter. All times are requested in UTC, but may be returned in either UTC or Local time format for each station. See the obtimezone parameter. |&start=201306011800&end=201306021215
obtimezone String Optional: A value of either UTC or local. If omitted the default is UTC. Set the timezone used on the observation output (input times are always UTC) |&obtimezone=local
showemptystations Number Optional: When set to "1" will show stations even when there are no observations that match the time period. The JSON OBSERVATION object will be empty. By default, stations without observations are omitted from the response. |&showemptystations=1
units String or set of strings and pipes separated by commas Optional: By default, data will come back in metric units. For basic usage, set it equal to ENGLISH. For more granularity, the user can specify what units each convertable variable should be in, with the variable group, followed by a pipe character |, and then the unit abbreviation. Valid combinations are as follows: temp|C, temp|F, temp|K; speed|mps, speed|mph, speed|kph, speed|kts; pres|pa, pres|mb; height|m, height|ft; precip|mm, precip|cm, precip|in; alti|pa, alti|inhg. |&units=temp|F,speed|kph,metric

Output formatting and usability parameters

Query String Type Description & Example
timeformat String Optional: A format string for returning customized date-time groups for observation times and period of record. Can include words and letters.
Example: &timeformat=%m/%d/%Y at %H:%M,&timeformat=%Y%m%d%H:%M
output String Optional: Defaults to 'JSON'. 'XML' format and geoJSON are also output options with the same restrictions as JSON
Example: &output=xml, &output=geojson
callback string Function name for use in JSONP requests
Example: &callback=somefunction

/stations/nearesttime

https://api.synopticlabs.org/v2/stations/nearesttime

These parameters can be used in combination with the station selection parameters to acquire the most recent values or those nearest to a given time from a set of stations.

Query String Type Description & Example
attime Number Required: The date and time in the form of YYYYMMDDhhmm for which the observation returned will be closest, where YYYY is year, MM is month, DD is day, hh is hour, and mm is minutes. All times are requested in UTC, but may be returned in either UTC or Local time format for each station. See the obtimezone parameter. |&attime=201306011800&within=30,30
within Number Required: If used without attime, it can be left blank (giving the latest observation) or represent any number of minutes (giving the latest observation within that time frame). If with attime, it can be a single number of minutes (giving the observation closest to attime within that number of minutes prior to attime) or two numbers of minutes, representing before and after attime (giving the observation closest to attime within that number of minutes before or after attime) |&attime=201306011800&within=30,30
obtimezone String Optional: A value of either UTC or local. If omitted the default is UTC. Set the timezone used on the observation output (input times are always UTC) |&obtimezone=local
showemptystations Number Optional: When set to "1" will show stations even when there are no observations that match the time period. The JSON OBSERVATION object will be empty. By default, stations without observations are omitted from the response. |&showemptystations=1
units String or set of strings and pipes separated by commas Optional: By default, data will come back in metric units. For basic usage, set it equal to ENGLISH. For more granularity, the user can specify what units each convertible variable should be in, with the variable group, followed by a pipe character |, and then the unit abbreviation. Valid combinations are as follows: temp|C, temp|F, temp|K; speed|mps, speed|mph, speed|kph, speed|kts; pres|pa, pres|mb; height|m, height|ft; precip|mm, precip|cm, precip|in; alti|pa, alti|inhg.
Example: &units=temp|F,speed|kph,metric
qc String Optional: Returns data checks for the vars requested. It is possible to target a particular SynopticLabs data check or ask for the entire SynopticLabs test suite, i.e. &qc=on. Regardless if any data checks are returned, a QC_FLAGGED=<bool> key will appear in the JSON response inside each STATION element. Data checks will be in a key titled QC.
Note: The existence of a data check flag for an observation is not necessarily an indication of invalid or inaccurate data. For a detailed explanation how to apply data checks and how to leverage them, please click here to read more.

Output formatting and usability parameters

Query String Type Description & Example
timeformat String Optional: A format string for returning customized date-time groups for observation times and period of record. Can include words and letters.
Example: &timeformat=%m/%d/%Y at %H:%M,&timeformat=%Y%m%d%H:%M
output String Optional: Defaults to 'JSON'. 'XML' format and geoJSON are also output options with the same restrictions as JSON
Example: &output=xml, &output=geojson
callback string Function name for use in JSONP requests
Example: &callback=somefunction

/stations/latest

https://api.synopticlabs.org/v2/stations/latest

The latest resource is an alias to the /nearesttime resource which returns the most recent observation for all selected variables (all variables by default) for the selected stations.

Query String Type Description & Example
obtimezone String Optional: A value of either UTC or local. If omitted the default is UTC. Set the timezone used on the observation output (input times are always UTC)
Example: &obtimezone=local
showemptystations Number Optional: When set to "1" will show stations even when there are no observations that match the time period. The JSON OBSERVATION object will be empty. By default, stations without observations are omitted from the response.
Example: &showemptystations=1
units String or set of strings and pipes separated by commas By default, data will come back in metric units. For basic usage, set it equal to ENGLISH. For more granularity, the user can specify what units each convertible variable should be in, with the variable group, followed by a pipe character |, and then the unit abbreviation. Valid combinations are as follows: temp|C, temp|F, temp|K; speed|mps, speed|mph, speed|kph, speed|kts; pres|pa, pres|mb; height|m, height|ft; precip|mm, precip|cm, precip|in; alti|pa, alti|inhg.
Example: &units=temp|F,speed|kph,metric
within Number Number of minutes from the present to search for observations. If omitted, then the latest observation of every variable and station is returned
Example: within=60
qc String Optional: Returns data checks for the vars requested. It is possible to target a particular SynopticLabs data check or ask for the entire SynopticLabs test suite, i.e. &qc=on. Regardless if any data checks are returned, a QC_FLAGGED=<bool> key will appear in the JSON response inside each STATION element. Data checks will be in a key titled QC.
Note: The existence of a data check flag for an observation is not necessarily an indication of invalid or inaccurate data. For a detailed explanation how to apply data checks and how to leverage them, please click here to read more.

Output formatting and usability parameters

Query String Type Description & Example
timeformat String Optional: A format string for returning customized date-time groups for observation times and period of record. Can include words and letters.
Example: &timeformat=%m/%d/%Y at %H:%M,&timeformat=%Y%m%d%H:%M
output String Optional: Defaults to 'JSON'. 'XML' format and geoJSON are also output options with the same restrictions as JSON
Example: &output=xml, &output=geojson
callback String Function name for use in JSONP requests
Example: &callback=somefunction

/stations/latency

https://api.synopticlabs.org/v2/stations/latency

These parameters can be used in combination with the station selection parameters to acquire latency data from a set of stations.

Query String Type Description & Example
start Number Required: The start date and time in the form of YYYYMMDDhhmm to return observations, where YYYY is year, MM is month, DD is day, hh is hour, and mm is minutes. The start parameter must be used with the end parameter. All times are requested in UTC, but may be returned in either UTC or Local time format for each station. See the obtimezone parameter. |&start=201306011800&end=201306021215
end Number Required: The end date and time in the form of YYYYMMDDhhmm to return observations, where YYYY is year, MM is month, DD is day, hh is hour, and mm is minutes. The start parameter must be used with the end parameter. All times are requested in UTC, but may be returned in either UTC or Local time format for each station. See the obtimezone parameter. |&start=201306011800&end=201306021215
obtimezone String Optional: A value of either UTC or local. If omitted the default is UTC. Set the timezone used on the observation output (input times are always UTC) |&obtimezone=local
stats String Optional: Describes what statistical values will be returned. Can be one of the following values: "avg"/"average"/"mean", "max"/"maximum", "min"/"minimum", "stdev"/"standarddeviation"/"std", "median"/"med", "count", or "all". "All" will return all of the statistics.
Example: &stats=stdev

Output formatting and usability parameters

Query String Type Description & Example
callback String Function name for use in JSONP requests
Example: &callback=somefunction
output String Optional: Defaults to 'JSON'. 'XML' format is also an output option with the same restrictions as 'JSON'|&output=xml
timeformat String Optional: A format string for returning customized date-time groups for observation times and period of record. Can include words and letters.
Example: &timeformat=%m/%d/%Y at %H:%M,&timeformat=%Y%m%d%H:%M

/networks

https://api.synopticlabs.org/v2/networks

The Networks service provides metadata on the networks within the SynopticLabs dataset.

Accepted parameters

Query String Type Description & Example
id Number Single or comma separated list of network IDs. Networks IDs are the way station metadata identifies a station's network.
Example: &id=1,2,3,4
shortname String Single or comma separated list of network short names.
Example: &shortname=uunet,raws
sortby String Optional: Only valid value is alphabet for determining the sorting order. By default networks are sorted by ID.
Example: &sortby=alphabet

Output formatting and usability parameters

Query String Type Description & Example
callback String Function name for use in JSONP requests
Example: &callback=somefunction
output String Optional: Defaults to 'JSON'. 'XML' format id also supported with the same restrictions as JSON
Example: &output=xml

/networktypes

https://api.synopticlabs.org/v2/networktypes

Returns network type metadata matching the query string parameters provided.

Accepted Parameters

List of query string parameters to request metadata

Query String Type Description & Example
id Number Single or comma separated list of network ID types.
Example: &id=1,2,3,4

Output formatting/usability parameters

Query String Type Description & Example
callback String Function name for use in JSONP requests
Example: &callback=somefunction
output String Optional: Defaults to 'JSON'. 'XML' format id also supported with the same restrictions as JSON
Example: &output=xml

/qcsegments

https://api.synopticlabs.org/v2/qcsegments

Returns a list of temporal segments describing a data check event. For a full explanation of this service please read our explanation about this service. Please note that this data response is different from our standard time series styled response.

Accepted Parameters

Any /stations/ or /stations/timeseries argument is valid.

Output formatting/usability parameters

Query String Type Description & Example
callback String Function name for use in JSONP requests
Example: &callback=somefunction
output String Optional: Defaults to 'JSON'. 'XML' format id also supported with the same restrictions as JSON
Example: &output=xml

/qctypes

https://api.synopticlabs.org/v2/qctypes

Returns a list of the available data checks provided by both SynopticLabs and our third party providers.

Accepted parameters:

Query String Type Description & Example
shortname String The API shortname the data check. This is used to target a particular test.
Example: &shortname=sl_range_check
id Number An internal SynopticLabs ID number for a test or tests
Example: &id=1,2,3

Additional accepted output formatting/usability parameters:

Query String Type Description & Example
callback String Function name for use in JSONP requests
Example: &callback=somefunction
output String Optional: Defaults to 'JSON'. 'XML' format id also supported with the same restrictions as JSON
Example: &output=xml

/variables

https://api.synopticlabs.org/v2/variables

Returns a list of the available variables within the API. No arguments (besides token) are accepted.

Additional accepted output formatting/usability parameters:

Query String Type Description & Example
callback String Function name for use in JSONP requests
Example: &callback=somefunction
output String Optional: Defaults to 'JSON'. 'XML' format id also supported with the same restrictions as JSON
Example: &output=xml

Accessing data checks via the API

Currently the API supports accessing data checks in two distinct ways. They are provided in terms of temporal segments (/qcsegments) which do not include the observations and second and as data attributes via the /timeseries, /nearesttime and /latest services.

By default, the API does not return data that has been flagged as non-plausible by the SynopticLabs Range Check, e.g. a temperature value of 200C. It does provide a series of URL arguments that allow the retrieval of removed data as well as their flags. If the &qc argument is omitted then the service will return data while assuming the following QC arguments: &qc=on, &qc_remove_data=on, qc_flags=off and &qc_checks=sl_range_check.

Note, these are for JSON and GeoJSON response output formats only.

Query String Type Description and Example
&qc String "on|off", turn qc on or off. If set to "off" then all data will be returned without data checks and quality control (this is not recommended). Setting this to "on" allows for control over how data checks are applied to the observed data values.
&qc_remove_data String "on|off|mark", sets how observed data values are returned when the user specified data checks have failed for the data. A setting of "off" returns the data values even if a data check failure is present for that data. A setting of "on" removes failed data values with a "null". A setting of "mark" replaces failed data with a value of "false".
&qc_flags String "on|off", toggles whether the data checks are returned alongside any data that failed a requested check. If "on" then the data checks will be returned in the API response.
&qc_checks String "[flag name]|[flag source]|all", list of data checks applied to data values. The settings of other qc parameters determines how the data and data checks are returned. Where "all" will return any data check in our system. "flag name" allows the targeting of a flag by name or a list (comma separated) of flags. "flag source" allows targeting a data check provider i.e. "synopticlabs" for SynopticLabs. Example: &qc_checks=synopticlabs,ma_range_check or &qc_checks=synopticlabs,madis.

Example: For the complete suite of tests from SynopticLabs add &qc=on which inherits &qc_remove_data=off, &qc_flags=on and &qc_checks=synopticlabs.

WARNING: using qc_checks=all may not be the best solution for identifying erroneous data as it may increase rejecting valid data. It is also not recommended using qc=off as there will be no data checks applied to the data.

For a full list of &qc_check values, query the /qctypes service at:

https://api.mesowest.net/v2/qctypes?token=demotoken

For more information read our introduction on this topic or the data check documentation.

JSON Response Format

This API produces data in the JSON format by default. Fortunately, JSON has native decoders in a large number of programming languages, requiring only the need to know the structure of the returned data to use it. Each API resource returns a different format of JSON depending on the needs of that resource. This section will demonstrate the major differences between these formats.

JSON is an ideal protocol for exchanging data objects and structures, however it is not well-suited for large volumes of data. To decode a JSON object, data must be held entirely in memory. Thus, when requesting very large volumes of data (from the /stations/timeseries resource only at this time) the requested output should be in the CSV format (&output=csv), which can be streamed in chunks. CSV formats are not described here.

Standard JSON response structure & summary

Result sets have 2 or 3 elements, the result, which can have various names, a possible additional element with reference information, and the SUMMARY, which will be described shortly. A successful query will have a SUMMARY like this (where RESULT represents any number of data queries).

All resources except for the /auth and /variables use the same basic JSON structure, which is comprised of a single object. This object has various elements (keys), finishing with a SUMMARY key. The SUMMARY object details API performance and status for the query.

{
  "RESULT": [...],
  "SUMMARY": {
    "NUMBER_OF_OBJECTS": 2,
    "RESPONSE_CODE": 1,
    "RESPONSE_MESSAGE": "OK",
    "RESPONSE_TIME": "4.48298454285 ms"
  }
}

A query summary contains 4 primary pieces of information

Parameter Meaning
NUMBER_OF_OBJECTS How many discrete objects were returned, for /stations queries this is the number of individual stations returned, for /networks, how many networks, and for /networktypes, how many types.
RESPONSE_CODE An internally-defined code for the state of a query. See the table in the Errors section for an explanation of possible values.
RESPONSE_MESSAGE A string representing the same message as the RESPONSE_CODE
RESPONSE_TIME The amount of time it took for the API to respond to the query, which does not count time for data to be delivered to the user, or time the query waited to be accepted by the API.

Other parameters in the summary are for internal timing. In the event of an error, the structure of the SUMMARY object is discussed in the Errors section of the documentation.

/stations/ JSON characteristics

The /stations resource exposes a diverse set of functions that return data based on a selection of stations and data characteristics. The structure of the data returned from any /stations resource is consistent, with a minimum number of custom variables and inputs for each response.

With no data, station metadata are presented as a list of objects within an element named STATION. Therefore the top two keys of the JSON are STATION and SUMMARY.

{
  'STATION':[ ... ],
  'SUMMARY': { ... }
}

Metadata queries will always return a station period of record with start and end values. Null values may exist for stations whose start times are not known. Nulls should not exist for the end time. End times will be the time of the last observation for active stations. Stations with null start times will be excluded from any obrange search because it is not known whether or not a station had data during that time.

Station metadata formatting

Without extended metadata (&complete=1) or complete period of record (&sensorvars=1), the default columns included for each station entry are as follows. These values are included for all stations retrieved for all queries.

Parameter Meaning
ID Internal SynopticLabs identification number for the station.
NAME Station name
STID Station abbreviation/Identifier
MNET_ID Numeric ID of the network
ELEVATION Elevation above mean sea level in feet
LONGITUDE Longitude
LATITUDE Latitude
STATE US or Canadian 2-letter state abbreviation
TIMEZONE ISO-8601 compliant station timezone (approximate for offshore and Canadian stations)
STATUS String defining if the station is ACTIVE or INACTIVE
PERIOD_OF_RECORD Date-time groups for total station period of record. If &sensorvars=1, the period of record is for each variable in addition to station existence.

Complete station metadata values

The following additional categories are returned in addition to the default metadata values for extended metadata requests.

Parameter Meaning
SHORTNAME Network short name
COUNTRY 2-letter Country abbreviation
NWSFIREZONE NWS Fire zone
COUNTY County in which the station is located
CWA NWS County Warning Area (Which NWS Forecast office covers the station location)
SGID Sub-Geographic Area Coordination Center ID
NWSZONE NWS Forecast zone
GACC Geographic Area Coordination Center ID

Additional metadata parameters cannot be retrieved via the API at this time. Some metadata pertaining to sensor variables is provided when making data queries.

Station structure with observational data

In addition to the default metadata structure (or extended metadata if requested), data are inserted into the resultant JSON output within the station object outlined above. In addition to the STATION and SUMMARY elements of the JSON object, a new element is added called UNITS. This object is a set of key-value pairs matching variable IDs to the units they are sent in. The unit strings match those in the data results set. The station objects within the STATION element have additional elements added to them.

New Element Purpose Returned by these resources
SENSOR_VARIABLES A list of names of the variables returned from this station. This summarizes the variables which will be found in the OBSERVATIONS element. /timeseries, /climatology, /statistics, /nearesttime
OBSERVATIONS The element which holds variable data and time stamps. So, this is the generic structure of a data query from the API. New elements in the structure are highlighted. /timeseries, /climatology, /nearesttime, /precipitation
STATISTICS The element which holds aggregate statistical values; it parallels the structure of OBSERVATIONS when requested for /nearesttime /statistics, /latency (if requested)
LATENCY The element which holds latency values and corresponding date/times; it parallels the structure of OBSERVATIONS when requested for /timeseries /latency
QC_FLAGGED The element which holds any QC data by sensor. (if requested) /timeseries, /latest, /nearesttime
{
  UNITS: {},
  STATION: [
      {
          STATUS: "ACTIVE",
          MNET_ID: "153",
          ELEVATION: "4806",
          NAME: "U of U William Browning Building",
          STID: "WBB",
          SENSOR_VARIABLES: [],
          LONGITUDE: "-111.84755",
          STATE: "UT",
          OBSERVATIONS: {},
          LATENCY: {},
          STATISTICS: {},
          LATITUDE: "40.76623",
          TIMEZONE: "US/Mountain",
          ID: "1",
          QC_FLAGGED: True
          QC: {}
      }
  ],
  SUMMARY: { ... }
}

The OBSERVATIONS element

The last and trickiest part of the JSON response is the OBSERVATIONS element. OBSERVATIONS is an object/dictionary where the keys are variable set names, and the values are lists. The variable names in OBSERVATIONS (aka the keys of the OBSERVATIONS object) are the names in SENSOR_VARIABLES under the variable name.

Single-observation

These will return in a /nearesttime, or /precip request.

In this case, each variable contains an object, like this:

"solar_radiation_value_1": {
    "date_time": "2014-10-06T17:00:00-0600",
    "value": 397
 }
Multiple observation

These will return in a /timeseries, or /climatology request.

In this case, all the elements within the OBSERVATIONS and QC elements are lists of the same size, and simply the index of the variable observation is equivalent to the date_time array. This will often result in null values for variables which only report periodically.

 "date_time": [
    "2013-06-06T12:04:00Z",
    "2013-06-06T12:09:00Z",
    "2013-06-06T12:14:00Z",
    "2013-06-06T12:19:00Z",
    "2013-06-06T12:24:00Z",
    "2013-06-06T12:29:00Z",
    "2013-06-06T12:34:00Z",
    "2013-06-06T12:39:00Z",
    "2013-06-06T12:44:00Z",
    "2013-06-06T12:49:00Z",
    "2013-06-06T12:54:00Z",
    "2013-06-06T12:55:00Z",
    "2013-06-06T12:59:00Z"
 ],
 "altimeter_set_1": [
    86065.2,
    86036.6,
    86065.2,
    86065.2,
    86065.2,
    86065.2,
    86065.2,
    86065.2,
    86065.2,
    86065.2,
    86065.2,
    86065.2,
    86065.2
 ],

the STATISTICS element

Looking similar to the single-observation OBSERVATION datasets, each variable set contains an object. If a single statistical value is selected (standard deviation, for example) the output will appear as follows:

"wind_gust_set_1": {
    "start": "01020000",
    "end": "01030000",
    "value": 1.8528130054473877
}  

If, on the other hand, all statistics are requested, the object appears as follows:

"altimeter_set_1": {
    "count": 2418.0,
    "start": "01020000",
    "minimum": 85578.8515625,
    "end": "01030000",
    "mintime": "2009-01-02T22:20:00Z",
    "standard_deviation": 27818.8359375,
    "maxtime": "2011-01-02T12:53:00Z",
    "median": 87869.84375,
    "average": 88727.6015625,
    "maximum": 877712.4375
}

If &stats=all is requested from the /latency resource, the STATISTICS object will simply look as follows:

"STATISTICS": {
    "count": 289.0,
    "start": "201307100000",
    "minimum": 0.0,
    "end": "201307110000",
    "mintime": "2013-07-10T01:00:00Z",
    "standard_deviation": 15.430158615112305,
    "maxtime": "2013-07-10T11:15:00Z",
    "median": 0.0,
    "average": 5.380622863769531,
    "maximum": 85.0
}

the LATENCY element

Looking similar to the multiple-observation OBSERVATION datasets, the LATENCY object contains only two keys: date_time and values, for which the values are lists that look like the following:

"date_time": [
    "2013-07-10T00:00:00Z",
    "2013-07-10T00:05:00Z",
    "2013-07-10T00:10:00Z",
    "2013-07-10T00:15:00Z",
    "2013-07-10T00:20:00Z",
    "2013-07-10T00:25:00Z",
    "2013-07-10T00:30:00Z",
    "2013-07-10T00:35:00Z",
    "2013-07-10T00:40:00Z",
    "2013-07-10T00:45:00Z",
    "2013-07-10T00:50:00Z",
    "2013-07-10T00:55:00Z",
    "2013-07-10T01:00:00Z"
],
"values": [
    60,
    55,
    50,
    45,
    40,
    35,
    30,
    25,
    20,
    15,
    10,
    5,
    0,
]

/networks JSON response format

A successful /networks query result set will contain an element (or key) called MNET. MNET is a list of objects (dictionaries), each of which represent a network from the query. Each network will have the following parameters

Parameter (object/dict key) Meaning
ID The internal numeric ID of the network
URL A web address for the network
CATEGORY A numeric category ID (see the /networktypes query) categorizing the purpose of the network
SHORTNAME The common abbreviation or shortened way to refer to the network
LONGNAME The formal and more descriptive name of the network

Here is an example output for a query resulting in a single network result:

{
  "MNET": [
    {
      "URL": null,
      "CATEGORY": "9",
      "SHORTNAME": "RAWS",
      "ID": "2",
      "LONGNAME": "Interagency Remote Automatic Weather Stations"
    }
  ],
  "SUMMARY": ...
}

/networktypes JSON response format

/networktypes result sets are contained within the MNETCAT key. This key contains a list of objects (dicts) with the following parameters:

Parameter (object/dict key) Meaning
ID The internal numeric ID of the network type category
NAME A short identifier for this network type
DESCRIPTION A clear description of the category

Here is an example result set from an /networktypes query

{
  "MNETCAT": [
    {
      "DESCRIPTION": "Air Quality",
      "ID": "2",
      "NAME": "AQ"
    }
  ],
  "SUMMARY": ...
}

/qcsegments JSON response format

The /qcsegments has a unique response format. This is to optimize downloading.

"STATION: [ { ... "QC": [ { "start": "2017-04-17T22:00:00Z", "qc_flag": 17, "sensor": "relative_humidity_qc_1", "end": "2017-04-17T22:45:00Z" }, ... ], ... } ]

/variables JSON response format

The /variables resource has a very simple output, a single set of nested objects (dictionaries) showing the variable names returned by the API. The objects are structured within a top-level element (key) of VARIABLES. This contains an object whose keys are the variable names available. Each variable object contains the following parameters

Parameter (object/dict key) Meaning
long_name The more descriptive identifier of this variable, a string unit | The unit in which this variable comes out of the API

Here is an example of this output (the returned data is essentially static, so this is just a fraction of the standard return).

{
  "VARIABLES":
    {
      "soil_temp": {
        "long_name": "Soil Temperature",
        "unit": "Celsius"
      },
      "fuel_moisture": {
        "long_name": "10 hr Fuel Moisture",
        "unit": "gm"
      },
      "road_subsurface_tmp": {
        "long_name": "Road Subsurface Temperature",
        "unit": "Celsius"
      },
      "" : ...
    }
}

/qctypes JSON format

The /qctypes resource has a very simple output, a single set of nested objects (dictionaries) showing the test names returned by the API. The objects are structured within a top-level element (key) of QCTYPES. This contains an object whose keys are the tests available. Each test object contains the following parameters

Parameter (object/dict key) Meaning
SHORTNAME A shortened version of the test NAME. The first characters represent the original entity that performed the test.
ID The internal SynopticLabs ID representing a specific test.
NAME The full name of the QC/IC check, with the original performer of the test specified with its full name.

Here is an example of this output (the returned data is essentially static, so this is just a fraction of the standard return).

{
    "QCTYPES": [
        {
            "SHORTNAME": "sl_range_check",
            "ID": "1",
            "NAME": "SynopticLabs Range Check"
        },
        {
            "SHORTNAME": "mw_time_step_check",
            "ID": "2",
            "NAME": "SynopticLabs Time-step Check"
        },
        {
            "SHORTNAME": "mw_pers_check",
            "ID": "3",
            "NAME": "SynopticLabs Temporal Persistence Check"
        },
            "",...
    ]
}

XML Response Format

XML formatted responses are derived directly from the JSON responses, therefore they are the same collections of nested lists and objects.

GeoJSON Responses

The API return basic Feature objects in GeoJSON format. Furthermore the API sets various properties of the GeoJSON feature depending on the resource requested. An example of the properties on a Feature object from a /stations/metadata request is below

"properties": {
    "county": "Salt Lake",
    "timezone": "America/Denver",
    "sgid": "GB20",
    "id": "33898",
    "nwsfirezone": "SLC478",
    "stid": "MTMET",
    "state": "UT",
    "cwa": "SLC",
    "nwszone": "UT003",
    "gacc": "GB",
    "status": "ACTIVE",
    "elevation": "4996",
    "station_info": "http://mesowest.utah.edu/cgi-bin/droman/station_total.cgi?stn=MTMET",
    "more_observations": "http://mesowest.utah.edu/cgi-bin/droman/meso_base_dyn.cgi?stn=MTMET",
    "latitude": "40.766573",
    "shortname": "UUNET",
    "mnet_id": "153",
    "name": "U of U Mountain Met Lab",
    "country": "US",
    "longitude": "-111.828211"
}

Errors and Restrictions

Occasionally an error will occur, either because no data fit the parameters requested, authentication was invalid, or (rarely) a problem internal to our system. Most errors are handled by the API, and will return a summary output JSON. Additionally, access restrictions within the SynopticLabs dataset are enforced by the API throwing an error in the event of a data request for which a particular token was not authorized.

Built-in errors

The following error codes exist within the API by design. Incorrect token. Tokens must be correct in the &token=... parameter of the API query string. An incorrect token will result in a failed request.

{
  "SUMMARY": {
    "RESPONSE_CODE": 200,
    "RESPONSE_MESSAGE": "Authentication Failure.",
    "RESPONSE_TIME": " 0 ms"
  }
}

No stations fitting the selection criteria. In the event that no data producing stations were found in the area requested, no data will be returned. This includes cases when two selection criteria cancel each other out.

{
  "SUMMARY": {
    "NUMBER_OF_OBJECTS": 0,
    "RESPONSE_CODE": 2,
    "RESPONSE_MESSAGE": "Zero Results",
    "RESPONSE_TIME": "2.34580039978 ms"
  }
}

Each handled query error has an associated response code, which is passed in the SUMMARY object. The following is a list of these codes and their messages.

Response Code Message
1 No errors
2 Zero results
200 Authentication failure
400 Violates a rule of the API

Other possible errors

In a few cases, standard HTTP error codes will be thrown without JSON. These include:
* 504 (Timeout, the request took too long to handle)
* 502 (API server temporarily unavailable)
* 500 (Uncaught internal error)

Sensor Variable List

Please visit the API-based Sensor variable list page to view the most recent list of variable names and units accepted by Mesonet API.