JSON Output Format

The API produces data in the JSON format by default. Fortunately, JSON has native decoders in a large number of programming languages, so you only need to know the structure of the returned data to use it. Each API service outputs a different format of JSON depending on the needs of that service. This section explains the basic JSON structure, as well as a detailed explanation of the /stations service output 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.

Generic JSON structure

Result sets have 4 main elements: STATIONS, UNITS for the variables queried, the SUMMARY and QC_SUMMARY. A successful query will have a SUMMARY like this (where RESULT represents any number of data queries). All services except for the /auth,/variablesand some errors 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 you made.

JSON

{
  "RESULT":  [...],

  "SUMMARY": {
    "NUMBER_OF_OBJECTS": 2,
    "RESPONSE_CODE": 1,
    "VERSION": "v2.21.0",
    "RESPONSE_MESSAGE": "OK",
    "RESPONSE_TIME": "4.48298454285 ms"
  }
}

A query summary contains the following pieces of information (Services available in)

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. (All Services)
`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. (All Services)
`RESPONSE_MESSAGE`	A string representing the same message as the `RESPONSE_CODE`. (All Services)
`VERSION`	The API’s current version number. (All Services)
`METADATA_RESPONSE_TIME`	The amount of time it took for the API to query and parse the metadata. (All Data Services)
`DATA_QUERY_TIME`	The amount of time it took for the API to query the data from the database. (All Data Services)
`DATA_PARSE_TIME`, `DATA_PARSING_TIME`	The amount of time it took for the API to format the queried data into output (All Services except Metadata and Variables)
`TOTAL_DATA_TIME`	The amount of time if took for the API to query and parse the data. (All Services except Metadata, Precipitation and Variables)
`PRECIP_DATA_TIME`	The amount of time it took for the Advanced Precipitation server to query the raw precipitation data, process the data and parse the data. (Precipitation)
`RESPONSE_TIME`	The amount of time if took for the API to query and parse the data. (Variables)
`FUNCTION_USED`	A diagnostic indicator for Synoptic’s developers .(Time Series, QC Segments)

In the event of an error, the structure of the SUMMARY object is discussed in the Errors section of the documentation.

Stations

Station metadata JSON structure.

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.

JSON

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

Default station metadata values

Without complete metadata (&complete=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	Format
`ID`	Internal Synoptic identification number for the station.	string integer
`NAME`	Station name	string
`STID`	Station abbreviation/Identifier	string
`MNET_ID`	Numeric ID of the network	string integer
`ELEVATION`	Elevation above mean sea level in feet	string float
`ELEV_DEM`	Elevation produced by the Digital Elevation Model	string float
`UNITS`	Units for elevation and sensor height (position). Observation units are within the `UNITS` element.	object
`LONGITUDE`	Longitude	string float
`LATITUDE`	Latitude	string float
`STATE`	US or Canadian 2-letter state abbreviation	string
`TIMEZONE`	ISO-8601 compliant station timezone (approximate for offshore and Canadian stations)	string
`STATUS`	String defining if the station is `ACTIVE` or `INACTIVE`	string
`PERIOD_OF_RECORD`	List with the start and end of a station's record	Period of record object
`RESTRICTED` , `RESTRICTED_DATA`	`true` - Public, `false` - Restricted access	boolean

Complete station metadata values

The following additional categories are returned for complete metadata requests (&complete=1).

Parameter	Meaning	Format
`SHORTNAME`	Network short name	string
`COUNTRY`	2-letter Country abbreviation	string
`NWSFIREZONE`	NWS Fire zone	string
`COUNTY`	County in which the station is located	string
`CWA`	NWS County Warning Area (Which NWS Forecast office covers the station location)	string
`NWSZONE`	NWS Forecast zone	string
`GACC`	Geographic Area Coordination Center ID	string
`SGID`	Sub-Geographic Area Coordination Center ID	string
`WIMS_ID`	Weather Information Management System ID	string
`PROVIDERS`	Name and URL of the data provider (if available)	object

Period of record objects

Various areas will indicate a “period of record” for a given platform, variable or other resource. This is always indicated with the key PERIOD_OF_RECORD within the nested object response.

Period of record objects do not recognize timeformat arguments, and the timestamp is always in ISO8601 format.

Parameter	Meaning	Format
`start`	timestamp of the first observation received in the represented category	string (ISO8601 timestamp)
`end`	timestamp of the last observation received in the represented category. May be delayed by several days by infrequent processing	string (ISO8601 timestamp)

Example json of a period of record

JSON

"PERIOD_OF_RECORD": {
    "start": "1997-10-22T00:00:00Z",
    "end": "2002-04-07T17:00:00Z"
  }

Station data JSON Structure

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 2 additional elements added to them. Both are formatted as objects.

New Element	Purpose
`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.
`OBSERVATIONS`	The element which holds variable data and time stamps.

