Time Series
Returns data for a station or set of stations based on a time span
Request Format
A Time Series request is an HTTP URL with the following form:
https://api.synopticdata.com/v2/stations/timeseries
Acquiring data from this web service requires certain parameters. When encoding URLs, all parameters are separated using the ampersand (&) character and their value is indicated by an equal sign (=). Below is a list of accepted parameters.
token
(required), Your application’s API token. This is used to identify who is requesting API data. You are never required to use multiple tokens, but you can use as many as you need. Learn more in our tokens overview.At least one station selection parameter (required):
Either
start
andend
, orrecent
(one is required but not both)start
&end
, Defines thestart
andend
time of the request with the form of YYYYmmddHHMM. Where YYYY is year, mm is month, dd is day, HH is hour, and MM is minutes. Thestart
parameter must be used with theend
parameter. For example:&start=201306011800&end=201306021215
.All times are requested in UTC, but may be returned in either UTC or local time format for each station. See the
obtimezone
parameter.recent
, Indicates the number of minutes to return, previous to the current time. For example:recent=120
will return the last two hours of observations.
Optional Parameters
obtimezone
(UTC [default], local), Indicates if the time zone of the response is in UTC or the local time zone of the station. Sets the time zone applied to the observation output (input times associated withstart
andend
are always UTC). Example:obtimezone=local
showemptystations
(0 [default], 1), Indicates if stations with no observations will be returned. Setting to1
will return any station meeting the defined time period, variables, and geographic or network parameters, even if there are no observation data available.showemptyvars
(0 [default], 1), Indicates if variables with no observations for the requested time period will be returned. Default behavior is to remove any variables from theOBSERVATIONS
element if no data is present. Setting to 1 will return keys in theOBSERVATIONS
element for any requested variables. This guarantees that all keys in theSENSOR_VARIABLES
element will be present in theOBSERVATIONS
element. For the timeseries service, if other non-requested variables have reported for the requested time period, empty variables will be shown withnull
arrays. However if no station reports are present for the period empty variables will show empty lists ([]
). Note that if all requested variables are empty you will also need to passshowemptystations=1
to retain the station and variables in the response.units
(metric [default], english, [custom format]), Defines the unit of measure for returned data. For standard measurements used by many in the United Statesenglish
will fill most needs. There is also the ability to support custom unit configurations. This is achieved by accessing the variable group such as “temp” and setting the desired unit using a pipe (|
) character. The following list describes the available units for each variable group.temp
(C, F, K), Temperature: Celsius, Fahrenheit and Kelvin.speed
(mps, mph, kph, kts), Speed/Velocity: Meters per second, miles per hour, kilometers per hour, knots.pres
(pa, mb, inhg), Pressure: Pascals, millibars, inches mercury.height
(m, ft), Height: Meters, feet.precip
(mm, cm, in), Precipitation: Millimeters, centimeters, inches.alti
(pa, inhg), Altimeter: Pascals, inches mercury.
Furthermore, it is possible to modify one of the preset settings (metric/english). This is achieved by appending a variable group and unit to the parameter string with a comma. For example, to use “english” units with any speed variables in mph (instead of default knots) the parameter would be
&units=english,speed|mph
.precip
(0 [default], 1), Enable derived precip (Basic Precipitation Service). All raw precip variables will be replaced with two new variables namedprecip_intervals_set_1d
andprecip_accumulated_set_1d
.precip_intervals_set_1d
represents precip received in the intervals between consecutive observations. For ASOS stations, the intervals span between official 1-hr and special METAR reports.precip_accumulated_set_1d
is a cumulative sum of the interval values for the requested time period. Note that precip values will only be reported for complete intervals contained within the requestedstart
andend
. If you are using this service to sum precip for consecutive requests, it is possible that intervals spanning the edges of your request window will not be counted (the Advanced Precipitation Service may be better suited for this request pattern). Passingvars=precip
along withprecip=1
enables return of derived precip without needing to specify an individual precip variable withvars=
, or needing to return all reported variables for a station (omittingvars
). Example:precip=1
orvars=precip&precip=1
all_reports
(0 [default], 1), Indicates if reports from all available precipitation variables should be returned. Some networks (such as ASOS/AWOS) can report precipitation in multiple forms (e.g.precip_accum_one_hour
andprecip_accum_six_hour
). By default, the derived precip returned withprecip=1
will be calculated using the single most representative and consistently reporting variable. (requiresprecip=1
to be enabled)hfmetars
(0, 1 [default]) Disable use of High Frequency NOAA METAR data. This is a variant of the hourly NWS/FAA airport data where observations are recorded approximately every 5 minutes. A value of0
will exclude these data from data returns.sensorvars
(0 [default], 1) Indicates if sensor specific metadata for each variable in theSENSOR_VARIABLES
element will be returned. Each sensor element contains the following: aposition
value indicating the height of the sensor, aPERIOD_OF_RECORD
value that describes the period of the sensor being active, and aderived_from
list of source observations (derived variables only). By default (0), empty objects will be returned within theSENSOR_VARIABLES
element, with the exception derived variables which will always showderived_from
keys.
The following example will request all the stations in Utah with an observation within the last two hours:
https://api.synopticdata.com/v2/stations/timeseries?state=ut&recent=120&token=YOUR_TOKEN_HERE
The following example will request only the air temperature for KSLC (Salt Lake City Airport) on January 3, 2015:
https://api.synopticdata.com/v2/stations/timeseries?stid=kslc&start=201501030000&end=201501032359&vars=air_temp&token=YOUR_TOKEN_HERE
Response Format Parameters
timeformat
, Defines a time format that all time stamps in the data response to be formatted to. By default the API will return time values in ISO 8601 format. This behavior can be changed by passing a string with a valid strftime expression. Below are some common examples.timeformat=%m/%d/%Y at %H:%M
would yield “06/22/2017 at 17:06”timeformat=%b%20%d%20%Y%20-%20%H:%M
would yield “Jun 22 2017 - 17:06”timeformat=%s
returns Unix/POSIX time in terms of seconds (this parameter cannot be used withobtimezone
). This is a special function in addition to the supported strftime arguments.
output
(json [default], csv, xml, geojson), Indicates the response format of the request. It’s recommended to use the JSON format which there are well supported parsing libraries in all major languages.csv
only works when requesting a single station. i.e using thestid
parameter.geojson
will only return the best guess sensor if the station has multiple sensors of the same type.
Data Checks and Quality Control
By default, the API does not return data that has been flagged as non-plausible by the Synoptic Range Check, e.g. a temperature value of 200°C.
If the qc
parameter is omitted then the API will return data while assuming the following: qc=on
, qc_remove_data=on
, qc_flags=off
and qc_checks=sl_range_check
. Note that if the range check removes all values for all requested stations and variables, a response message of “No stations found for this request” will be returned. If the range check removes all values only for certain variables, those variables will not be present in the OBSERVATIONS
object.
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 of data checks, please click here to read more.
qc
(on [default], off), Indicates the application behavior of the QC attributes on the data requested. If set tooff
then all data will be returned without data checks and quality control (not recommended). If set toon
, aQC_SUMMARY
object is returned, aQC_FLAGGED: [bool]
key will be inside theSTATION
object, and individual data checks will be in theqc
response key for each variable within theOBSERVATIONS
object.qc_remove_data
(on, off, mark), Indicates the response behavior for an observation that fails a user specified data check. (defaulton
ifqc
parameter omitted, elseoff
ifqc=on
)off
returns the data values even if a data check failure is present for that data.on
removes failed data values, returningnull
. If all values for all requested stations and variables are set tonull
, a response message of “No stations found for this request” will be returned. If all values for an individual variable are set tonull
, the variable will not be present in theOBSERVATIONS
object.mark
replaces failed data with a value offalse
.
qc_flags
(on, off), Indicates whether the data checks are returned alongside any data that failed a requested check. Ifon
then the data checks will be returned in theqc
response key for each variable within theOBSERVATIONS
block. (defaultoff
ifqc
parameter omitted, elseon
ifqc=on
)qc_checks
([flag name], [flag source], keyword), defines a list of applied data checks. (defaults tosl_range_check
ifqc
parameter omitted, elsesynopticlabs
ifqc=on
)“flag name” allows targeting one or more specific data checks in a comma separated list (e.g.
sl_range_check,sl_rate_check
)“flag source” allows targeting one or more data check providers (
synopticlabs
,mesowest
ormadis
).“keyword” can be one of the following:
basic
,advanced
,all
. Click here to read more about the basic and advanced groups of checks).all
will apply all data checks in our system. Caution: This argument will enable all flag sources, some of which can aggressively flag data, and may remove significant amounts of data ifqc_remove_data=on
.
Some examples of modifying the default QC checks are:
qc_checks=synopticlabs,ma_range_check
, Applies the Synoptic QC suite and MADIS range checkqc_checks=synopticlabs,madis
, Applies the Synoptic and MADIS QC suites.
Request Response
JSON Format
The Time Series service will return its results in a single organized and self describing JSON object. At a minimum, every request will return a JSON object with a SUMMARY
field.
An example JSON response would be:
{
UNITS: {
position: "m",
elevation: "ft",
air_temp: "Celsius"
},
QC_SUMMARY: {
QC_CHECKS_APPLIED: [
"sl_range_check"
],
TOTAL_OBSERVATIONS_FLAGGED: 0,
PERCENT_OF_TOTAL_OBSERVATIONS_FLAGGED: 0
},
STATION: [
{
STATUS: "ACTIVE",
MNET_ID: "1",
PERIOD_OF_RECORD: {
start: "1997-01-01T00:00:00Z",
end: "2023-07-27T23:30:00Z"
},
ELEVATION: "4226",
NAME: "Salt Lake City, Salt Lake City International Airport",
STID: "KSLC",
SENSOR_VARIABLES: {
air_temp: {
air_temp_set_1: {
position: "2.0",
PERIOD_OF_RECORD: {
start: "1997-01-01T00:50:00Z",
end: "2023-07-31T17:54:00Z"
}
}
}
},
ELEV_DEM: "4235.6",
LONGITUDE: "-111.96503",
UNITS: {
position: "m",
elevation: "ft"
},
STATE: "UT",
OBSERVATIONS: {
date_time: [
"2015-01-03T00:00:00Z",
"2015-01-03T00:05:00Z",
"2015-01-03T00:10:00Z",
"2015-01-03T00:15:00Z",
"2015-01-03T00:20:00Z"
],
air_temp_set_1: [
-5.6,
-5.6,
-6.1,
-6.1,
-6.7
]
},
RESTRICTED: false,
QC_FLAGGED: false,
LATITUDE: "40.77069",
TIMEZONE: "America/Denver",
ID: "53"
}
],
SUMMARY: {
DATA_QUERY_TIME: "44.8989868164 ms",
RESPONSE_CODE: 1,
RESPONSE_MESSAGE: "OK",
METADATA_RESPONSE_TIME: "121.969938278 ms",
DATA_PARSING_TIME: "107.047080994 ms",
VERSION: "v2.21.0",
TOTAL_DATA_TIME: "151.947021484 ms",
NUMBER_OF_OBJECTS: 1,
FUNCTION_USED: "time_data_parser"
}
}
SUMMARY{}
NUMBER_OF_OBJECTS
, is a integer value of the number of stations returned.RESPONSE_CODE
, is a numerical code indicating the status of the request.“1” = “OK”
“2” = “Zero Results”
“200” = “Authentication failure”
“400” = “Violates a rule of the API”
RESPONSE_MESSAGE
, is a string explaining theRESPONSE_CODE
.VERSION
, is the API’s current version number.METADATA_RESPONSE_TIME
, is the amount of time it took for the API to query and parse the metadata.DATA_QUERY_TIME
, is the amount of time it took for the API to query the data from the database.DATA_PARSING_TIME
, is the amount of time it took for the API to format the queried data into output.TOTAL_DATA_TIME
, is the amount of time if took for the API to query and parse the data.FUNCTION_USED
, is a diagnostic indicator for Synoptic’s developers.
STATION[]
SENSOR_VARIABLES[]
, summary of variables in the OBSERVATIONS element.OBSERVATIONS[]
, contains all the observational data.QC[]
, contains a time series for each flagged variable (qc_checks
). Returns the specified QC IDs at the same time as the flagged observation.QC_FLAGGED
, boolean value indicating data check attributes are returned (if requested).
QC_SUMMARY{}
QC_CHECKS_APPLIED[]
, a list of data checks that were applied to the data.TOTAL_OBSERVATIONS_FLAGGED
, number of observations that have additional data check attributes.PERCENT_OF_TOTAL_OBSERVATIONS_FLAGGED
, floating point number indicating the percentage of the observations that have additional data check attributes.
UNITS{}
A list of the units of each variable in the
OBSERVATIONS
element.