### Example Precipitation API Request

Source: https://docs.synopticdata.com/services/precipitation

This example demonstrates how to request precipitation data for a specific station ('wbb') over a given time range ('January 2017') using daily intervals. It includes essential parameters like station ID, start and end times, precipitation mode, interval, and a placeholder for the API token.

```HTTP
https://api.synopticdata.com/v2/stations/precip?stid=wbb&start=201701010000&end=201702010000&pmode=intervals&interval=day&token=YOUR_TOKEN_HERE
```

--------------------------------

### Timeseries Endpoint Examples

Source: https://docs.synopticdata.com/services/time-series

Examples demonstrating how to request timeseries data for stations, including filtering by state, recent observations, and specific variables.

```APIDOC
## GET /stations/timeseries

### Description
Requests timeseries data for stations based on various criteria.

### Method
GET

### Endpoint
`/stations/timeseries`

### Query Parameters
- **state** (string) - Optional - Filter stations by state.
- **recent** (integer) - Optional - Request data within the last specified number of minutes.
- **stid** (string) - Optional - Filter by specific station ID.
- **start** (string) - Optional - Start of the time period (YYYYMMDDHHMM).
- **end** (string) - Optional - End of the time period (YYYYMMDDHHMM).
- **vars** (string) - Optional - Comma-separated list of variables to retrieve.
- **precip** (integer) - Optional - Enable derived precipitation (0 or 1).
- **all_reports** (integer) - Optional - Include reports from all precipitation variables (0 or 1, requires `precip=1`).
- **hfmetars** (integer) - Optional - Disable High Frequency NOAA METAR data (0 or 1, default is 1).
- **sensorvars** (integer) - Optional - Include sensor-specific metadata (0 or 1, default is 0).
- **sitinghistory** (integer) - Optional - Include historical siting metadata (0 or 1, requires `complete=1`).
- **timeformat** (string) - Optional - Custom time format string (strftime compatible) or `%s` for Unix time.
- **output** (string) - Optional - Output format (json, csv, xml, geojson, default is json).
- **qc** (string) - Optional - Quality control settings (e.g., 'on', 'off').
- **qc_remove_data** (string) - Optional - Remove data flagged by QC.
- **qc_flags** (string) - Optional - Include QC flags.
- **qc_checks** (string) - Optional - Specify QC checks to perform.
- **token** (string) - Required - API token for authentication.

### Request Example
```
https://api.synopticdata.com/v2/stations/timeseries?state=ut&recent=120&token=YOUR_TOKEN_HERE
```

### Request Example 2
```
https://api.synopticdata.com/v2/stations/timeseries?stid=kslc&start=201501030000&end=201501032359&vars=air_temp&token=YOUR_TOKEN_HERE
```

### Response
#### Success Response (200)
- **OBSERVATIONS** (object) - Contains the observed data.
- **STATION** (object) - Contains station metadata.
- **SUCCESS** (boolean) - Indicates if the request was successful.

#### Response Example (Conceptual)
```json
{
  "SUCCESS": true,
  "STATION": [
    {
      "STID": "KSLC",
      "LONGITUDE": -111.97,
      "LATITUDE": 40.77
    }
  ],
  "OBSERVATIONS": [
    {
      "air_temp": [
        {
          "date": {
            "global": "2015-01-03T12:00:00Z"
          },
          "value": 5.0
        }
      ]
    }
  ]
}
```
```

--------------------------------

### Connect to WebSocket Stream with Python

Source: https://docs.synopticdata.com/services/push-streaming-code-examples

Shows how to connect to a WebSocket stream and receive data using the `websocket-client` library in Python. Requires `pip install websocket-client`. The code establishes a connection and enters an infinite loop to continuously receive and process JSON-formatted messages.