So, this is the generic structure of a Station data query from the API:

JSON

{
    UNITS: {},
    STATION: [
        {
            STATUS: "ACTIVE",
            MNET_ID: "153",
            PERIOD_OF_RECORD: {
              start: "1997-01-01T00:00:00Z",
              end: "2023-07-21T17:30:00Z"
            },
            ELEVATION: "4806",
            NAME: "U of U William Browning Building",
            STID: "WBB",
            SENSOR_VARIABLES: {},
            ELEV_DEM: "4727.7",
            LONGITUDE: "-111.84755",
            UNITS: {
              position: "m",
              elevation: "ft"
            },
            STATE: "UT",
            OBSERVATIONS: {},
            RESTRICTED: false,
            LATITUDE: "40.76623",
            TIMEZONE: "America/Denver",
            ID: "1"
        }
    ],
    SUMMARY: { ... }
}

The SENSOR_VARIABLES element

A list of names of the variables returned from this station. This summarizes the variables which will be found in the OBSERVATIONS element. This section includes sensor specific metadata, which can be useful for stations with multiple sensors reporting the same variable.

This element is returned with the parameter sensorvars=1. When not specified, Latest, Time Series, and Nearest will return empty objects within the SENSOR_VARIABLES element.

New Element	Purpose	Format
`position`	The height/depth of the sensor. (Units are given by `UNITS` in the `STATION` element)	string float
`PERIOD_OF_RECORD`	The period of record for the given sensor.	Period of record object
`derived_from`	For derived variables only, the list of the sensors the variable is derived from.	object

Example of SENSOR_VARIABLES within the STATIONS element:

JSON

STATION: [
  {
    SENSOR_VARIABLES: {
      air_temp: {
        air_temp_value_1: {
          position: "2.0",
          PERIOD_OF_RECORD: {
            start: "1997-04-12T00:00:00Z",
            end: "2023-07-21T21:40:00Z"
          }
        }
      }
    }
  }
]

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 names, and the values are lists. Variable names typically follow the format of var_value_n , where n can be greater than 1 if a station has multiple sensors reporting the same variable (eg. air_temp_value_1). This section will cover the OBSERVATIONS element by services, with each header listing the relevant Weather API service.

The following parameters are common among all OBSERVATION representations

Parameter	Meaning	Format
[variable identifier]`_`[`#`][`d`]	As discussed above, one or more keys for a variable, the variable index (VID) and the letter `d` if the variable was derived by synoptic.	varies
`date_time`	The time the observation indicated was reported	string
`value`	the value of the variable indicated	varies

Latest, Nearest

In this case, each variable contains the date_time the observation was recorded and the value of the observation.

Example Latest output:

JSON

 OBSERVATIONS: {
  air_temp_value_1: {
    date_time: "2023-07-21T11:55:00-0600",
    value: 33.122
  }
}

The time indicated by date_time is the time the observation at value was reported

Time Series, Latency

The variable-date_time relationship is much simpler for Time Series. In this case, all the elements within the OBSERVATIONS element are lists of the same size, and 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.

Example Time Series output:

JSON

