Latest

Returns the most recent observation from a station or set of stations

Request Format

A Latest request is an HTTP URL with the following form:

https://api.synopticdata.com/v2/stations/latest

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.

Optional Parameters

• Any number of station selection parameters (optional). Including no station selections will return results for all stations. This can result in extremely large results for services that support it.

• obtimezone (UTC [default], local), Indicates if the time zone of the response is in UTC or the local timezone of the station. Sets the timezone applied to the observation output (input times associated with start and end are always UTC). Example: obtimezone=local. This parameter can’t be used with timeformat=%s.

• showemptystations (0 [default], 1), Indicates if stations with no observations will be returned. Setting to 1 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 will be returned. Default behavior is to remove any variables from the OBSERVATIONS element if no data is present. Setting to 1 will return keys in the OBSERVATIONS element for any requested variables. This guarantees that all keys in the SENSOR_VARIABLES element will be present in the OBSERVATIONS element. Note that if all requested variables are empty you will also need to pass showemptystations=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 States english 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.

• within, Restricts the response to observations within a time window previous to the current time in minutes (e.g. within=60 returns only observations within the last 60 minutes). By default, all latest observations are returned. Note that for stations that have stopped reporting or report infrequently, the latest observations could be days, months or years old.

• minmax, Integer for number of days to show daily minimium and maximum values (up to 7 days previous to current day). Synoptic’s full suite of QC checks are applied to the raw data before calculating min and max values. The minmax arg is required to use this feature. Try it Now

• minmaxtype, (UTC, local [default]), Controls whether min and max values are calculated using the station local day or the UTC day.

• minmaxtimezone, (UTC, local), Controls whether the timestamps associated with the min and max values are returned in local or UTC timezone. (default matches the input to minmaxtype)

• 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 of 0 will exclude these data from data returns.

• sensorvars (0 [default], 1) Indicates if sensor specific metadata for each variable in the SENSOR_VARIABLES element will be returned. Each sensor element contains the following: a position value indicating the height of the sensor, a PERIOD_OF_RECORD value that describes the period of the sensor being active, and a derived_from list of source observations (derived variables only). By default (0), empty objects will be returned within the SENSOR_VARIABLES element, with the exception derived variables which will always show derived_from keys.

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 with obtimezone). This is a special function in addition to the supported strftime arguments.

• output (json [default], 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. Try it Now

  • 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 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 to off then all data will be returned without data checks and quality control (not recommended). If set to on, a QC_SUMMARY object is returned, a QC_FLAGGED: [bool] key will be inside the STATION object, and individual data checks will be in the qc response key for each variable within the OBSERVATIONS object.

• qc_remove_data (on, off, mark), Indicates the response behavior for an observation that fails a user specified data check. (default on if qc parameter omitted, else off if qc=on)

  • off returns the data values even if a data check failure is present for that data.

  • on removes failed data values, returning null. If all values for all requested stations and variables are set to null, a response message of “No stations found for this request” will be returned. If the value for an individual variable is set to null, the variable will not be present in the OBSERVATIONS object.

  • mark replaces failed data with a value of false.

• qc_flags (on, off), Indicates 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 qc response key for each variable within the OBSERVATIONS block. (default off if qc parameter omitted, else on if qc=on)

• qc_checks ([flag name], [flag source], keyword), defines a list of applied data checks. (defaults to sl_range_check if qc parameter omitted, else synopticlabs if qc=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 or madis).

  • “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 if qc_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 check

• qc_checks=synopticlabs,madis, Applies the Synoptic and MADIS QC suites.

Request Response

JSON Format

The Latest 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: {
    solar_radiation: "W/m**2"
  },
  QC_SUMMARY: {
    QC_SHORTNAMES: {
      1: "sl_range_check"
    },
    QC_CHECKS_APPLIED: [
      "sl_range_check"
    ],
    PERCENT_OF_TOTAL_OBSERVATIONS_FLAGGED: 0,
    QC_SOURCENAMES: {
      1: "SynopticLabs"
    },
    TOTAL_OBSERVATIONS_FLAGGED: 0,
    QC_NAMES: {
      1: "SynopticLabs Range Check"
    }
  },
  STATION: [
    {
      STATUS: "ACTIVE",
      MNET_ID: "153",
      PERIOD_OF_RECORD: {
        start: "1997-01-01T00:00:00Z",
        end: "2023-07-31T17:55:00Z"
      },
      ELEVATION: "4806",
      NAME: "U of U William Browning Building",
      STID: "WBB",
      SENSOR_VARIABLES: {
        solar_radiation: { }
      },
      ELEV_DEM: "4727.7",
      LONGITUDE: "-111.84755",
      UNITS: {
        position: "m",
        elevation: "ft"
        },
      STATE: "UT",
      OBSERVATIONS: {
        solar_radiation_value_1: {
          date_time: "2023-08-01T23:15:00Z",
          value: 576.2
        }
      },
      RESTRICTED: false,
      QC_FLAGGED: false,
      LATITUDE: "40.76623",
      TIMEZONE: "America/Denver",
      ID: "1"
    }
  ],
  SUMMARY: {
    DATA_QUERY_TIME: "1.07908248901 ms",
    RESPONSE_CODE: 1,
    RESPONSE_MESSAGE: "OK",
    METADATA_RESPONSE_TIME: "62.3641014099 ms",
    DATA_PARSING_TIME: "0.0760555267334 ms",
    VERSION: "v2.21.0",
    TOTAL_DATA_TIME: "1.15704536438 ms",
    NUMBER_OF_OBJECTS: 1
  }
}

• SUMMARY{}

  • NUMBER_OF_OBJECTS, (always returned) is a integer value of the number of stations returned.

  • RESPONSE_CODE, (always returned) 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, (always returned) is a string explaining the RESPONSE_CODE.

  • RESPONSE_TIME, (always returned) server time to process the request.

• STATION[]

  • SENSOR_VARIABLES[], summary of variables in the OBSERVATIONS element.

  • OBSERVATIONS[], contains all the observational data.

  • QC[], contains all the data attributes.

  • QC_FLAGGED, boolean value indicating data check attributes are returned (if requested).

• QC_SUMMARY{}

  • QC_TESTS_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.