```python
from websocket import create_connection
import json

my_token = "Your API Token"
stream_server = "wss://push.synopticdata.com/feed/"
query_arguments = "units=english&stid=KIAD,KDCA&vars=air_temp,relative_humidity"

# then you simply create your connection
ws = create_connection(stream_server+my_token+"/?"+query_arguments)

# and then you need to read for new messages from the connection. Do this
# using an infinite while loop.

while True:
	data = ws.recv()
	json_data = json.loads(data);

	# and now do things with your received data, before going back to 
	# the socket for another message.
```

--------------------------------

### Request air temperature for a specific station and time

Source: https://docs.synopticdata.com/services/time-series

This example shows how to request only the air temperature for a specific station (KSLC) on a particular date (January 3, 2015). It uses `stid`, `start`, `end`, `vars`, and `token` parameters.

```http
https://api.synopticdata.com/v2/stations/timeseries?stid=kslc&start=201501030000&end=201501032359&vars=air_temp&token=YOUR_TOKEN_HERE
```

--------------------------------

### Get Latest Station Data using Python (requests)

Source: https://docs.synopticdata.com/services/code-examples

This Python example uses the popular `requests` library to fetch the latest station data. API parameters are conveniently passed as a dictionary. This method is generally recommended for its simplicity and robustness.

```python
import requests
import os
API_ROOT = "https://api.synopticdata.com/v2/"
api_request_url = os.path.join(API_ROOT, "stations/latest")
api_arguments = {"token":API_TOKEN,"stid":"KLAX"}
req = requests.get(api_request_url, params=api_arguments)
req.json()
```

--------------------------------

### Modify QC Checks Example

Source: https://docs.synopticdata.com/services/time-series

Demonstrates how to modify the default QC checks by specifying flag sources and specific checks. These examples illustrate targeting different QC suites and individual checks.

```query
qc_checks=synopticlabs,ma_range_check
```

```query
qc_checks=synopticlabs,madis
```

--------------------------------

### Python WebSocket Stream

Source: https://docs.synopticdata.com/services/push-streaming-code-examples

This example shows how to use the `websocket-client` library in Python to connect to a WebSocket stream and receive data.

```APIDOC
## Python WebSocket Stream

### Description
Connect to a WebSocket stream using the `websocket-client` library in Python and process incoming JSON data.

### Method
WebSocket Client Connection

### Endpoint
`wss://push.synopticdata.com/feed/{Your API Token}/?{Query Arguments}`

### Parameters
#### Query Parameters
- **units** (string) - Optional - Specifies the units for the data (e.g., `english`).
- **stid** (string) - Required - Specifies the station IDs to subscribe to (e.g., `KIAD,KDCA`).
- **vars** (string) - Required - Specifies the variables to retrieve (e.g., `air_temp,relative_humidity`).

### Request Example
```python
from websocket import create_connection
import json

my_token = "Your API Token"
stream_server = "wss://push.synopticdata.com/feed/"
query_arguments = "units=english&stid=KIAD,KDCA&vars=air_temp,relative_humidity"

ws = create_connection(stream_server + my_token + "/?" + query_arguments)

while True:
    data = ws.recv()
    json_data = json.loads(data)
    # Process the received JSON data here
    # For example:
    # print(json_data)

```

### Response
Data is received in a loop using `ws.recv()`. Each received message is a JSON string that can be parsed into a Python dictionary for processing.
```

--------------------------------

### Watch WebSocket Stream with WSCat (Bash)

Source: https://docs.synopticdata.com/services/push-streaming-code-examples

Utilizes the WSCat terminal utility to directly monitor a WebSocket stream from the command line. Requires WSCat to be installed, which is a NodeJS-based tool. Ensure the URL with parameters is enclosed in quotes.

```bash
wscat -c "wss://push.synopticdata.com/feed/{Your Token}/?{Arguments}"
```

--------------------------------

### Example JSON Response for Authentication Token

Source: https://docs.synopticdata.com/services/welcome-to-synoptic-data-s-web-services

This snippet displays an example of the JSON response received after successfully creating or listing authentication tokens. It shows a 'TOKENS' array containing a sample token.

```json
{
  "TOKENS": ["a6a82dddc14a46c892077bded6f5a3d6"]
}
```

--------------------------------

### Javascript WebSocket Stream

Source: https://docs.synopticdata.com/services/push-streaming-code-examples

This example demonstrates how to connect to a WebSocket stream using Javascript's native WebSocket API and process incoming messages.

```APIDOC
## Javascript WebSocket Stream