OBSERVATIONS: {
  date_time: [
    "2023-07-20T00:00:00Z",
    "2023-07-20T00:05:00Z",
    "2023-07-20T00:10:00Z"
  ],
  metar_set_1: [
    "METAR KBUR 200000Z AUTO 17007KT 10SM CLR 33/11 A2994",
    "METAR KBUR 200005Z AUTO 17008KT 10SM CLR 33/10 A2994",
    "METAR KBUR 200010Z AUTO 17009KT 10SM CLR 33/09 A2994"
  ]

Precipitation

Advanced Precipitation processes raw precipitation data and returns derived precipitation totals or intervals for a requested time period and set of stations. The response JSON for precipitation requests varies based on the pmode requested.

No mode requested

The default precip service functionality is a variant of totals, but its response is distinct.

Parameter	Meaning	Format
`total_precip_value_#`	Precipitation in specified unit computed from precip variable `#`	float
`ob_start_time_#`	Date of first observation included in integration from precip variable `#`	string
`ob_end_time_#`	Date of last observation included in integration from precip variable `#`	string
`count_#`	Number of observations included by precip variable `#`	integer

Example no-pmode response.

JSON

"OBSERVATIONS": {
    "total_precip_value_1": 2.794,
    "ob_start_time_1": "2023-01-01T00:00:00Z",
    "ob_end_time_1": "2023-01-02T00:00:00Z",
    "count_1": 1440
},

When `pmode` is used

The following parameters are returned for Precipitation requests where pmode is defined:

Parameter	Meaning	Format
`total`	Total precipitation (Millimeters by default)	float
`count`	The total number of raw observations to derive the given precipitation total.	integer
`first_report`	Time of the first report (start of the `total`’s period)	string
`last_report`	Time of the last report (end of the `total`'s period)	string
`report_type`	Original recording frequency of the raw precipitation being processed.	string
`interval`	Chronological position of an interval total for a `pmode=intervals` request.	integer
`accum_hours`	The amount of hours totaled for a `pmode=last` request from the requested end.	integer

Pmodes: totals

A distinct element in the precipitation list is made per different type of precip measurement made by the station.

JSON

"OBSERVATIONS": {
    "precipitation": [
          {
              "total": 2.794,
              "first_report": "2023-01-01T00:00:00Z",
              "last_report": "2023-01-02T00:00:00Z",
              "count": 1440,
              "report_type": "precip_accum_one_minute"
          }
    ]
},

Pmodes: intervals

The precipitation list is a collection of the amounts for the given intervals determined by your request. The same keys as totals pmode responses are used, with some additional.

JSON

"OBSERVATIONS": {
    "precipitation": [
          {
              "total": 0.508,
              "first_report": "2023-01-01T00:00:00Z",
              "last_report": "2023-01-01T12:00:00Z",
              "count": 720,
              "interval": 1,
              "report_type": "precip_accum_one_minute"
          },
          {
              "total": 2.286,
              "first_report": "2023-01-01T12:00:00Z",
              "last_report": "2023-01-02T00:00:00Z",
              "count": 720,
              "interval": 2,
              "report_type": "precip_accum_one_minute"
          }
    ]
},

Pmodes: last

A list of objects by report type.

JSON

"OBSERVATIONS": {
      "precipitation": [
            {
                "total": 8.636,
                "first_report": "2022-12-31T00:00:00Z",
                "last_report": "2023-01-02T00:00:00Z",
                "count": 2876,
                "accum_hours": 48,
                "report_type": "precip_accum_one_minute"
            }
      ]
  },

Quality Control Segments

Quality Control Segments checks and returns the duration of associated QC flags for a requested period. The service returns a QC element instead of OBSERVATIONS.

JSON

QC: [
  {
    start: "2018-01-21T17:00:00Z",
    qc_flag: 18,
    sensor: "air_temp_qc_1",
    end: "2018-01-21T17:00:00Z",
    is_open: false
  }
]

The following parameters are returned for Quality Control Segments requests:

Parameter	Meaning	Format
`sensor`	Sensor name and number.	string
`qc_flag`	QC check ID (see QC Types).	integer
`is_open`	If the segment is open. If open, QC checks can continue past	boolean
`start`	Start time of the segment.	string
`end`	End time of segment. If the segment is open, the end time will be time of query.	string

QC Summary JSON structure.

When qc=on is requested (by default), the QC_SUMMARY object will be returned. QC_SUMMARYdetails API the QC check applied and number of violating observations in the following:

JSON

"QC_SUMMARY": {
  "QC_CHECKS_APPLIED": [
    "sl_range_check"
  ],
  "TOTAL_OBSERVATIONS_FLAGGED": 0.0,
  "PERCENT_OF_TOTAL_OBSERVATIONS_FLAGGED": 0.0,
  "QC_NAMES": {
    "1": "SynopticLabs Range Check"
  },
  "QC_SHORTNAMES": {
    "1": "sl_range_check"
  },
  "QC_SOURCENAMES": {
    "1": "SynopticLabs"
  }
},

The QC_SUMMARY contains the following parameters. All string format:

Parameter	Meaning
`QC_CHECKS_APPLIED`	The list of QC check applied (`sl_range_check` only by default)
`TOTAL_OBSERVATIONS_FLAGGED`	The number of observations flagged.
`PERCENT_OF_TOTAL_OBSERVATIONS_FLAGGED`	The percent of observations flagged relative to the total observation requested.
`QC_NAMES`, `QC_SHORTNAMES`, `QC_SOURCENAMES`	Dictionaries mapping string QC type IDs from the `qctypes` service and use in the QC results to more metadata.

Networks

Within the MNET object, the Networks service returns objects per Network containing station statistics and metadata. Example Networks output:

CODE

MNET: [
  {
    CATEGORY: "4",
    REPORTING_STATIONS: 2457,
    TOTAL_RESTRICTED: 0,
    ACTIVE_RESTRICTED: 0,
    LAST_OBSERVATION: "2023-08-02T00:00:00Z",
    URL: null,
    PERCENT_REPORTING: 94.14,
    PERIOD_CHECKED: 120,
    TOTAL_STATIONS: 3527,
    ACTIVE_STATIONS: 2610,
    PERIOD_OF_RECORD: {
      start: "1997-01-01T00:00:00Z",
      end: "2023-08-02T00:00:00Z"
    },
    LONGNAME: "ASOS/AWOS",
    SHORTNAME: "ASOS/AWOS",
    PERCENT_ACTIVE: 74,
    ID: "1"
  }
]

Each object within MNET contains the following parameters:

Parameter	Meaning	Format
`LONGNAME`	Formal name of network.	string
`SHORTNAME`	Short name of network.	string
`ID`	Network ID number (the same as `MNET_ID`).	string integer
`CATEGORY`	Network type, see Network Types service for details.	string integer
`PERIOD_CHECKED`	The interval of time used to calculate analytics. In minutes.	integer
`PERIOD_OF_RECORD`	Furthest extent of reporting history for the network.	Period of record object
`REPORTING_STATIONS`	Number of stations currently reporting in this network. Interval is defined below.	integer
`TOTAL_STATIONS`	Total number of stations assigned to this network.	integer
`ACTIVE_STATIONS`	Number of stations currently set to active status.	integer
`PERCENT_REPORTING`	Percentage of active stations currently reporting data.	float
`PERCENT_ACTIVE`	Number of stations currently set to active status.	float
`LAST_OBSERVATION`	Time stamp of last observation seen.	string
`TOTAL_RESTRICTED`	Number of stations in the network whose data may be restricted for public distribution	float
`ACTIVE_RESTRICTED`	Number of those restricted stations which are active.	float
`URL`	Network/data provider’s URL, if available.	string

Variables

Returns a list of all known variables (sensors) available within the Weather API. Example of the VARIABLES object:

JSON

VARIABLES: [
  {
    air_temp: {
      long_name: "Temperature",
      unit: "Celsius",
      vid: "3"
    }
  },
  ...
]

The objects within VARIABLE contains the following parameters:

Parameter	Meaning	Format
`long_name`	Formal name of sensor or variable.	string
`unit`	Default unit of measure (metric).	string
`vid`	Synoptic variable ID number.	string integer

Network Types

Returns a list of all network categories available within the Weather API within the MNETCAT object, example:

JSON

"MNETCAT": [
  {
    "DESCRIPTION": "Agricultural",
    "ID": "1",
    "NAME": "AG"
  },
  ...
]

The objects within MNETCAT contains the following parameters:

Parameter	Meaning	Format
`NAME`	Short name of network type.	string
`DESCRIPTION`	Description of network.	string
`ID`	Network type ID.	string integer

Quality Control Types

Returns a selection or list of the available data checks provided by both Synoptic Data and our third party providers within the QCTYPES object, for example:

JSON

"QCTYPES": [
  {
    "SOURCE_ID": "1",
    "SHORTNAME": "sl_range_check",
    "ID": "1",
    "NAME": "SynopticLabs Range Check"
  }
]

The objects within QCTYPEScontains the following parameters:

Parameter	Meaning	Format
`ID`	Data check ID. This is the ID used in reporting data attributes.	string integer
`SOURCE_ID`	Numerical representation of the source of the QC check	string integer
`NAME`	Formal name of data check.	string
`SHORTNAME`	Short name description of data check.	string

Generic JSON structure

Stations

Station metadata JSON structure.

Default station metadata values

Complete station metadata values

Period of record objects

Station data JSON Structure

The SENSOR_VARIABLES element

The OBSERVATIONS element

Latest, Nearest

Precipitation

No mode requested

When pmode is used

Pmodes: totals

Pmodes: intervals

Pmodes: last

Quality Control Segments

QC Summary JSON structure.

Networks

Variables

Network Types

Quality Control Types

When `pmode` is used