### Description
Connect to a WebSocket stream using Javascript and process incoming messages.

### Method
WebSocket Connection

### Endpoint
`wss://push.synopticdata.com/feed/{Your API Token}/?{Query Arguments}`

### Parameters
#### Query Parameters
- **units** (string) - Optional - Specifies the units for the data (e.g., `english`).
- **stid** (string) - Required - Specifies the station IDs to subscribe to (e.g., `KIAD,KDCA`).
- **vars** (string) - Required - Specifies the variables to retrieve (e.g., `air_temp,relative_humidity`).

### Request Example
```javascript
var my_token = "Your API Token";
var stream_server = "wss://push.synopticdata.com/feed/";
var query_arguments = "units=english&stid=KIAD,KDCA&vars=air_temp,relative_humidity";

function message_received(message_event) {
    var message_json = JSON.parse(message_event.data);
    if (message_json.type == "auth") {
        // Handle authentication message
    } else if (message_json.type == "data") {
        // Handle data messages
        var ob_index;
        for (ob_index in message_json.data) {
            // Process observations
        }
    } else if (message_json.type == "metadata") {
        // Handle metadata messages
    }
}

var socket = new WebSocket(stream_server + my_token + "/?" + query_arguments);
socket.onmessage = message_received;
```

### Response
#### Success Response
Messages are received asynchronously and processed by the `message_received` function. Message types include `auth`, `data`, and `metadata`.
```

--------------------------------

### Fetch Station Metadata using cURL

Source: https://docs.synopticdata.com/services/code-examples

This example demonstrates how to fetch station metadata from the Synoptic Data API using the cURL command-line tool. Ensure the API URL is enclosed in quotes. The output is a JSON file that can be processed further.

```shell
curl "https://api.synopticdata.com/v2/stations/metadata?&token={YourToken}&stids=WBB,MTMET"
```

--------------------------------

### Fetch and Decode Nearest Time Station Data using PHP

Source: https://docs.synopticdata.com/services/code-examples

This PHP example retrieves data for the nearest time station using `file_get_contents` to fetch the API response. The `json_decode` function then converts the JSON string into a PHP associative array or object.

```php
<?php
//Specify Request Parameters
$stid = "WBB";
$within = "1440";
$token = "YourToken";
//Construct the query string
$apiString = "stid={$stid}&within={$within}&token={$token}";
//Get the raw JSON object and convert to a PHP variable
$response = file_get_contents("https://api.synopticdata.com/v2/stations/nearesttime?{$apiString}");
$data = json_decode($response, true); 
// leave off the following true if you would like a PHP object instead of an associative array
//Do stuff with the PHP variable!
?>
```

--------------------------------

### Enable Siting History Metadata (URL Parameter)

Source: https://docs.synopticdata.com/services/percentiles

This parameter enables the return of all historical siting metadata for each station. When enabled, this data is provided as a list within the `SITING` key. To utilize this feature, the `complete=1` parameter must also be enabled.

```text
sitinghistory=1
```

--------------------------------

### WSCat Command Line

Source: https://docs.synopticdata.com/services/push-streaming-code-examples

Use the WSCat utility to watch WebSocket streams directly from the command line.

```APIDOC
## WSCat Command Line

### Description
Use the WSCat terminal utility to directly monitor a WebSocket stream from your command line.

### Method
Command Line Utility

### Endpoint
`wscat -c "wss://push.synopticdata.com/feed/{Your Token}/?{Arguments}"`

### Parameters
#### Command Line Arguments
- **-c** - Connect to the specified WebSocket URL.
- **URL** (string) - Required - The WebSocket URL including token and query arguments. Ensure the URL is enclosed in quotes if it contains special characters.
  - **units** (string) - Optional - Specifies the units for the data (e.g., `english`).
  - **stid** (string) - Required - Specifies the station IDs to subscribe to (e.g., `KIAD,KDCA`).
  - **vars** (string) - Required - Specifies the variables to retrieve (e.g., `air_temp,relative_humidity`).

### Request Example
```bash
wscat -c "wss://push.synopticdata.com/feed/{Your Token}/?units=english&stid=KIAD,KDCA&vars=air_temp,relative_humidity"
```

### Response
Output is streamed directly to the terminal as messages are received.
```

--------------------------------

### Example Period of Record JSON Object

Source: https://docs.synopticdata.com/services/json-output-format

This JSON object represents the 'PERIOD_OF_RECORD' for a given platform or resource. It includes the start and end timestamps of the data, always in ISO8601 format. The 'PERIOD_OF_RECORD' object does not recognize 'timeformat' arguments.

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

--------------------------------

### Get Latest Station Data using Python (urllib)

Source: https://docs.synopticdata.com/services/code-examples

This Python snippet shows how to retrieve the latest station data using the built-in `urllib` library. API parameters are passed directly in the URL. It requires the `os.path` and `json` modules.

```python
import urllib.request as req
import os.path
import json

API_ROOT = "https://api.synopticdata.com/v2/"
API_TOKEN = "[your api token]"
# let's get some latest data
api_request_url = os.path.join(API_ROOT, "stations/latest")
# the built-in library requires us to specify the URL parameters directly
api_request_url += "?token={}&stid={}".format(API_TOKEN, "KLAX")
# Note, .format is a python method available to put values into strings
# then we make the request
response = req.urlopen(api_request_url, api_arguments)
api_text_data = response.read()
```

--------------------------------

### Ruby: API Request and Response

Source: https://docs.synopticdata.com/services/code-examples

This Ruby code retrieves data from an API using the net/http and uri libraries. It constructs a query string with specified parameters (stid, within, token), then makes a GET request to the API endpoint. The response, which is a JSON string, is then extracted.  Additional steps might involve converting the JSON string into a Ruby hash using a JSON parsing library (e.g., 'json').

```ruby
require "net/http"
require "uri"
#To easily convert the returned JSON string to a Ruby hash
#also require "rubygems" and "json"

#Specify request parameters
stid = "WBB"
within = "1440"
token = "YourToken"

#Construct the query string
apiString = "stid="+stid+"&within="+within+"&token="+token

#Parse the API URL and get the body of the response (the JSON)
uri = URI.parse("https://api.synopticdata.com/v2/stations/nearesttime?"+apiString)
response = Net::HTTP.get_response(uri)
dataString = response.body #JSON comes in as a string
#data = JSON.parse(dataString) Converts JSON string to a Ruby hash
```

--------------------------------

### Connect to WebSocket Stream with JavaScript

Source: https://docs.synopticdata.com/services/push-streaming-code-examples

Demonstrates how to establish a WebSocket connection and handle incoming messages in JavaScript (browser or NodeJS). It utilizes the native WebSocket API to parse authentication and data messages from the stream. No external libraries are strictly required for basic functionality.

```javascript
var my_token = "Your API Token";
var stream_server = "wss://push.synopticdata.com/feed/";
var query_arguments = "units=english&stid=KIAD,KDCA&vars=air_temp,relative_humidity";

// first you should define a function that is called every time a message is received
function message_received(message_event) {
	// this function will be called every time there is a new message. And 
	// the message will be given to the function as a special object.
	// First you should extract the JSON object from the message
	var message_json = JSON.parse(message_event.data);

	// and now you can process your streamed data. Use the `type` key to 
	// determine what kind of message it is
	if (message_json.type == "auth") {
		// auth messages contain your session ID, which you can use to 
		// reconnect where you left off if you have network trouble
	

	} else if (message_json.type == "data") {
		// this message contains a list of observations
		var ob_index;
		for (ob_index in message_json.data) {
			//... handle your new observations
		}
	} else if (message_json.type == "metadata") {
		// this is metadata!
	}

}

// we had to define that function first, but now we can connect to the socket
// and set that function to be what is called when a message is received. 

// and create the socket - this connects and starts listening almost immediately.
var socket = new WebSocket(stream_server+my_token+"/?"+query_arguments);
socket.onmessage = new_message;
```

--------------------------------

### JSON Response Example

Source: https://docs.synopticdata.com/services/latest

This is an example of a JSON response from the Synoptic Data Services API. It includes observation data, quality control summaries, and general request information.

```JSON
{
  "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
  }
}
```

--------------------------------

### Retrieve Daily Statistics for Air Temperature

Source: https://docs.synopticdata.com/services/statistics

This example demonstrates how to request daily statistics for air temperature for a specific station (KSLC) over a given date range. It requires a valid API token. The response format can be controlled using parameters like `timeformat` and `output`.

```http
https://api.synopticdata.com/v2/stations/statistics?stid=kslc&vars=air_temp&period=day&start=20250101&end=20250131&token=YOUR_TOKEN_HERE
```

--------------------------------

### Example JSON Response for Variables

Source: https://docs.synopticdata.com/services/variables

An example of the JSON response structure returned by the variables endpoint. It includes a SUMMARY of the request and a list of VARIABLES with their details.

```json
{
  "VARIABLES": [
    {
      "air_temp": {
        "long_name": "Temperature",
        "unit": "Celsius",
        "vid": "3"
      }
    },
    ...
  ],
  "SUMMARY": {
    "NUMBER_OF_OBJECTS": 162,
    "RESPONSE_CODE": 1,
    "VERSION": "v2.21.0",
    "RESPONSE_MESSAGE": "OK",
    "RESPONSE_TIME": "0.19097328186 ms"
  }
}
```

--------------------------------

### Siting History Parameter

Source: https://docs.synopticdata.com/services/percentiles

Explains the `sitinghistory` parameter, which allows retrieval of historical siting metadata for stations.

```APIDOC
## Siting History Parameter

### Description
The `sitinghistory` parameter, when set to `1`, returns all historical siting metadata for each station. This data is provided as a list within the `SITING` key and requires the `complete=1` parameter to be enabled.

### Parameters
#### Query Parameters
- **sitinghistory** (integer) - Optional - Set to `1` to retrieve historical siting metadata.
- **complete** (integer) - Required when `sitinghistory=1` - Set to `1` to enable the retrieval of complete period-of-record data.

### Example Usage
To retrieve siting history for a station:
```
https://api.synopticdata.com/v2/stations/metadata?stid=kslc&sitinghistory=1&complete=1&token=YOUR_TOKEN_HERE
```

### Response Structure (partial)
```json
{
  "SITING": [
    {
      "STATION_ID": "KSLC",
      "START_DATE": "2000-01-01T00:00:00Z",
      "END_DATE": "2010-12-31T23:59:59Z",
      "METADATA": {
        "LAT": 40.7864,
        "LON": -111.9822,
        "ELEV": 1287
      }
    }
    // ... more historical entries
  ]
}
```
```

--------------------------------

### Request all stations in Utah with recent observations

Source: https://docs.synopticdata.com/services/time-series

This example demonstrates how to retrieve all stations in Utah that have had an observation within the last two hours. It utilizes the `state`, `recent`, and `token` parameters.

```http
https://api.synopticdata.com/v2/stations/timeseries?state=ut&recent=120&token=YOUR_TOKEN_HERE
```