--- language: "en" --- # National Mesonet Program Synoptic is a prime subcontractor with the US National Mesonet Program, and in this role we facilitate the majority of the aggregation, delivery and compliance monitoring for the program. Synoptic has developed tools for NMP partners who provide the data to be able to monitor their networks and sharing. Visit the [Synoptic's NMP Overview](https://synopticdata.com/national-mesonet-program) and the [National Mesonet Program's website](https://nationalmesonet.us/) for more information. * [Partner Dashboard](https://docs.synopticdata.com/nmp/partner-dashboard.md) --- language: "en" --- # Glossary of terms and labels Explanation of the terms and labels on the Partner Dashboard. | **Term** | **Explanation** | |---------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | Acquisition method | The technical mechanism of data transfer. | | Acquisition type | The broad characterization of whether Synoptic receives data by requesting it (PULL) or if it is delivered to us (PUSH). | | Average latency | Time difference between report timestamps and data availability, averaged for all reporting platforms. | | Contract line item | The NMP contract line item under which this platform's observations are counted. | | Contracted platforms | The number of contracted platforms grouped by contribution type. | | Daily network availability | Days available vs the number of possible days in the period. | | Daily platform availability | The average number of platforms reporting at least once per day compared to the contracted number of platforms. | | Days network was available | The number of days during the period where a connection between Synoptic and the provider was established. | | Days platform was available | Number of days in period the platform made at least one report. | | Expected latency | A summary or average of all expected latency values for all platforms included in the platform inventory. | | Expected total reports | The total number of reports expected in the period based on the expected frequency for all platforms in the network. If a network includes more platforms than contracted, this value is the lowest number of expected reports for the number of platforms contracted. | | Fractional hours | Number of hours on road measured against 160-hour threshold. | | Hourly network availability | Hours available vs the number of possible hours in the period. | | Hours (vehicle) | Number of hours on road. | | Hours network was available | The number of hours during the period where a connection between Synoptic and the provider was established. | | MADIS category | How MADIS is expected to categorize the data from this provider. This is for reference purposes and does not affect how MADIS has actually categorized any provider data. | | Network availability | Hours network is accessible by Synoptic systems. | | Platform category | Platform categorization: Professional Plus (Pro+) or Professional (Pro) (if applicable). | | Platform expected latency | A provided description of the expected amount of time required for the average observation from a given site to be delivered to Synoptic and/or MADIS. | | Platform provider identity | The name and identifier of the platform provided to Synoptic. | | Platform received reports | The total number of reports received from the platform during the period as well as a percentage of the expected number of reports during the period given the provided expected frequency. | | Platform report latency | The average amount of time between when an observation timestamp is assigned and when it is received at Synoptic for the period. | | Platform reporting frequency | Provided expected interval between report timestamps in minutes. This is the inverse of the number of reports per unit time. | | Platforms | The number of distinct mobile platforms that reported obesrvations in the period. | | Platforms (aircraft) | The number of distinct aircraft that reported observations in the period. | | Platforms (surface mobile) | Total number of vehicles reporting in the period. | | Platforms available in period | The total number of platforms that reported at least once during the period compared to the contracted number of platforms. | | Platforms included in inventory | The number of unique platforms for which metadata has been provided and no request to remove has been received. This is neither a function of data flow nor contract expectations. | | Platforms meeting requirements | Number of platforms operating as measured against the 160-hour reference value threshold (20 days per month, 8 hours per day). | | Platforms reporting daily | The average number of platforms reporting each day over the entire period. | | Platforms reporting in period | The number of platforms that reported at least once during the period. | | Possible platform reports | Daily reports received vs the number of reports that would be expected if every site included in the inventory were reporting. Can be above 100% if stations report more frequently than expected. | | Received reports | The total number of unique timestamps indicated from every included platform in the network inventory. | | Report percentage | Percentage of received reports to expected reports for all contracted platforms, based on the expected reporting frequency of each contracted platform. More information [here](https://docs.synopticdata.com/nmp/how-report-percentage-is-calculated.md). | | Soundings | Total number of ascents and descents. | | Synoptic platform identifier | A unique 5-10 character identifier used by Synoptic to process data and metadata for a platform. Due to issues of platform ID reuse, these identifiers often differ from those used by a provider. | --- language: "en" --- # How report percentage is calculated The NMP monitoring dashboard displays a commitment compliance as a function of the number of reports received from the network compared to the total number of reports expected from that network. Reports (also known as "observations") are considered a unique timestamp for conventional surface monitoring platforms, and may be aggregated into timed chunks around 5 or 10 minutes depending on network for platforms which report different variables at different timestamps. This means that your total monthly contribution percentage is not a function of how many stations were available, either in the month or on any given day, or the network availability metric (which was the standard prior to 2021). When viewing the NMP Partner Dashboard, the total reports percentage is the average of the daily reports percentage bar graph values. So when those go down, the total percentage goes down. If issues are suspected with these calculations you are encouraged to use the feedback form on the NMP application. ## Expected reports Expected reports are directly derived from the expected reporting frequency from the platform. If this information is provided as part of the network commitment metadata, then that is used, otherwise we will estimate an expected reporting frequency from existing data. Providers are encouraged to contact us if the expected frequency for any station is inaccurate. ## Impact from uneven distribution of reports Because the total number of reports from a month is the primary factor, a network where all the stations report on the same frequency will (with caveats) be consistent between the daily availability of stations, and the total report percentage. However if a network has some stations which contribute more observations to the total than others, this will skew the importance of those higher-resolution stations to your total contribution, and losing one of those will more substantially impact the performance statistics. --- language: "en" --- # Partner Dashboard Table of Contents * [How report percentage is calculated](https://docs.synopticdata.com/nmp/how-report-percentage-is-calculated.md) * [Glossary of terms and labels](https://docs.synopticdata.com/nmp/glossary-of-terms-and-labels.md) The NMP Dashboards are resources intended for NMP partners to monitor their ongoing performance for data provisions to the National Mesonet Program. Numbers reflected in the dashboards are based on information Synoptic received either directly through partner data feeds or through partner inventory spreadsheets. ## Period of performance summaries Period summaries are an analyzed report of partner contribution for periods of performance as defined in the contract. The numbers in these reports reflect Synoptic's best understanding of your contribution to the NMP. When viewing your network, the most recent or real-time period of performance summary will always be the default view. Summaries are generated each day around 12UTC for the period leading up to the end of the previous day. Each period of performance summary will be used to determine partner performance and contribution which will inform compensation. There may be discrepancies in terms of platforms and contribution parameters in historical periods as they are intended to reflect exactly what Synoptic understood regarding that provider at that time. ### Historical periods Once produced, summaries remain available for viewing indefinitely. These can be accessed by the month and year buttons at the top of the interface. There may be discrepancies in terms of platforms and contribution parameters in historical periods, as they are intended to reflect exactly what Synoptic understood regarding that provider at that time. ### Interface resources There are a few tools in the interface to help providers manage their reporting. #### Add a platform This button will take you from your provider dashboard to a special form that can be used to submit important metadata about new platforms in your network. While Synoptic often is able to aggregate basic platform metadata through our ingest and counting processes, other information, such as that requested in this form, is harder to automatically identify. Please use this form to alert the Synoptic NMP team for each new platform in your network. #### Feedback Use the Feedback button to let the Synoptic NMP team know if you have any questions or comments regarding the overall dashboard structure/look or your particular network. We will respond to you via email if necessary. #### Report outage At the top of each provider dashboard, there is a "Report outage" button in which anyone with dashboard access may submit a report of a network or individual station outage to the Synoptic NMP team. These submissions are recorded but do not have any direct affect on monitoring or statistics. --- language: "en" --- # Contribute Data to Synoptic Synoptic Data is a Public Benefit Corporation building on the legacy of MesoWest that was developed over the past two decades at the University of Utah. Synoptic Data facilitates the efficient exchange of data available from diverse sources to allow government agencies, businesses, individuals, and communities to rapidly and equitably access environmental information for use in their daily activities, operations, and decision making. Synoptic strives to foster a collaborative exchange of environmental information that helps sustain the mission of data providers. Data providers control whether they prefer their data to be available to all potential users or limited to specific user communities. Data distributed by Synoptic undergo a battery of automated tests that help data providers know if sensor maintenance may be required. All publicly accessible data sent to Synoptic Data will also appears on all MesoWest products and web pages. The same data ingest system is used. ## How do I provide data to Synoptic? If you are interested in providing real-time observations to Synoptic Data, there are several options: ### 1) I have a personal weather station, and I would like to make my real-time observations available to Synoptic Data. Synoptic Data can most easily access personal weather stations if they are part of the Citizen Weather Observing Program (CWOP). The National Weather Service El Paso, TX has put together very useful guides ([linked here](https://www.weather.gov/epz/cwopEPZ)) on how to select CWOP-compatible weather station equipment, site the equipment, and configure hardware and software so that the data are transmitted to the CWOP system. Once the real-time data are in the CWOP system, Synoptic Data has access to it with no additional work required. If you have enabled a weather station in CWOP, and can see the data in the CWOP system but not in Synoptic Data, feel free to contact us and we can investigate if there are any issues with getting the real-time data. ### 2) I manage data collection for multiple weather stations, and I wish to make the real-time observations available to Synoptic Data. Data providers can share their data with Synoptic Data in many different ways. Our goal is to simplify the data transmission process as much as possible. To start, feel free to contact us with some information on your assets and which transfer method(s) might work best for your system. Even if your preferred method isn't listed below, Synoptic Data would be happy to discuss other potential ways to get your real-time observations flowing. In order to add assets to Synoptic Data, the following minimum metadata (data about the metadata) is required: * Station Name * Abbreviated and/or full name (ex. KHOU - Houston, Houston Hobby Airport) * Geographic Coordinates * Latitude and Longitude * Elevation above sea level We will attempt to use station identifiers you define as long as they don't conflict with one of the over 50,000 stations in our databases (to check our inventory yourself, use our [Explore Tool](https://synopticdata.atlassian.net/l/cp/CxeYvrpZ)). We also need to know how the data are reported: * Variable Types * Units * Reporting Frequency * Regular Interval Reporting (ex. every 5 minutes, daily) * Event Driven #### a) Data Pull Procedures Synoptic Data can develop scheduled pull mechanisms that query real-time data from accessible data repositories (HTTP, HTTPS, FTP, SFTP, etc.) your organization might host or maintain. Synoptic Data can access the data files themselves, the output of developed API services, or other forms of data depending on what your organization may prefer. #### b) Data Push Procedures Synoptic's modern cloud-based architecture leverages scalable, redundant technology to optimize our operations. In the Amazon cloud where much of Synoptic's operations are located, this means Amazon's S3 data object storage service is a robust and reliable platform to exchange data. [Learn more about pushing data to Synoptic with Amazon S3](https://docs.synopticdata.com/providers/pushing-data-via-amazon-s3.md) If your organization prefers to send the real-time data, Synoptic Data can do so. Data ingest servers have been configured to accept routine FTP, SFTP, and SCP pushes of data files. To utilize one of these methods, Synoptic Data will need to create an account for you on one of the ingest servers. Synoptic Data also has an actively running Local Data Manager (LDM) server for those entities who may wish to use that as a data push mechanism. #### c) Campbell Scientific Data Logger Access Synoptic Data operates a 24/7 Campbell Scientific LoggerNet Server, which can access Campbell data loggers reachable via an IP/hostname and port number. If desired, Synoptic Data can set up procedures to collect and immediately process new observations directly from data loggers themselves, which eliminates the intermediate steps of collecting and then sending the data. Synoptic Data would work with your organization on selecting a proper data collection schedule so that power and communications costs are considered. --- language: "en" --- # Data Formatting Best Practices Synoptic is extremely flexible regarding accepted data representations. We have a team of data scientists and engineers on staff who use powerful tools and cloud technology to quickly understand and ingest any data format. This is how Synoptic has been able to aggregate legacy TAC formats like METAR, SHEF, and SYNOP, binary formats like NetCDF, BUFR, and HDF, and structured formats like CSV, JSON, and XML. We receive these formats of data in a variety of ways. Most commonly this will be data files, exchanged by [Pushing data via Amazon S3](https://docs.synopticdata.com/providers/pushing-data-via-amazon-s3.md) or classic S/FTP, LDM. We also perform ingest via streaming methods, including MQTT and WebSocket. Additionally we pull data in many formats from various forms of web endpoints, such as APIs. Across all these techniques, there are a few best practices for downstream usability of your data. ## 1. Use metric units Synoptic's system, and many downstream applications require the use of metric or SI units. For the most part Synoptic's internal system will store your observation data in its metric units (see [our variable list](https://variables.docs.synopticdata.com/) to see our storage units). When we convert units we attempt to retain your precision where possible, but some conversions are imprecise (such as Fahrenheit to celsius). Sending data as metric allows us to skip this change. Data are re-converted to English or other units by our API and other delivery services. ## 2. Use predictable structure keys When providing structured data, such as JSON or XML, use structures which provide constantly predictable keys. This means the data is structured and repeatable. It also may produce a less efficient structure, for instance { "temperature_1":12, "temperature_2":15, "wind_speed_1":5 } Conversely, a structure which uses predictable keys for this data would be { "measurements":[ { "variable":"temperature", "sensor":1, "value":12 }, { "variable":"temperature", "sensor":2, "value":15 }, { "variable":"wind_speed", "sensor":1, "value":5 }, ] } This is less efficient, yes, but is much easier to read with software. --- language: "en" --- # Pushing data via Amazon S3 Synoptic data aggregation leverages Amazon's S3 object storage service as a platform for receiving data from providers in a secure and highly available manner. ## About S3 S3 stands for "Simple Storage Service" and it is an object storage service operated by Amazon's AWS, which is used to upload and download data. Objects in this context can be thought of as files with names. Using standardized technical interfaces, any provider can securely connect to the Amazon S3 service, and publish their data files. S3 requires object storage service interfaces, you generally cannot use older technologies like SFTP or SCP to interface with any object storage services. Synoptic leverages AWS functionalities on top of S3, such as services to trigger automatic processing of newly uploaded files to quickly ingest the submitted data. Amazon S3 is one of many object storage services which generally utilize the same mechanics for interaction. These include Pandas, and other cloud vendors also operate equivalent services. ### Core concepts The two main concepts in s3 are the **bucket:** isolated inventories of objects, and **keys:** (not to be confused with access keys) which is the location of the object - essentially the file path. Synoptic gives providers exclusive access to a single bucket for publishing data. You can store an unlimited number of objects in a bucket, and the use of slashes in keys (e.g. `a/b/c`) is optional (the key is the whole string), but is used by some file browsers to organize objects. We encourage using different objects to upload additional data. Using timestamp-related factors to define keys can be useful for optimizing reading, but the main efficiency considerations come from **avoiding pushing data you already pushed,** and**avoiding overwriting existing data.** ## Synoptic's ingest buckets To facilitate data ingest, Synoptic uses [multi-region access points](https://aws.amazon.com/s3/features/multi-region-access-points/) (MRAP) as the front door for S3-based data object pushes. For providers, these function identically to any bucket. For providers, our MRAPs mean your data pushes travel the minimum distance before reaching AWS infrastructure. Pushes from Europe will route to buckets in Europe, for instance. This reduces dependency on variably implemented global telecommunications infrastructure, and instead puts the load on the Amazon internet backbone. For Synoptic, our MRAPs ensure that data pushed to our platform is reliably received even if the normal region for your data ingest is disrupted. When our ingest team is configuring your push, we will share the MRAP bucket endpoint ARN and the path/key prefix which has been designated for your dataset. When using an MRAP endpoint, Synoptic only permits `put_object` events. This means you **cannot list, read, move, or delete the objects currently in the bucket**. For this reason it is important to follow the recommended naming conventions and ensure files published will not overwrite each other. ## Accessing S3 You will need to access S3 either programmatically, or via a file browser tool like [Transmit](https://panic.com/transmit/), much like SFTP. To authenticate there are 3 options we support ### Authenticating with AWS Roles The most robust way for us to provide you secure access to a bucket is to use AWS's IAM system. If a provider already operates in AWS, we can simply permit a role from your account to write data to a bucket we own. That way we never have to exchange credentials. A provider who does not operate in AWS can also implement methods to assert identity with AWS via the use of trusted certificates. This arrangement is more complicated and can be configured with individual providers and our ingest engineering team. ### Authenticating with keys and secrets A simpler but ++less preferred++ method to access an S3 bucket is provisioned keys and secrets. A provider can be securely provided these credentials, and then the code that publishes the data would use those values to access the bucket. This is much less secure as compromised keys can be used by others. To reduce this risk, we require providers using keys to **update them annually if not more frequently** depending on your compliance requirements. Our ingest team will ensure you securely use these credentials, and are able to update them on our cycle. AWS credentials are very different from Synoptic product credentials. If this is the right option for you, we will provide credentials to you. ### Accessing a bucket you own A third option, which is really a variant of the first, is a reverse process, we can access an object storage that you own. If you are using AWS S3, we can work with you to configure role based access for our data provider account, and then we can read and track your data. If you use an alternative object store service, we would treat that as a fetch access, which is not addressed in this guide. It is very secure for us to access a bucket in your control, but it does require you to have your own AWS account. ## Programmatic access Because S3 uses an open protocol, there are a variety of software tools and packages that can be used to connect. Because we are specifically addressing the Amazon AWS service, the easiest ways to implement the full authentication process would be to utilize one of the [AWS Developer toolkits](https://aws.amazon.com/developer/tools/), such as `boto3` for Python. It would be best to refer to the documentation relevant to the toolkit you use, but the following functions will likely be used * Functions for targeting a bucket (we will give you the bucket reference) * Functions for uploading data (such as `put object`) * Functions for reviewing and reading data, including `list objects v2` and `get object` Functions will normally use these expressions. If you receive an error, read it carefully, it likely specifies a function you are calling which we likely did not grant permission to perform. As always, contact our provider help desk for any assistance. ## Helpful scripts The following scripts are examples, using python and `boto3` of how you can interface with an S3 bucket ### Set up credentials for boto3 client Python local_file_path = 'data.csv' # Path to the local file to upload bucket = 'provider-hex' # Replace with your S3 bucket name s3_filename = 'data.csv' # Desired S3 key for the uploaded file / Same as local file name # Load credentials from the access keys file with open('provider_accessKeys.csv', 'r') as f: lines = f.readlines() access_key = lines[1].strip().split(',')[0] secret_key = lines[1].strip().split(',')[1] # Set up boto3 client with the loaded credentials boto3.setup_default_session(aws_access_key_id=access_key, aws_secret_access_key=secret_key) It is recommended to use your own AWS account and request access to a bucket to send to. This is more secure and prevents the need for access key rotation in the future. ### Upload a file to S3 Python def upload_file_to_s3(file_path, bucket_name, s3_key): """ Uploads a file to an S3 bucket. Args: file_path (str): Local path to the file to be uploaded. bucket_name (str): Name of the S3 bucket. s3_key (str): The key (filename) to use in the bucket. """ # Initialize S3 client s3 = boto3.client('s3') try: # Upload the file s3.upload_file(file_path, bucket_name, s3_key) print(f"File '{file_path}' uploaded to bucket '{bucket_name}' with key '{s3_key}'.") except Exception as e: print(f"An error occurred while uploading: {e}") ### Check if a file was uploaded Python def verify_file_in_s3(bucket_name, s3_key): """ Verifies if a specific file exists in the S3 bucket. Args: bucket_name (str): Name of the S3 bucket. s3_key (str): The key (filename) to check in the bucket. Returns: bool: True if the file is found, False otherwise. """ # Initialize S3 client s3 = boto3.client('s3') try: # List objects in the specified bucket response = s3.list_objects_v2(Bucket=bucket_name) if 'Contents' not in response: print(f"The bucket '{bucket_name}' is empty or the key does not exist.") return False # Check if the specified file (s3_key) is present in the bucket filenames = [item['Key'] for item in response['Contents']] if s3_key in filenames: print(f"File '{s3_key}' exists in the bucket '{bucket_name}'.") return True else: print(f"File '{s3_key}' not found in the bucket '{bucket_name}'.") return False except Exception as e: print(f"An error occurred: {e}") return False --- language: "en" --- # Product and Service Documentation ## About *This knowledge base covers the details of Synoptic's data services. From* [*Getting Started*](https://docs.synopticdata.com/services/welcome-to-synoptic-data-s-web-services.md)*with Weather API to* [*visualizing the extent of available observations*](https://docs.synopticdata.com/services/synoptic-data-viewer.md)*, this knowledge base has you covered.* ### Get in contact For all your web service related inquiries and help email [support@synopticdata.com](mailto:support@synopticdata.com). ### Weather API 🌎 Data * [Time Series](https://docs.synopticdata.com/services/time-series.md) * [Latest](https://docs.synopticdata.com/services/latest.md) * [Nearest Time](https://docs.synopticdata.com/services/nearest-time.md) * [Precipitation](https://docs.synopticdata.com/services/precipitation.md) * [Statistics](https://docs.synopticdata.com/services/statistics.md) * [Percentiles](https://docs.synopticdata.com/services/percentiles.md) * [QC Segments](https://docs.synopticdata.com/services/quality-control-segments.md) πŸ‘€ User Access and Data * [Your Account](https://docs.synopticdata.com/account.md) * [Data Access Credentials](https://docs.synopticdata.com/account/data-access-credentials.md) * [Public API Tokens](https://docs.synopticdata.com/account/public-api-tokens.md) * [Latency](https://docs.synopticdata.com/services/latency.md) * [Commercial Free Trial](https://docs.synopticdata.com/account/commercial-free-trial.md) πŸ“„ Metadata * [Metadata](https://docs.synopticdata.com/services/metadata.md) * [QC Types](https://docs.synopticdata.com/services/quality-control-types.md) * [Variables](https://docs.synopticdata.com/services/variables.md) * [Networks](https://docs.synopticdata.com/services/networks.md) * [Network Types](https://docs.synopticdata.com/services/network-types.md) ### More Services πŸ” Viewing and Analytics * [Synoptic Data Viewer](https://docs.synopticdata.com/services/synoptic-data-viewer.md) * [Availability](https://docs.synopticdata.com/services/data-availability-dashboard.md) * [Explore Tool](https://docs.synopticdata.com/services/explore-tool.md) (legacy) 🌐 Data Services * [Data Download Tool](https://docs.synopticdata.com/services/data-download-tool.md) * [Push Streaming](https://docs.synopticdata.com/services/push-streaming.md) * [Contribute Data to Synoptic](https://docs.synopticdata.com/providers.md) ### About the data πŸ—ΊοΈ The Mesonet Dataset * [Station Variables](https://docs.synopticdata.com/services/station-variables.md) * [Station Networks \& Providers](https://docs.synopticdata.com/services/station-networks-providers.md) * [Network Types Table](https://docs.synopticdata.com/services/network-types-table.md) βœ… Quality control * [Mesonet Data QC](https://docs.synopticdata.com/services/mesonet-data-qc.md) * [QC Flag Types](https://docs.synopticdata.com/services/qc-flag-types.md) 🌧️ Interpreting the Data * [In-situ atmospheric measurement overview](https://docs.synopticdata.com/services/in-situ-atmospheric-measurement-overview.md) * [Weather Condition Codes](https://docs.synopticdata.com/services/weather-condition-codes.md) * [Cloud Height and Sky Condition](https://docs.synopticdata.com/services/cloud-height-and-sky-condition.md) * [Road surface condition codes](https://docs.synopticdata.com/services/road-surface-condition-codes.md) * [High Frequency ASOS](https://docs.synopticdata.com/services/high-frequency-asos.md) * [Precipitation Service Explained](https://docs.synopticdata.com/services/precipitation-service-explained.md) * [Statistics and Percentiles Services Explained](https://docs.synopticdata.com/services/statistics-and-percentiles-services-explained.md) *** ** * ** *** ### Synoptic Support Providing support and information for all of Synoptic Data's services. #### Get Support * [support@synopticdata.com](mailto:support@synopticdata.com) #### Related Links * [Synoptic Data](http://synopticdata.com/) * [Data Disclaimer](https://synopticdata.com/data-disclaimer) * [Terms and Conditions](https://synopticdata.com/tcs) --- language: "en" --- # About Data The articles in this directory are meant to help you understand characteristics of the various datasets Synoptic aggregates and distributes. πŸ—ΊοΈ [The Synoptic Dataset](https://docs.synopticdata.com/services/the-mesonet-dataset.md) * [Station Variables](https://docs.synopticdata.com/services/station-variables.md) * [Station Networks \& Providers](https://docs.synopticdata.com/services/station-networks-providers.md) * [Network Types Table](https://docs.synopticdata.com/services/network-types-table.md) 🌧️ Interpreting the Data * [In-situ atmospheric measurement overview](https://docs.synopticdata.com/services/in-situ-atmospheric-measurement-overview.md) * [Precipitation Service Explained](https://docs.synopticdata.com/services/precipitation-service-explained.md) * [Weather Condition Codes](https://docs.synopticdata.com/services/weather-condition-codes.md) * [Cloud Height and Sky Condition](https://docs.synopticdata.com/services/cloud-height-and-sky-condition.md) * [Road surface condition codes](https://docs.synopticdata.com/services/road-surface-condition-codes.md) * [High Frequency ASOS](https://docs.synopticdata.com/services/high-frequency-asos.md) * [Statistics and Percentiles Services Explained](https://docs.synopticdata.com/services/statistics-and-percentiles-services-explained.md) βœ… [Quality control](https://docs.synopticdata.com/services/quality-control.md) * [Synoptic Data QC](https://docs.synopticdata.com/services/mesonet-data-qc.md) * [QC Flag Types](https://docs.synopticdata.com/services/qc-flag-types.md) --- language: "en" --- # API Performance and Limits This article provides clarity around the performance and limitations users will experience using the Weather API. ## API Performance In the Open Access Tier, API Performance can vary widely based on the number of users and the amount of data being requested. High request volume or requests for large amounts of data can increase API response times, as the resource pool is shared with all Open Access users. In the Commercial Tier, there is a dedicated resource pool that scales to meet API request volume. The scaling pool allows for consistent performance and response times during periods of increased API traffic. ## Number of Simultaneous Responses (concurrency) The number of simultaneous responses are the number of concurrent requests that are processed by the Weather API at the same time. Our system allows up to 20 requests at a time, which by default are processed consecutively one at a time (concurrency of 1). If you have a concurrency of 5, then up to 5 requests can be processed at once. ![Concurrency Diagram.png](https://docs.synopticdata.com/__attachments/a_901dc44a5e33b4cdabe7435619fc0124d3bfea54c7754da4ed6bd72ffd6f306f/Concurrency%20Diagram.png?cb=e740cb1abd0c624da3ddc3eaa2cd436f) Example: If each request takes 1 second, and you have a concurrency of 1, it would take a total of 20 seconds to get back all of your 20 requests. If each request takes 1 second, and you have a concurrency of 5, it would only take 4 seconds to get back all of your 20 requests. ## Request Volume Limitations All Weather API requests in the Timeseries and Nearest Time services are limited to 100,000 station-hours per request. A "station-hour" is calculated as (number of stations) x (number of hours in the requested time range). For example, requesting data from 5 stations for a single day represents (5x24)=120 station hours. If you exceed station-hour limits you will receive a response message such as `"Querying too many station hours. 929139120.0 hours were requested."` The Latest service is limited to 75,000 stations, and does not allow open-ended requests for "all" stations. You must include a station selection parameter or the `within` parameter. If you exceed station limits you will receive a response message such as `"Latest service requests are limited to 75000 stations. This request matched 96339 stations. Please narrow the request with station, network, country, state, bbox, radius, or a smaller within window."` The Statistics service is limited to 2 million station-hours. The Percentiles service is limited to 50,000 stations, with a specific limit for hourly percentiles (`data=hourly`) of 150,000 station-hours. The Precipitation service has request volume limits depending on the `pmode` used. Please follow up with [support@synopticdata.com](mailto:support@synopticdata.com) if you are running into issues with request volume limitations and we can work with you to improve your request pattern. ### General guidance for dealing with requests that are at a limit There are numerous, reasonable request patterns which may result in exceeding these limitations. Sometimes you will exceed the limit when attempting to establish a query pattern. Other times the growth of the dataset available to you means that a query pattern which used to work now exceeds limits. In each of these cases the best practice is to **monitor your usage if you are getting close** and implement a form of pagination which makes sense for your usage model. #### Monitoring your usage Most query patterns include known durations, so you can use the period you are requesting - such as a 4 hour time series, and know that if your station set is approaching 25,000 stations, you may be at risk. Synoptic's dataset grows substantially year over year, but depending on your access, data available to you may not (airport-only access will only grow \~1% each year, whereas resell networks can add 20-30% in a year). #### Implementing a pagination strategy There is no single pagination strategy recommended for accessing Weather API results. You will need to break up your request into chunks that will reliably stay below the limit, following the monitoring strategy discussed above. Some options available to you are: * Querying for specific stations - this gives you the maximum control. You can use the metadata service to identify the stations of interest, and then pass lists of stations up to your limit to get responses. There is no limit on the API's query length, however your method of creating URLs may have limits. * Query by time - if you are making requests with a time dimension, and if your usage can handle it, you can split up your series by time. Note inclusivity of begin and end times from the documentation of the service you are using - but a full series can generally be reconstructed this way. * Spatial pagination is a straightforward, but tricky, way to divide usage. It is important to recognize the variation in area for various spatial zones (such as states) and variations in spatial density (ocean vs land) mean that simple spatial implementations may still be at risk if stations are not well distributed among your selections. * Bounding boxes - you can subdivide the spatial selection you have using BBOXes to ensure the number of stations in your selection is well below the limit. * Other spatial selectors - states, countries, counties, etc - You can develop strategies to use these, but you will experience difficulty getting even distribution of stations, and risk some of your queries still exceeding the limitations. * Utilize spatial thinning - this is designed for display applications, but can be configured to reduce the data you receive. You will receive only a subset of the data accessible to you in this method, but you can largely guarantee staying within a range of values in most cases. ## Spatial Limitations Depending on usage and tier level, certain spatial limitations may be placed on users and reflected within their API request output. These limitations are listed among the features for [Open Access](https://synopticdata.com/open-access) and [Commercial](https://synopticdata.com/commercial-pricing) tiers. For example, an API user with access only to observations within Germany querying the Latest Service for Global METAR stations will not receive observations from any other European country outside Germany. ## Historical Data Access Similarly to Spatial Limitations, depending on usage and tier level, temporal limitations may be placed on users and reflected within their API request output. These limits are defined in years previous to the current time. These limitations are listed among the features for [Open Access](https://synopticdata.com/open-access) and [Commercial](https://synopticdata.com/commercial-pricing) tiers. For example, an API user with 1 year of historical data access makes a Time Series request at 12:42 UTC on June 20th, 2023 for data spanning from January 1, 2000 to the current time. Within the API response, they would receive data from 12:42 UTC June 20th, 2022 until 12:42 UTC June 20th, 2023, excluding data before June 20th, 2022. Consider your usage tier and contract settings if you notice potentially missing data for a successful request. Correctly formatted queries will only return data for active stations that are within contract-defined spatial and historical limits. If you see a response message such as `"No stations found for this request, or your account does not have access to the requested station(s)."`, then either no data is available for the requested parameters, or the stations are not provisioned in your contract settings. --- language: "en" --- # ASOS/AWOS (United States METAR) Synoptic's oldest and most widely used dataset is the `ASOS/AWOS` network, mesonet ID `1`. ASOS/AWOS combines two *independent* data sources into a single time series. 1. The official **METAR** feed for the United States and neighboring countries - covering every airport that produces METAR and SPECI observations. These come from 3 types of platforms. ASOS stations, AWOS stations, and manual reports. Synoptic does not know which station is which type of equipment. 2. A 5-minute sample of the [High Frequency ASOS](https://docs.synopticdata.com/services/high-frequency-asos.md) dataset produced by NOAA and shared publicly. A "METAR" string is created for these messages, but this is not a genuine METAR. This is referred to as "HFMETAR" in this document. About half the dataset has these observations. ## Dataset nomenclature The name "ASOS/AWOS" is a compromise among US federal agencies, where the dataset itself is maintained by a combination of NOAA, FAA and US DOD entities. ASOS refers to the Automated Surface Observing System, which is a US-Government managed type of airport sensing platform maintained generally by the National Weather Service, and held in the highest standard. AWOS stands for Automated Weather Observing System, and is the general term for any aviation-grade (which is an extremely high standard) airport observing system. Most DOD sites, and many smaller airports have AWOS's, which may be maintained by government or private maintainers. There are multiple grades of AWOS, and this network will share observations from comissioned units which are certified to send out automated METAR. METAR is a foundational meteorological format, which has several possible definitions, but, is used in aviation as the official indicator of the weather conditions at an airport. These reports are sent hourly at a minimum, but can be as frequent as every 15 minutes in some sites. METAR typically reports at the same time each hour, and in the united states a common time to report is 53 minutes past the hour. A SPECI is a type of METAR report which is in the same dataset as METAR, but is distributed as a result of a significant change in the meteorological conditions between regular METAR reports. These can occur at any minute. ## Latency The two data sources for this dataset have substantially different latencies. Formal METARS are available from the Synoptic platform **within 3 minutes** of their sampling in most conditions. This is in line with most global sources for METAR observations, and we are working to improve on this (June 2026). SPECI observations have the same latency characteristic. The HFMETAR component has latency of 5-9 minutes or more. This data is produced upstream of synoptic, and is delivered in 5-minute batches. This latency can also vary from time to time depending on the workload of that upstream source. Our latency monitoring tools ( [Data Availability Dashboard](https://docs.synopticdata.com/services/data-availability-dashboard.md) ) work on a per-dataset basis, meaning their latency reports will be a combination of the HF and normal METARS. This is not a valid representation of the latency of METARS alone. Weather events do not generally impact availability of ASOS/AWOS data, however local disruptions can prevent specific stations from being accessible. ## A note about HFMETAR observations Some stations in the ASOS/AWOS dataset are augmented with HFMETAR data. HFMETAR have all the same drawbacks as the [High Frequency ASOS](https://docs.synopticdata.com/services/high-frequency-asos.md) dataset, and more. They have higher latency (even than the HFASOS feed itself), lower precision, and fewer variables. Synoptic has been producing a METAR string from these lower-quality observations, that has led to significant confusion regarding these observations. To be clear, these are not valid METAR observations, they are not based on the sampling conventions for METAR, and they have not received the quality control performed on METAR. [Weather API](https://docs.synopticdata.com/services/weather-api.md) supports an argument specially for this dataset of `&hfmetar=0` to prevent HFMETAR values from being returned from the API. Presently (June 2026) the push streaming service does not support this argument and there is no way to exclude the HFMETAR observations. --- language: "en" --- # Cloud Height and Sky Condition For many airports and other weather stations, a [ceilometer](https://en.wikipedia.org/wiki/Ceilometer) is used to measure the height of the [cloud base](https://en.wikipedia.org/wiki/Cloud_base) above the weather station. The ceilometer works by shooting a laser pulse directly upwards and then measures the time it takes for the pulse to return. This time is then used to calculate the distance to the clouds overhead. When there are multiple layers of clouds in the atmosphere, the ceilometer will detect multiple returned pulses due to the varied return times and it will differentiate these as different cloud layers. Because the ceilometer is limited to only detecting the clouds directly above it, they generally use time-averaged values to report the cloud coverage (or "sky condition"). For stations that report cloud height and sky condition observations, the Weather API will return this data in the variables `cloud_layer_1_code`, `cloud_layer_2_code`, and `cloud_layer_3_code`. On our legacy MesoWest website these variables were named, respectively, *CHC1* , *CHC2* , *CHC3*. The decoded cloud layer heights (above ground level) and sky condition are available in the derived variables `cloud_layer_1`, `cloud_layer_2` and `cloud_layer_3`. These variables use a dictionary structure to report cloud height and sky condition, such as: JSON cloud_layer_1_value_1d: { date_time: "2020-07-01T18:35:00Z", value: { sky_condition: "broken", height_agl: 457.21 } } Note that `height_agl` is returned in meters by default. If a user defines `units=height|ft` or `units=english`, then `height_agl` will be returned in feet. The cloud layer with greatest sky coverage is also included in the derived `weather_summary` variable. The [weather condition](https://docs.synopticdata.com/services/weather-condition-codes.md) will be returned for `weather_summary` if present, and if a weather condition is not present cloud layers will be returned. The cloud layer codes are decoded to provide cloud height and sky condition using the following logic. The last number returned always gives the sky condition code, which are the following: 0 = missing 1 = clear 2 = scattered 3 = broken 4 = overcast 5 = obscured 6 = thin scattered 7 = thin broken 8 = thin overcast 9 = thin obscured All digits except the last refer to the cloud height, which is the height given in units of hundreds of feet. That unique unit comes from aviation and other similar fields which historically established the standard practice to express [flight level](https://en.wikipedia.org/wiki/Flight_level) in units of hecto-feet or hundreds of feet. Below are some examples to illustrate what these variables mean: * `cloud_layer_1_code` = 222 Cloud layer #1 is at a height of 22 hundreds of feet = 2200 ft. The last digit 2 indicates the sky condition *scattered*. * `cloud_layer_2_code` = 807 Cloud layer #2 is at a height of 80 hundreds of feet = 8000 ft. The last digit 7 indicates the sky condition *thin broken*. * `cloud_layer_3_code` = 2504 Cloud layer #3 is at a height of 250 hundreds of feet = 25000 ft. The last digit 4 indicates the sky condition *overcast*. --- language: "en" --- # Code Examples We have put together a number of examples of using different languages to both get data from the API, and to read the resulting JSON. [Curl](https://docs.synopticdata.com/services/code-examples.md#cURL) \| [Python](https://docs.synopticdata.com/services/code-examples.md#Python) \| [JavaScript](https://docs.synopticdata.com/services/code-examples.md#JavaScript) \| [PHP](https://docs.synopticdata.com/services/code-examples.md#PHP) \| [Ruby](https://docs.synopticdata.com/services/code-examples.md#Ruby) ## cURL cURL is a command available in the terminal of many Unix (Linux, MacOS) computers which can download something from the internet to your local server. All you have to do is be sure to enclose the API URL in quotes! curl "https://api.synopticdata.com/v2/stations/metadata?&token={YourToken}&stids=WBB,MTMET" This will leave a file on your computer (depending on the output settings for cURL you use). You'll have to read the resulting JSON file using one of the reading methods shown below ## Python Our data services are almost all written in Python, so we would definitely recommend you to use python to get the data as well! This uses Python 3. ### Getting data Using the built-in `urllib` library, we can get API data, but you have to give the arguments to the API URL directly. Below this example we show one using the popular (it may already be available to you) requests library, which can take your API requirements in a dictionary. 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() ### Using the [Requests](http://docs.python-requests.org/en/master/) package: 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() ### Reading API data with Python Though you can request CSV data format for a limited number of requests, Python is very good at understanding JSON, and turning it into data you can work with. To do this, you should use the `json` package, which comes standard. Python import json use_data = json.loads(api_text_data) # Now you can work with use_data because it is a dictionary of the data the API returned. use_data['STATION'][0] The `.json()` function you can use from the Requests package reads and decodes the JSON returned on its own, so you can skip this step. ## JavaScript There are a number of ways to make data requests with JavaScript. For simplicity we are going to use jQuery, which is a high-level framework that hides essentially all the work of making a request and decoding the JSON data. In JS, making a request means using a callback function. When you send the request to be made, your code will not stop and wait for the request to complete. Instead, you will tell the request a function to call when that request is done. This function is called a 'callback'. JavaScript var tkn = "[my public token]"; $.getJSON('https://api.synopticdata.com/v2/stations/latest', { // specify the request parameters here stid:stn, within:1440, token:tkn }, function (data) { /* * do something with your returned data */ } ); Server-side JavaScript, usually in the form of NodeJS, is a popular and powerful programming language. Though jQuery will work in Node, you can also use the `fetch` method. Because that is a more technical concept, and because it works differently from the example above, we will not show an example here. Fetch also has built-in methods to read and understand JSON data. If, for some reason, your request cannot decode the JSON itself, here is the line you would use to get structures from JSON data in JavaScript JavaScript var data_dict = JSON.parse(json_string); *** ** * ** *** The following examples are just some of the languages we have built applications with that required using the API. Please [contact us](https://myaccount.synopticdata.com/contact/) if you have any other language examples we could feature here! ## PHP With PHP, the `file_get_contents` function grabs the contents of the API query in a straightforward manner, and then `json_decode` converts the response into a PHP object or associative array. PHP ## Ruby In Ruby, the `net/http` and `uri` libraries are needed to call the API and get back the response. Note that this response is treated as a string in Ruby, so to convert the JSON into a more useful hash, you will need one of the JSON conversion utilities, the most common gem being shown in the comments here. 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 --- language: "en" --- # Configuring S3 bucket in another account to notify SQS or SNS For customers who have access to a data bucket and want an event-driven model to catch new files in a data delivery bucket. An important consideration is there is no UI in the AWS console to manage this. You will need to use the CLI, code, CloudFormation, etc, to implement this action. In this case, we want to publish `s3:ObjectCreated:*` events in a Synoptic data bucket to a SQS in your account. This guide largely covers this requirement ## Prerequisites In establishing access, you give Synoptic the AWS account ID of your account, and we grant both access to read/list objects, as well as permissions to put and get notifications. ### Steps required 1. Create the queue - you can do this in the console. There is no need to grant access to our provider account, as publishes come from the S3 service, not our account. This is addressed in the next step 2. Update the queue policy to permit s3 from the source bucket to publish to your queue (in addition to any other access policies on your queue or topic). Following least privilege principles you may want to limit actions to post messages only. { "Sid": "s3_publisher_statement", "Effect": "Allow", "Principal": { "Service": "s3.amazonaws.com" }, "Action": "SQS:*", "Resource": "YOUR_QUEUE_ARN", "Condition": { "ArnLike": { "aws:SourceArn": "SYNOPTIC_BUCKET_ARN" } } } 3. Use the CLI to put a bucket notification/queue event on the Synoptic-owned bucket With `sqs-config.json` being the SQS configuration specification JSON {"QueueConfigurations":[ {"QueueArn":"YOUR_QUEUE_ARN", "Events":["s3:ObjectCreated:*"]} ]} 4. from the CLI use this command to place the bucket notification rule on our bucket aws s3api put-bucket-notification-configuration \ --bucket [SYNOPTIC_BUCKET_NAME] \ --notification-configuration file://sqs-config.json With these steps completed, your SNS or SQS should begin to receive notifications immediately when new files are published to the bucket, and you can invoke lambdas or other events to consume and act on the data. If your access is disabled in the future, notifications may persist for after access is withdrawn, but you will lack the ability to capture the objects indicated in the messages. --- language: "en" --- # Custom data deliveries Synoptic performs a wide variety of bespoke data services for our customers. Additionally, Synoptic aggregates datasets for specific customers or programs which do not align with the mesonet data model which forms the core of our general access products. In these cases, there are an unlimited number of data exchange methods we can establish depending on the requirements of the data and the customer. Generally, documentation for custom data deliveries will be provided in the process of establishing a connection. For our more general documentation, we have some guides for technical implementation details which are more generally utilizable across our custom exchanges. * [Configuring S3 bucket in another account to notify SQS or SNS](https://docs.synopticdata.com/services/configuring-s3-bucket-in-another-account-to-notify.md) --- language: "en" --- # Data Availability Dashboard The [Data Availability Dashboard](https://availability.synopticdata.com/) provides users with the information they need to determine if data is flowing through Synoptic's system at the network- and station-levels, and how the current data flow fits in the context of the recent past. It is not meant to be a subjective assessment of network or station quality. In order to achieve this, we provide objective summary counts of the number of stations reporting on a network-by-network basis, and the number of observation reports transmitted by single stations to Synoptic. We also provide indications of the time delays introduced along the path from data measurement to transmission to Synoptic's system where it is made available to you, the user. As described in our 'Note about the data', the measurement and transmission frequencies are highly variable among networks and stations, depending on a number of external factors. Below is a detailed explanation of the data availability dashboard components, and a brief note regarding the nature of the data we aggregate. If you have any questions or would like to provide feedback please reach out to us at [support@synopticdata.com](mailto:support@synopticdata.com). ## Dashboard terminology ### Network-level metrics ![image-20230505-200616.png](https://docs.synopticdata.com/__attachments/a_cada96d89727eaac46e0afbd38009ea7600c73e2e919e9a0695a87124dda4a3b/image-20230505-200616.png?cb=d0e460826c8fcff68bf0e8c4ebf2e82f) **1. Number of stations reporting** Number of stations reporting is the number of unique stations reporting for a network in a one hour period. These hourly unique station counts are provided for the most recent hour, as an average over the past 24 hours, and over the past 7 days. **2. Data last received** The time (to the nearest 5 minute increment) of the most recent transmission of data from the given network to Synoptic. This is the approximate time when the network data was most recently made available in the Synoptic system and is not synonymous with the timestamp of the most recent measurement. The time elapsed since the last data transmission is also displayed in parentheses in minutes. **3. Typical data delay** The data delay is the time between when an observation is logged and when it is transmitted to Synoptic and available for use in our system. It is the sum of both the time since the last data transmission and the time between when a measurement was made and when it was transmitted to Synoptic. At the network-level, this delay is computed hourly as the average delay across all reports by all stations in the network. We define the 'typical' data delay as the interquartile range of these hourly values over the last day (24 hours). ### Station-level metrics ![image-20230505-200642.png](https://docs.synopticdata.com/__attachments/a_9f066781f26293e85c5ab17d6c92c2729aeab096e40b1b9d686ee71fd1bd5312/image-20230505-200642.png?cb=bf69b2e459bb92f2fe1c522c37216254) **1. Number of reports** This is the number of reports transmitted by the station to Synoptic's system in a one hour period. As with the network metrics, 24 hour and 7 day summaries are the average number of hourly reports over the respective time periods. Note: Synoptic periodically receives historical station data to fill data gaps. In these instances, the station report counts may exhibit short duration increases. **2. Data last received** Similar to the network metric, this is the time of the most recent station data transmission (to the nearest 5 minute increment). It is not synonymous with the timestamp of the most recent station observation. The time passed since the last data transmission is also presented in units of minutes. **3. Typical data delay** The typical delay between an observation timestamp and when it is available in Synoptic's system. The definition of the 'typical' delay follows the network definition. ## A note about the data Synoptic Data aggregates surface mesonet data from more than 300 networks, comprising nearly 100,000 stations in near real-time. The hundreds of providers that make these data available for public benefit must choose measurement frequencies and data transmission intervals that align with their own individual needs/purposes. These can vary greatly depending on factors ranging from operational objectives to station by station power availability. For instance, a provider may measure conditions on hourly intervals, but power constraints may require that the transmission of these data to Synoptic occur once per day. Such situations would be reflected in the data delay for the stations comprising this network. Even stations within a given network may measure or transmit at varying intervals, which can result in significant daily variation in the network station counts. Synoptic's efforts to aggregate mesonet data from any and all providers means that the flow of data through our system is highly network-dependent and expected to vary over a range of timescales from daily to seasonal. Interpretation of the summaries and timeseries presented in the data availability dashboard must bear this variability in mind. ## FAQs ### Why do the lines in timeseries' plots not align with the \`Last Report\` marker? The step plots reflect variable values that are rolled up hourly at the top of the hour (:00). When viewed as a wall clock time that is approaching the top of the hour, this can result in a gap between the timeseries step plot and the Last Report marker. ![CkvkJMHGKmHUVbOeQYeLT7Vvn3dOMHOnXEkzRS_73RSyCepYjElh0O5pPfmWgJrNqVaKFoGj3JD9U9-W1yf9gfKz5iPZ1rkZXWg_qTJuyGq62g8-Dw0UuPg1qqRguY7t2AmhH9ADU7VE2A2zjQ](https://docs.synopticdata.com/__attachments/a_03896422d464fe2e47101da2850bab695a5645837bd81662470df6e767bdfc7a/CkvkJMHGKmHUVbOeQYeLT7Vvn3dOMHOnXEkzRS_73RSyCepYjElh0O5pPfmWgJrNqVaKFoGj3JD9U9-W1yf9gfKz5iPZ1rkZXWg_qTJuyGq62g8-Dw0UuPg1qqRguY7t2AmhH9ADU7VE2A2zjQ?cb=3d2c8a6989578ac1e66de630a7125cce) Alternatively, many stations report once per hour. In these situations it is common for the Last Report marker to plot somewhere on the step plot's most recent hourly interval. This indicates that the station has not reported since the most recent rollup at the top of the hour. ![jZFk0PP6fjGJSRiNfNfDgA5MV5neR6L-f3hc9bd5On5v9lgFbrAu7RxsSzd3ZtNKwj4ion4PPFQ83i3CDtaE5QZH-HUttOATiyxAIHMgTaZlfduGZFlSG_9nOadO8xQEHFv_YGchwTGnmhcLsw](https://docs.synopticdata.com/__attachments/a_5e1955f74b49ba2cbcafe80a5029428e9afa97da0dc64cab7dceab52a98f23ce/jZFk0PP6fjGJSRiNfNfDgA5MV5neR6L-f3hc9bd5On5v9lgFbrAu7RxsSzd3ZtNKwj4ion4PPFQ83i3CDtaE5QZH-HUttOATiyxAIHMgTaZlfduGZFlSG_9nOadO8xQEHFv_YGchwTGnmhcLsw?cb=3a02cd54316ba4e3cd99dad4e76cf402) --- language: "en" --- # Data Download Tool The [Data Download tool](https://download.synopticdata.com/) provides access to environmental data from thousands of locations across Synoptic's dataset. It is designed to fetch data from one station at a time in CSV format. If you need to download data from more than a couple dozen stations or want to access current or past conditions over a region, we recommend our API data services. The provisional data available from the data download tool are intended for diverse user applications. For data required for a court of law or regulatory purposes, review the information available from the NCEI or consult a CCM The download service may be used to request multiple data sets sequentially and have them process at the same time. A single request may cover a time span from a single hour up to 22 years. Due to events like stations becoming inactive and inactive, there may be gaps in the period you request which are not indicated before you request data. The download tool does not remove any data. You decide the variables you prefer to download including parameters commonly derived from the information available at that station. While the request's start and end dates are in UTC (Universal Time Coordinated), you can choose either the station's local time zone or UTC for the timestamps output in your download. ## Getting your data Once the CSV download is ready, two options are available to retrieve it: * Click a link and download in your browser * Use a URL and web tools such as wget or curl to import the data into another program or application * Requests are usually filled quickly but your download files are available for up to three days after they are created Now click [New Download](https://download.synopticdata.com/) and get started! If you need any help, feel free to [contact us](https://synopticdata.com/contact-us). ### Quality control Only the default QC flags are applied on these data, and those will remove observations Synoptic confidently assesses are unphysical and outside the reasonable range of the variable being represented. The tool does not give access to any additional QC information at this time. ### Data disclaimer As described in the [data disclaimer](https://synopticdata.com/data-disclaimer), data available from Synoptic are considered provisional. Data deemed to fail Synoptic data checks are not available to download via the Download service. ### Reported vs Derived Variables When selecting variables, they will be described as either reported or derived. Reported variables are the values we receive directly from a station, whereas derived variables are calculated by Synoptic based on other reported variables. For example, dew point temperature can be derived from a station's air temperature and relative humidity observations. In some cases, a station may have both a reported and derived value for the same variable. ### Download Limit The download service limits the number of in-progress and complete downloads based on your customer settings. Within the download service, the πŸ”Œ tab will display your limit, the amount used, and remaining number of requests available. 24 hours after a request you will have another download available, a download link will remain live for 3 days. You can contact [sales@synopticdata.com](mailto:sales@synopticdata.com) to discuss options to raise your limit. The download service uses a shared resource to process requests for all users, so delays may be anticipated when the server is busy. --- language: "en" --- # Data Viewer Pages ## Viewer Access The Data Viewer is freely available to all users wishing to view publicly available data without an account. By opening a free Synoptic account, users gain access to unlimited saved favorites and the transfer transfer of settings across devices in the Data Viewer. A free account also opens access to Synoptic's Data Download Service. You can sign up for an account by selecting the avatar in the upper right corner of the application, and clicking 'Sign up'. ## Explore ![image-20250425-153247.png](https://docs.synopticdata.com/__attachments/a_0c6e923e9642ddef714bf7a7c7655a6f74b4382047f1e3db8600900e2705648e/image-20250425-153247.png?cb=1783fc621a2fb88cef09dd4a5061d66c) The Explore page is your source to view map-based snapshots of conditions across your interest area, displaying data values on the map at the reporting station's location. We apply a station thinning algorithm to maintain a clear view of station conditions. If the station density seems sparse, zooming in will update the view with additional stations. Clicking on a station displays a popup with a Conditions tab that presents a table of the most recent observations and timeseries chart of recent conditions (the duration is adjustable in the [Global Settings](https://docs.synopticdata.com/services/data-viewer-pages.md)). Select the About tab to view basic station and sensor metadata. ### Data filtering and selection The default display is real-time temperature across all public networks. Using the Explorer menu pane you can quickly adjust the display by changing variables, time, and filter to specific networks of interest with just a few clicks. #### Variable Selecting the active variable from the menu pane allows you to choose from a selection of variables in Synoptic's system. We've prioritized common variables and are always adding more in response to user feedback. If you don't see the variable you're looking for, please [contact us](mailto:support@synopticdata.com) and let us know! #### Time Mode In addition to real-time observations, you can also display a historical snapshot of data. Toggle from "Now" to "Historic" mode and select any date and time (UTC or user-local) spanning our entire period of record (1996). All the data is equally accessible. #### Network Selection In addition to mapping observations by variable and timestamp, you can also filter by network. By default, all networks are shown, however you have the ability to chose the type of networks you'd like to see, or specify one or more networks yourself. "Use by group" filters by preselected groups that work well together or are similar in observing purpose. "Custom" allows you to select by one or more networks, you can look up networks by their long or short names given [here](https://docs.synopticdata.com/services/station-networks-providers.md). ### Weather Summary Stations of interest can be added to a 'Weather Summary' table to facilitate panning of conditions on the map while retaining a summary view of specific stations of interest. Stations can be added in two ways: 1. add all stations in the map view by selecting the 'Weather Summary' button at the bottom of the application, and select 'Add current stations on the map'. 2. add individual stations by selecting a station marker on the map and check the box to add the station to the weather summary The weather summary table permits comparison of the latest observations from all selected stations alongside the minimum and maximum values since the previous day. Links to display tabular data or plot a meteogram for each station are also available. ## Metadata ![image-20250425-153339.png](https://docs.synopticdata.com/__attachments/a_6f0e299b88f852b0ffef6b94cea6f5154e050e157d2ed89f9c807adf7d1650e1/image-20250425-153339.png?cb=17b43f6f5c4ccf7cd0c0beffd68aebc6) The Metadata page provides tools to quickly explore the entire catalogue of data aggregated by Synoptic. Contrary to the Explore page, which applies spatial filters in order to preserve a clean viewing experience for tracking conditions, the Metadata pkage displays *all* stations in Synoptic's system. Filter assets by status (actively reporting or inactive), variables of interest, period of record, and more. Station markers on the map can be clicked to view additional station metadata. The Metadata page's station search functionality is also an excellent tool for quickly finding a specific station of interest, and supports search by ID or station name keywords. This is the most efficient way to find a single station, and users can navigate to current data by clicking the tabular data link( ![table_chart_24dp_666666_FILL1_wght400_GRAD0_opsz24.png](https://docs.synopticdata.com/__attachments/a_15b6bca0814e6e5d45474fab85ed7c9f8238260d5338c9883ff0374333e0e85d/table_chart_24dp_666666_FILL1_wght400_GRAD0_opsz24.png?cb=b2d56f2b097e93fffd43243c3d085346) ) in the station's metadata panel. ## Table ![image-20250425-153409.png](https://docs.synopticdata.com/__attachments/a_db53a30121842392806aaee5eef8d113d9a245ab19a8d29768124c3afa139f89/image-20250425-153409.png?cb=f03fb093298a51376bef5869f4458410) The Table page is your source for tabular data at a single station of interest. Access the Table page for a station by selecting the station of interest from the Explore page and then clicking the table page icon ( ![table_chart_24dp_666666_FILL1_wght400_GRAD0_opsz24.png](https://docs.synopticdata.com/__attachments/a_15b6bca0814e6e5d45474fab85ed7c9f8238260d5338c9883ff0374333e0e85d/table_chart_24dp_666666_FILL1_wght400_GRAD0_opsz24.png?cb=b2d56f2b097e93fffd43243c3d085346) ) from either the navigation pane or the station data panel. You can also select a station from the Table page menu drawer. The Data Viewer's default display is limited to a common set of 'Basic Weather' variables to streamline presentation. To view all variables for a station, toggle the 'Basic Weather' variable group to 'All' under the Table menu header to the left of the display. You can also change the variable group in the [Global Settings](https://docs.synopticdata.com/services/synoptic-data-viewer.md#%255BinlineExtension%255D--Global-Settings). Basic metadata for the station is displayed in the Table page. For comprehensive metadata, select the Metadata link ( ![toc_24dp_666666_FILL1_wght400_GRAD0_opsz24.png](https://docs.synopticdata.com/__attachments/a_2ecc3c01aea291c2bc857ca19a5f7cbd9396723e705f770ea7e33793e339e19f/toc_24dp_666666_FILL1_wght400_GRAD0_opsz24.png?cb=83479d0320fdd625c5aad79eb6d653f7) ). You can always click the tabular data icon ( ![table_chart_24dp_666666_FILL1_wght400_GRAD0_opsz24.png](https://docs.synopticdata.com/__attachments/a_15b6bca0814e6e5d45474fab85ed7c9f8238260d5338c9883ff0374333e0e85d/table_chart_24dp_666666_FILL1_wght400_GRAD0_opsz24.png?cb=b2d56f2b097e93fffd43243c3d085346) ) to return to the default data view. The Summary Weather Data table provides a summary of the most recent station report along with minimum and maximum values for the current and previous day (minimum and maximum values are only displayed in the 'Now' time mode). If the time mode is 'Historic', the table will populate with the station report at the closest date time to that specified. If the station reports precipitation, precipitation accumulations over the 1, 3, 6, 24, and 48 hours leading up to the specified date/time stamp are also displayed. Hovering over "How can I access this data?" will provide the exact [Weather API](https://docs.synopticdata.com/services/weather-api.md) query used to power a table and a link to the [Data Download tool](https://docs.synopticdata.com/services/data-download-tool.md) to save the data. The Station Data table displays the station time series data over the duration specified by [Global Settings](https://docs.synopticdata.com/services/synoptic-data-viewer.md#%255BinlineExtension%255D--Global-Settings) 'Duration'. Within the table, observations flagged by Synoptic's QC processes are displayed in yellow. Hovering over the yellow flag displays the name of the QC check ([more information about QC](https://docs.synopticdata.com/services/mesonet-data-qc.md)). ## Graph ![image-20250425-153525.png](https://docs.synopticdata.com/__attachments/a_8fb27d47fcf656f2cdb7bddbd2553a9b4c602da459f4ea78fd87f998eef683f8/image-20250425-153525.png?cb=3c7612296a689a1252c34993b4e847d2) The Graph tab allows the user to specify a date and time ('Now' or 'Historic') and create a timeseries graph for up to 7 days, ending on the specified date time. To begin, click "Add New Plot". From there, the user can choose to graph **one or more variables for a single station** or **a single variable for up to 4 stations** by selecting the tab corresponding to the desire plot type. Variable(s) can be selected from the pre-defined variables or searching for variable ([list of available variables and their Synoptic callable names](https://docs.synopticdata.com/services/station-variables.md)). Stations can be selected from the map by clicking on a station and can be filtered by network. Graphs are interactive and can be edited and downloaded to be shared or used in other applications. As with other Data Viewer pages, graphs are encapsulated by the url, which can be shared with other users. Four graphs can be displayed at one time, whether or not they are single/multi station graphs. ## Dashboards ![image-20250425-154355.png](https://docs.synopticdata.com/__attachments/a_dcb8217f45a28d025325874900c508a4b793933b8e77682c711e151769a838cd/image-20250425-154355.png?cb=4e7ca0560a59ca8c95ec7f7da038475a) The Dashboard page is part of the paid Dashboards and Notifications service in the Data Viewer. Users can create dashboards for selected stations and variables and view all conditions in a centralized page. Get a quick summary of station conditions with variable tiles and toggle between map and table displays of current conditions for all selected stations. A station status page can be accessed by clicking the monitor icon ( ![monitor_heart_24dp_666666_FILL1_wght400_GRAD0_opsz24.png](https://docs.synopticdata.com/__attachments/a_0957e87f01739972ffdca85a79729fb29c1c8d451607ef7cc7d422ee70461bbc/monitor_heart_24dp_666666_FILL1_wght400_GRAD0_opsz24.png?cb=a5721f93c6f102b8aa25890bf186642e) ), and displays station reporting information, battery voltage, and quality control summary for monitoring station performance. Dashboards also provide the starting point for generating Notifications based on station reporting frequency and environmental conditions. [Contact us](https://synopticdata.com/contact-sales/) to learn more about Dashboards and Notifications! ## Notifications ![image-20250425-154543.png](https://docs.synopticdata.com/__attachments/a_4fb1dc42364114a9cc21ed779a3df78b3bdcbdf4bcf528e98a78fbd4ebfcdc10/image-20250425-154543.png?cb=faa6903171d9ae7c0ec0f2f137438e35) Data Viewer Notifications are integrated with Dashboards as part of the Data Viewer's paid service. The Notifications page provides a summary of all active and inactive Notifications created by the user. Active stations display the number of stations presently in alert. Existing notification details can be reviewed by selecting one from the summary table. Notifications can also be modified by selecting the edit icon ( ![edit_24dp_666666_FILL1_wght400_GRAD0_opsz24.png](https://docs.synopticdata.com/__attachments/a_878f2da04740543c6f8cf2882619bdee02b902cadb728f70c03f619c5dc00ab1/edit_24dp_666666_FILL1_wght400_GRAD0_opsz24.png?cb=93f5cd841d88e178f8331db1b44c8953) ). ### Creation Notifications are created from the Dashboards page. The stations and variables in the selected Dashboard form the basis for creating a notification. While on the desired dashboard, click the add-alert icon ( ![add_alert_24dp_666666_FILL1_wght400_GRAD0_opsz24.png](https://docs.synopticdata.com/__attachments/a_f5cbfa166bd528b0171e35130fbc3d7693d836278a5140ddb06603b11f6288c7/add_alert_24dp_666666_FILL1_wght400_GRAD0_opsz24.png?cb=8fd46d65471ce640dcb566228660dd90) ) to create a new notification. The new notification form allows you to name and describe the alert, select a criticality level, define the alerting ruleset and terms for alert resolution, select stations from the dashboard to be alerted on, and distribution forms (email, SMS text, or only display in the dashboard). ### Notification Rules Notifications rules can be based on one or more environmental thresholds, or elapsed time since the station reported. Alerts on environmental thresholds can be triggered on a single observation, or consistent exceedance of the specified threshold for defined time period in order to minimize the risk of repeated alerts when conditions fluctuate about the defined threshold. Similarly, users have the flexibility to define the terms of alert resolution (a single observation or based on multiple observations over a specified time interval). ### Notification Distribution Users can choose to distribute alerts via email or SMS text. Distribution is optional; if no distribution is selected then stations in alert will only be communicated within the dashboard itself. If email or SMS text distribution is specified, users can select whether or not to receive notifications on alert resolution, and choose to receive periodic reminders of stations in alert for long-running alerts. ### Confirming Notifications After creation of a notification, users can choose to confirm (ie. save) the notification but leave it inactive, or confirm and activate. The options are designed to allow users to create a new notification even if they are already at their active notification limit as defined in their contract. Notification status can be changed from the Notification page summary table. --- language: "en" --- # Dataset-specific documentation This section of our documentation is dedicated to expanding on the unique characteristics, consdierations and requirements for using data from some of our [Station Networks \& Providers](https://docs.synopticdata.com/services/station-networks-providers.md). Often, when a dataset presents unique challenges we will make it [an opt-in dataset](https://docs.synopticdata.com/services/opt-in-public-datasets.md) (if it is public) to assist data users in understanding the nuances of using a certain dataset. Not all datasets or providers have additional information documented here. * [High Frequency ASOS](https://docs.synopticdata.com/services/high-frequency-asos.md) * [ASOS/AWOS (United States METAR)](https://docs.synopticdata.com/services/asos-awos-united-states-metar.md) --- language: "en" --- # Errors Occasionally an error will be returned from the API, either because no data fit the request, invalid authentication, or (rarely) a problem internal to the API itself. Most errors are handled by the API, and you will receive a summary JSON output in lieu of data. Additionally, access restrictions within the Synoptic dataset are enforced by the API with errors for each request of data a token can't access. Errors will provide at least the following two elements: ## Response Messages The response messages typically help a user understand and correct the API error. These self-describing and brief explanations will describe the general reason for the error. ### Response Code The response codes correlate to a broader error type. Errors are grouped together based on the similar problematic requests types. Response codes are categories are listed as follows: | Response Code | Message | |---------------|-------------------------------| | `-1` | Incorrect API parameter input | | `1` | No errors | | `2` | Zero results | | `403` | Authorization error | | `404` | URL not found | | `500` | Internal errors | ### -1 - Incorrect API parameter input These errors occur when an invalid input is passed through an API parameter. JSON { SUMMARY: { NUMBER_OF_OBJECTS: 0, RESPONSE_CODE: -1, VERSION: "v2.21.3", RESPONSE_MESSAGE: "START cannot be after END.", RESPONSE_TIME: 0 } } Possible response code -1 messages: | **Message** | **Description** | |--------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------| | `"START cannot be after END."` | `START` time requested is after `END` time requested, make sure your `START` time is before your `END` time. | | `"Both START and END are required for a valid query."` | `START` and `END` times are required for Time Series. Advanced Precipitation, and Latency requests. | | `"No latency data found for this request."` | This will only be returned as a response code -1 message for the Latency service. No latency data for the specified query. | | `"No networks data found for this request."` | This will only be returned as a response code -1 message for the Networks service. No network data for the specified query. | | `"No data found for this request."` | This will only be returned as a response code -1 message for the Networks Types and QC Types services. No data for the specified query. | | `'WITHIN parameter required to use ATTIME.'` | In the Nearest Service, `WITHIN` (minutes) must be used with the `ATTIME` parameter. | | `"LIMIT cannot be used without the RADIUS parameter."` | The `LIMIT` parameter only controls the number of return stations with the `RADIUS` parameter. | | `"GROUPBY cannot be used with a QC query."` | The `GROUPBY` parameter cannot be used alongside ANY `QC` parameter. | | `'UTF-8 Error'` | Make sure your query has properly encoded UTF-8 characters. | | `'Unknown JSON encoding error.'` | The API was unable to properly output the requested data, please reach out to [support@synopticdata.com](mailto:support@synopticdata.com) with your query URL. | ### 2 - No Results Errors with a response code of 2 indicate no data was returned for a query due to various reasons. JSON { SUMMARY: { RESPONSE_CODE: 2, RESPONSE_MESSAGE: "Invalid token. Be sure to use a token generated from your API Key, and not the key itself.", VERSION: null, HTTP_STATUS_CODE: 401 } } These errors can also be returned outside of JSON format, such as: {"SUMMARY": {"RESPONSE_CODE": 2, "RESPONSE_MESSAGE": "Too many requests sent. Please wait for other requests to finish and resend.", "VERSION": null, "HTTP_STATUS_CODE": 429}} Possible response code 2 messages: | **HTTP Status Code** | **Message** | **Description** | |----------------------|----------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | | `"No stations found for this request, or your account does not have access to the requested station(s). Please contact support@synopticdata.com."` | No stations fitting your selection criteria. In the event that no data was found for the queried stations, this error will occur. This includes cases when two selection criteria cancel each other out. If you anticipate sometimes the request may return stations with no data, you can add `&showemptystations=1` to have `STATION `objects with empty `OBSERVATIONS` returned. More details on [API Performance and Limits](https://docs.synopticdata.com/services/api-performance-and-limits.md) . | | | `"Authorization error - mesonet API access not enabled for this contract"` | The token and its associated account does not have access enabled for the Weather Data API. | | `401` | `"Invalid token. Be sure to use a token generated from your API Key, and not the key itself."` | The token passed is not recognized, the API key can't be passed here instead of the token. Commonly occurs with mistyped tokens. | | `403` | `"Unauthorized. Review your account access settings in the customer console.`" | Under "Customer \& contract" in the [Customer console](https://customer.synopticdata.com/customer/), "Access" will indicate the data services (including the API) that an account has access to. | | `400` | `"Request terminated"` | If you receive this error reach out to [support@synopticdata.com](mailto:support@synopticdata.com) with your query URL and indicate the account associated with the token. | | `429` | `"Too many requests in the queue. Please wait for other requests to finish."` | You have reached your concurrency and request waitlist limit, you will have to wait to send more queries. Refer to [API Performance and Limits](https://docs.synopticdata.com/services/api-performance-and-limits.md) for more details. | | `503` | `"Unknown error in API."` | If you receive this error reach out to [support@synopticdata.com](mailto:support@synopticdata.com) with your query URL and indicate the account associated with the token. | | `408` | `"Request could not complete. Timeout."` | The API request timed out after the limit of 360 seconds. Try the request again, if the error persists, please reach out to [support@synopticdata.com](mailto:support@synopticdata.com). | ### 403 - Authorization error 403 errors are directly tied to the levels of access an account and its access credentials have. If you receive one of these errors, refer to the features outlined with your usage tier on our [pricing page](https://synopticdata.com/pricing) or your signed commercial agreement. JSON { SUMMARY: { NUMBER_OF_OBJECTS: 0, RESPONSE_CODE: 403, VERSION: "v2.21.1", RESPONSE_MESSAGE: "Account associated with this token does not have access to the precipitation service. Please see our Enterprise Service options at https://synopticdata.com/enterprise, or contact us at account@synopticdata.com", RESPONSE_TIME: 0 } } Possible response code 403 messages: | **Message** | **Description** | |----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `"Authorization error - mesonet API access not enabled for this contract"` | The token and its associated account does not have access enabled for the [Weather API](https://docs.synopticdata.com/services/weather-api.md). | | `"Authorization error - no precip_access contract info"` | The token and its associated account does not have access to the [Advanced Precipitation service](https://docs.synopticdata.com/services/precipitation.md). Please review the features associated with your contract on our [pricing page](https://synopticdata.com/pricing). | | `"Auth``orization error - missing precip_access contract info"` | The token and its associated account does not have access to the [Advanced Precipitation service](https://docs.synopticdata.com/services/precipitation.md). Please review the features associated with your contract on our [pricing page](https://synopticdata.com/pricing). | | `"Authorization error - no qc_checks_access contract info"` | The token and its associated account does not have access to [Advanced QC](https://docs.synopticdata.com/services/mesonet-data-qc.md#Advanced-QC). Please review the features associated with your contract on our [pricing page](https://synopticdata.com/pricing). | | `"Account associated with this token does not have access to derived precipitation through the /timeseries endpoint. Please see our Enterprise Service options at https://synopticdata.com/enterprise, or contact us at account@synopticdata.com"` | The token and its associated account does not have access to [Basic Precipitation through Time Series](https://docs.synopticdata.com/services/time-series.md#Basic-Precipitation). Please review the features associated with your contract on our [pricing page](https://synopticdata.com/pricing). | | `"Account associated with this token does not have access to history earlier than x year(s). Please see our Enterprise Service options at https://synopticdata.com/enterprise, or contact us at account@synopticdata.com"` | The token and its associated account does not have access to historical data x year(s) before the current time. Please review the features associated with your contract on our [pricing page](https://synopticdata.com/pricing). | | `'The requested {} is not authorized for this account and token. Please modify your request.'` | The token and its associated account does not have access to one (or more) of the following requested parameters: * STID * Country * State Please review the features associated with your contract on our [pricing page](https://synopticdata.com/pricing). | | `"Authorization error - no contract available"` | If you receive this error reach out to [support@synopticdata.com](mailto:support@synopticdata.com) with your query URL and indicate the account associated with the token. | | `"Authorization error - no mesonet contract info"` | If you receive this error reach out to [support@synopticdata.com](mailto:support@synopticdata.com) with your query URL and indicate the account associated with the token. | | `'Invalid history_access setting in customer contract. Should be int or null.'` | If you receive this error reach out to [support@synopticdata.com](mailto:support@synopticdata.com) with your query URL and indicate the account associated with the token. | ### 404 - URL not found These errors will occur if an incorrect URL is requested. JSON { SUMMARY: { RESPONSE_CODE: 404, VERSION: "v2.21.3", RESPONSE_MESSAGE: "Requested URL not found. See https://developers.synopticdata.com/mesonet/ for valid webservices.", RESPONSE_TIME: "0 ms" } } Possible response code 404 messages: | **Message** | **Description** | |------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `"Requested URL not found. See https://developers.synopticdata.com/mesonet/ for valid webservices."` | The entered subdomain is correct `https://api.synopticdata.com/`, however, the URL refers to an incorrect service. The linked Developers site will have correct API endpoints. | ### 500 - Internal Error Errors internal to the API. If you continually receive one of these errors, please reach out to [support@synopticdata.com](mailto:support@synopticdata.com) with your query URL and indicate the account associated with the token. JSON { SUMMARY: { RESPONSE_CODE: 500, VERSION: "v2.21.1", RESPONSE_MESSAGE: "Internal error occurred.", RESPONSE_TIME: "0 ms" } } Possible response code 500 messages: | **Message** | **Description** | |-----------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `"Internal error ocurred."` | If you receive this error reach out to [support@synopticdata.com](mailto:support@synopticdata.com) with your query URL and indicate the account associated with the token. | --- language: "en" --- # Explore Tool Legacy - check out our [Synoptic Data Viewer](https://docs.synopticdata.com/services/synoptic-data-viewer.md) for a supported and improved viewer Synoptic's [Explore Tool](https://explore.synopticdata.com/) is designed to allow anyone to see public weather data aggregated and distributed by our Weather API. You can build this exact same platform using our API. ## What can I do Start by choosing your mode (Current Weather, Metadata Explorer, or Station). Each mode has a similar set of controls, and the map will stay in the same place between modes. ### Current Weather Choose the variable to view and unit, and look around at the most recent observation of the selected parameter. Only the first report of the given parameter is displayed. #### Available Variables * **Temperature**- Assuming you know what this is * **Precipitation**- The total integrated amount of precipitation reported by this station over the most recent period of time selected. Utilizes the Synoptic Precipitation service. * **Wind**- The wind speed and direction where the color and number indicate speed, and the arrow icon indicates the direction the wind is blowing. * **Solar**- Typically this means the downwelling shortwave solar radiation received at a point in W/m\^2 * **Pressure**- Mean sea level pressure derived from local station temperature and pressure measurements and extrapolated to a consistent elevation for meaningful comparison between stations even at different elevations. * **Data Age** - The number of hours since the last time an air temperature observation was made, up to 7 days. ### Metadata Explorer This is the default mode, and is designed to allow you to discover available stations. Make selections in the control menu, and click "Find \& display". A "Show visible" button is also available to view every active platform in your visible map area. Choose an option other than "Map" to view the result of your selections different ways. ### Station Mode Get to know a single station, from current and recent data, to metadata and history information. ### Developer tools To help you start building applications using our API products, the bottom of the page has an orange "how can I get this data" button - click it to see an explanation of the Weather API query that gave this data. Additionally you can enter a full Weather API query (without a token even) replacing with and see the query made and explained for you. --- language: "en" --- # FAQs ## How do I change units? You can adjust units and other settings that apply across the application in the Global Settings menu. Click the settings icon ( ![settings_24dp_666666_FILL1_wght400_GRAD0_opsz24.png](https://docs.synopticdata.com/__attachments/a_c45e38434e85410843c0d18a0c4749b1cc1bcee4300118195b44d05aa8ea79fb/settings_24dp_666666_FILL1_wght400_GRAD0_opsz24.png?cb=014e05353ff6c56f228aa75d1a322a54) ) in the upper right corner of the screen to get started. Settings are preserved for consistent experience. Signing up for a free Synoptic account allows users to also save settings across devices. ## Can I save a view to revisit later? Yes! Views in the Data Viewer are captured in the url, and can be bookmarked to revisit later or shared with others. With a free Synoptic account users can also save unlimited favorites. Just click the Favorite icon ( ![favorite_24dp_666666_FILL1_wght400_GRAD0_opsz24.png](https://docs.synopticdata.com/__attachments/a_acaec822041b1e2ddf8f6c97d85f120f5b658e419d95914c2a0e4c531c4bb17d/favorite_24dp_666666_FILL1_wght400_GRAD0_opsz24.png?cb=cec95e8aeb6dffcf62c67fafb255c464) ) and name your view. Saved favorites are accessible from the user avatar in the upper right corner of the application. ## Do I need an account to use the Data Viewer? No! The Data Viewer is freely available to all users wishing to view publicly available data without an account. By opening a free Synoptic account, users gain access to unlimited saved favorites and the transfer transfer of settings across devices in the Data Viewer. A free account also opens access to Synoptic's Data Download Service. ## How can I compare a timeseries of conditions between stations? Use Synoptic's 'Graph' page to compare a timeseries of conditions between stations. Select the 'Graph' icon (:f:) from the navigation menu, select 'Add New Plot', and select the 'MULTIPLE STATIONS' tab from the selection menu. From there, select a variable of interest, and up to 4 stations to compare on the same display. ## Why are variables missing from a station's tabular data display? The Data Viewer's default display is limited to a common set of 'Basic Weather' variables to streamline presentation. To view all variables for a station, toggle the 'Basic Weather' variable set to 'All' under the Table menu header to the left of the display. Displayed variables can also be changed in the Global Settings ( ![settings_24dp_666666_FILL1_wght400_GRAD0_opsz24.png](https://docs.synopticdata.com/__attachments/a_c45e38434e85410843c0d18a0c4749b1cc1bcee4300118195b44d05aa8ea79fb/settings_24dp_666666_FILL1_wght400_GRAD0_opsz24.png?cb=014e05353ff6c56f228aa75d1a322a54) ) by editing the 'Variable Group'. ## Why can't I find the variable I'm looking for on the Explore page? We are continually adding display support for variables in our system in response to user feedback. If you don't see a variable you're looking for, please let us know! You can submit feedback by clicking the feedback icon ( ![feedback_24dp_666666_FILL1_wght400_GRAD0_opsz24.png](https://docs.synopticdata.com/__attachments/a_2df3032eb819714e8d0293447c70f25938701e6a117fa127dc9b70cb4286c862/feedback_24dp_666666_FILL1_wght400_GRAD0_opsz24.png?cb=ced3ef7ed491e2e7223a85720be9b1d8) ) or contact Synoptic [++support++](mailto:support@synopticdata.com). ## Do I have to pay for an account? No. A free Synoptic account opens access to additional Data Viewer features: saved favorites and the saving of user settings across devices, and access to Synoptic's Data Download Service. Data Viewer Dashboards and Notifications are available as a paid service within the Data Viewer. ## How can I see a longer timeseries of conditions? Presently the Data Viewer supports timeseries displays up to a duration of 7 days. The default duration can be adjusted in the Global Settings ( ![settings_24dp_666666_FILL1_wght400_GRAD0_opsz24.png](https://docs.synopticdata.com/__attachments/a_c45e38434e85410843c0d18a0c4749b1cc1bcee4300118195b44d05aa8ea79fb/settings_24dp_666666_FILL1_wght400_GRAD0_opsz24.png?cb=014e05353ff6c56f228aa75d1a322a54) ) by editing the 'Duration' field. This will influence timeseries displays across the application and tabular displays of timeseries data. ## Can I download the data I see in the Data Viewer? Yes! The public data available in the Data Viewer can be downloaded from Synoptic's Data Download [++Service++](https://download.synopticdata.com/) for users with a free Synoptic account. The data download service can be accessed in the Data Viewer by clicking the 'Download' icon ( ![download_for_offline_24dp_666666_FILL1_wght400_GRAD0_opsz24.png](https://docs.synopticdata.com/__attachments/a_55a2eff9cc107248510dde6b9bc4ef58707208d98299e9d8b3eff111f840976a/download_for_offline_24dp_666666_FILL1_wght400_GRAD0_opsz24.png?cb=d6a95d209682f4d14e36b3cf4f2cab5a) ) from the Explore page station timeseries view. On the Table page, the Data Download Service can also be accessed from the 'How can I access this data'. ## My station has sensors at multiple heights, how can I see those? To preserve a clean and consistent viewing experience, the Data Viewer's map-based Explore page displays just a single sensor value. To view all sensor values for a variable in tabular form, navigate to Table page and toggle the 'Basic Weather' variable group to 'All' on the left side of the display. Complete station metadata, including all reporting variables, is available by selecting the 'Metadata' link ( ![toc_24dp_666666_FILL1_wght400_GRAD0_opsz24.png](https://docs.synopticdata.com/__attachments/a_ec67482b720db9a631ab8794c8d45f0dff45ddee8e98f04bb10e37d7a9d626dd/toc_24dp_666666_FILL1_wght400_GRAD0_opsz24.png?cb=83479d0320fdd625c5aad79eb6d653f7) ) from the Table page. All sensor values for a variable are also available as a timeseries chart from the 'Graph' page. Select the Graph page from the navigation pane, click 'Add New Plot', select the variable of interest from the 'Custom Variables' search field, and the station of interest. ## How long does it take for a newly added station to appear? Newly added stations are available in the Data Viewer's 'Data' display pages as soon as station data and metadata has been stored in our system. Station metadata caches that support Data Viewer's 'Metadata Explorer' page are updated every 6 hours. For this reason, it is possible that data for new stations may be displayed in the Data Viewer before the station is available for display in the 'Metadata Explorer'. ## How do I learn more about Synoptic's QC flags? Descriptions of Synoptic's quality control checks, and the thresholds we implement for each QC check and variable, are all available in our QC [++documentation++](https://docs.synopticdata.com/services/quality-control). A link to our QC documentation is also available from the Data Viewer's "About these data" link on the Explore page (bottom right corner of the application). ## Why don't I see my station of interest on the Data Viewer? Your station of interest may not show on the Data Viewer's map-based Explore page for one of a number of reasons: 1. **Synoptic's thinning algorithm has filtered your station of interest.** To preserve a clean and appealing visual display, we thin the data from our aggregated stores of \>150,000 active stations at coarse zoom levels (stations from federal networks of known quality are prioritized in thinning). If you cannot see your station of interest, try zooming to a local map view. 2. **The station belongs to a restricted network.**If this is the case, confirm that you are signed in and have access to the appropriate network. 3. **The station has not reported recently enough to be displayed on the Explore page.** When viewing data in 'Now' time, we restricted data to those stations which have reported in the last 90 minutes. When viewing historical data, station data is restricted to reports within +/- 45 minutes of the desired time. If the station has not reported within these time windows it will not display on the map. The easiest way to quickly find your station of interest in the Data Viewer is by using the Metadata Explorer's search functionality. Locate your station by searching based on the station name or id. Selecting the station and clicking the tabular data icon ( ![table_chart_24dp_666666_FILL1_wght400_GRAD0_opsz24.png](https://docs.synopticdata.com/__attachments/a_1fe7ff35db73f2811956d8145ee498bb203c908e0c580d4fba9639cc0810a1ed/table_chart_24dp_666666_FILL1_wght400_GRAD0_opsz24.png?cb=b2d56f2b097e93fffd43243c3d085346) ) from the station detail panel will take you to the current station data. If you know the station's Synoptic ID, you can also shortcut to the station's table page by appending the id to the Data Viewer url (e.g. ). --- language: "en" --- # High Frequency ASOS HF-ASOS data was unavailable from its source between October 2023 and January 2026. We have established a new connection with NWS and FAA which should provide reliable access to this dataset. We will continue to categorize the dataset as experimental. Since the mid 2010's the FAA has permitted/enabled many major airport weather stations, which are part of the Automated Surface Observing System (ASOS) to measure data at a **one-minute** temporal frequency than the traditional METAR frequency, which is "hourly with reports of significant change at any time." Because airport weather stations are operated as a cooperation between the FAA and NOAA, Synoptic receives HF-ASOS data via NOAA's MADIS service. HF-ASOS are also periodically referred to as "One minute observations" or "OMO" ## Considerations There are many nuances to receiving and using the HF-ASOS data. ### Variable precision and interpretation The telemetry mechanism used for HF/OMO ASOS data limits the precision of the values include in data messages. You will notice that HF-ASOS observations (and the 5 minute "HF-METAR" which is directly derived from this) exhibit lower precision. 1. Temperatures are expressed in whole degrees celsius 2. Wind speeds are a 2 minute average, even when looking at 1-minute observations. It is important to know that these limitations, along with other sampling factors means that these observations do not adhere to the METAR standard, and must not be used for aviation. Synoptic does not construct a METAR message from HF-ASOS data for this reason. ### Not every airport HF-ASOS are only available at *most* ASOS airport sensors. Many airports in the US are a different kind of station, known as an AWOS (automated weather observing station). The acronym may seem to mean the same thing, but the effect is that these other airport stations are often configured and operated differently than ASOS - which are all installed and managed by NOAA for the NWS and FAA. AWOS stations are not available for HF data. At this time ASOS and AWOS data are intermingled in our network ID 1 "ASOS/AWOS" and simply looking at our metadata we cannot immediately tell you whether a site is an AWOS or ASOS. Most of the major commercial airports are ASOS, and do have the HF service. ### Data organization and how to get it Synoptic exposes HF-ASOS data in two ways. Since 2017 we have received and publicly delivered a 5-minute subset of the HF-ASOS data, provided to us via MADIS, and we have blended those measurements in with our ASOS/AWOS network data. A special argument was added to Weather API - `hfmetars` - to allow queries to ignore these values and only provide the traditional METAR observations. Additionally, since 2019 Synoptic has received the full 1-minute data, as a low-latency provisional and real-time data stream from MADIS. Instead of combining these data with the existing METAR network, we created a new network to organize full HF-ASOS into, where the stations use their matching IDs (so Salt Lake is `KSLC`) with an additional `1M` - so [KSLC](https://viewer.synopticdata.com/kslc) is available for HF-ASOS as [KSLC1M](https://viewer.synopticdata.com/kslc1m). This is only available for stations which have reported the HF-ASOS data. ### Operational availability The HF-ASOS data feed is considered **experimental.** This means that the FAA and NOAA are both not giving full operational effort towards sustaining the dataset, like they would for the regular METAR reports. This means that brief to several-day outages are not uncommon. Like most outages, these are *completely outside of Synoptic's influence* ***.*** **We do not recommend developing applications solely based on the consumption of HF-ASOS data.** Our [Demos site](https://demos.synopticdata.com/hf-asos-available/index.html) has a tool that indicates the if the HF-ASOS data feed is flowing into Synoptic. ### Latency HF-ASOS is now a low-latency dataset. For availability latency (the time between when the observation was made and when Synoptic receives it) HF-ASOS, when operating normally, usually arrives with between 2 and 5 minutes latency. --- language: "en" --- # In-situ atmospheric measurement overview Let's briefly discuss some common ways we measure various variables, and more importantly some of the considerations you should make when using these data. Considerations do not include the universal concern which is that a sensor could be improperly installed, connected or calibrated, making it inaccurate. That is always a concern, particularly the farther a station is from a professional maintainer. ## Air Temperature Air temperature is the most common variable for a surface weather station. [In-Situ](https://github.com/synoptic/developers.synopticdata.com/blob/main/learn/in-situ) measurements (thermometers) often measure the electrical characteristics of metals at different temperatures. Different amounts of electricity can be measured from the metal and converted into a temperature based on how the sensor is designed. ### Limitations \& Considerations Depending on design, the ability to sense extreme temperatures or fast changes in temperature may be hampered. Over time the characteristic of the metals will change, and without re-calibrating the sensor, it may become less accurate. It is uncommon for commodity thermometers to be calibrated after they are deployed. ## Moisture Moisture can be measured many ways, and there are several moisture variables that can be sensed. Most common are Relative Humidity (RH) and dew point. The most common way for commodity sensors to measure RH is by assessing variations in the capacitance of a material exposed to the air. When the RH changes, this capacitance, which can be measured, changes in a relatively consistent fashion. To measure dew point directly, techniques exist to directly cool a surface until dew forms, and using a thermometer (above) to detect what temperature that was. This is very costly, and as a result is only found on very expensive observing platforms. In many instances the RH sensor is in the same physical package as the thermometer. There is another moisture measurement, called the wet bulb temperature. This can be measured by exposing water to flowing air and determining where the two temperatures reach equilibrium. This is generally hard to do automatically, and can mathematically be extracted from temperature and another moisture observation. ### Limitations and Considerations Similarly to thermometers, over time the ability of the material to represent the ambient conditions will decrease. Particularly, extreme cold can negatively impact the ability of an RH sensor to be accurate. Generally they can be recalibrated, but not necessarily repaired if found to have very low precision. ## Wind Wind is another of the most common measurements, and a wind sensor (anemometer) is one of the most identifiable components of a classic weather station. Wind speed historically was measured with some kind of spinning cup and wind vane (prop-vane) or propeller device (aerovane). The rotation of the cups or propellers is measured as electrical pulses, which can then be related back to a speed. Wind direction in these instruments is measured with a 'variable resistor' most of the time, which has different electrical properties depending on where the direction sensor is along a circle. However, in the last decade (and long before then) sonic wind sensors have become more common thanks to their decreased maintenance, lack of moving parts, and increased precision and accuracy. Sonic anemometers measure both the speed and direction of wind by sending small sound signals across a space, and measuring the doppler effect on the sound as it crossed that space. By measuring at 2 crossing directions, the speed in both angles, and thus the total speed and direction can be computed. Using a third pair of sensors, and separating the sensors both laterally and vertically 3-D wind speed and direction can be measured. ### Limitations and Considerations Besides normal wear-and-tear that degrades performance over time, anemometers are most popularly damaged by extreme weather conditions, which can damage them very visibly. Beyond that, ideally regular calibration should be performed on a mechanical anemometer for accurate measurement. prop-vane and aerovane sensors are not usually able to measure very low or variable wind speeds, and cannot measure turbulence directly. Sonic anemometers historically were very expensive and delicate, but that has changed recently. Today, many reasonably priced sensor packs utilize the solid-state and compact nature of sonic anemometers for their wind sensing. Sonic anemometers require an accurate observation of temperature and pressure to correctly determine wind speeds, and as a result can be victim to any of the issues those sensors face. Sonic anemometers also can have issues in cold weather, as ice can build up on the transducers, reducing or eliminating the ability to sense. Siting is one of the biggest issues with wind measurements. Though there is debate about what exactly representation even means, many stations are deployed close to obstacles which will change the wind speeds or directions from their free-field components which we would like to sense. Location concerns can render an anemometer completely useless depending on how close and significant nearby influences are. ## Pressure Barometric pressure is both a very interesting and valuable observation, and it is one of the easier observations to make. Pressure represents the force the air at a location would push on a vacuum. Thus, to measure pressure a vacuum is created, and sealed with something that will appear different depending on the force the atmosphere is exerting. Mercury was historically popular for barometers because in addition to its eagerness to change volume with temperature, it was very heavy, and therefore over a short vertical distance the atmospheric pressure could be measured (water, if used the same way would take over 5 meters where mercury requires around 30 inches). Since mercury is dangerous, a better way to automatically determine the pressure is to use sealed containers which are a vacuum inside, and whose exterior or lid is engineered so it can deflect slightly depending on increases or decreases of pressure. That deflection is then measured using several techniques, and converted into a pressure measurement. These canisters can be extremely small today, and barometers can be deployed in may environments as a result (most smartphones contain them). ### Limitations \& Considerations Barometers, like all sensors, do require regular calibration for ideal performance. However, unlike most atmospheric sensors, with relatively small error, the siting of a barometer is not critically important. Normally, outside of a sealed environment the barometric pressure is the same indoors and out, and certainly everywhere on a weather station the pressure should be the same. One concern is in wind, where a condition called dynamic pressure (pushing from the wind) can create momentary high and low pressure periods. This concept is used by aircraft to measure their airspeed via a Pitot tube. ## Precipitation Precipitation is a critical and conceptually simple atmospheric variable. Precipitation measurement is actually very complicated. We will discuss the several most common precipitation measuring methods we see: ### Rain Gauges A rain gauge is a bucket which quantifies how much water has entered it over a period of time. There are two variations: tipping bucket, and weighing. Tipping bucket use a teeter-tottering bucket device to discretely measure small amounts of liquid precipitation, reporting each tip of the bucket. A weighing gauge contains a pre-set amount of liquid, and a pressure sensor at the bottom, which reflects the weight of the contained fluid. When precipitation occurs the weight of the fluid increases, and that change is reflected as a precipitation amount. #### Other Rain Sensors There are a number of other ways to measure rain, some of which are frequently employed in all-in-one weather sensors. Sonic rain sensors employ what are essentially microphones to hear the impact of a raindrop on a clear surface. These care carefully tested and calibrated to do their best at estimating drop sizes and such. Hot plate anemometers maintain a metal surface at a high temperature (above water's boiling point), and the amount of energy required to keep the plate at that temperature is measured, as each molecule of water on the plate would have to be boiled. These techniques have various considerations for cost, power consumption and accuracy. ### Limits \& Considerations Gauge methods of measuring precipitation are often accurate in the presence of liquid rain, but become variable in the presence of cold, snow, debris or wind. Weighing gauges can be filled with antifreeze instead of water so in winter months they can generally still produce accurate liquid water measurements of snow and frozen precipitation. In cold weather, tipping buckets both can mechanically freeze as well as will fill with snow which does not drip through the buckets until it melts, up to several days later. There is lots of discussion about how well a single point precipitation observation represents anywhere else, but we won't go into that. ## Cloud Height/Ceiling Stations with the proper equipment can determine the height of one or more cloud levels directly or indirectly overhead using laser ceilometers. A ceilometer is a large laser range finder which sends a pulse of laser light, and records how long it takes for the reflection off a cloud to return. If a cloud is thin enough, responded pulses from a second or third cloud can be received. These return periods are timed, and pulses quickly analyzed to determine distances where clouds were encountered. By analyzing the measured clouds over time (since they move over a fixed point) the coverage of the clouds in a location can be determined. ### Considerations Because it can only see multiple cloud layers when either the lower layers are thin or the clouds are moving and exposing the multiple layers, reports of cloud height can vary widely from one to up to three layers. Ceilometers cannot assess the depth of a cloud, only the bottom. Ceilometers, like all lidars, are capable of seeing through a modest amount of rainfall, however this can disrupt the patterns the algorithms use to determine cloud heights, so generally in rain they are not fully functional. ## Visibility Horizontal visibility is affected by either fog (condensed water) or pollution, and is an important factor in aviation and road weather. Visibility is measured by placing a transmitter and receiver a short distance apart, and passing a light signal through the space. This light signal, usually a near-visible laser, will be impacted by the contents of the air, and the difference in strength between the emitted light and received light is measured. This difference is computed to represent an approximated visible distance, though the measurement itself was only made at a single point. ### Considerations Because the measurement is only made at a single point, it may not actually represent how the visibility changes over the given distance, so if you have 10 mile visibility, but there is fog 3 miles away, you will clearly not be able to see 10 miles. However, at the point of the measurement, the air was sufficiently clear. Airports frequently employ several of these sensors along a runway for this reason. ## Road Weather Many surface weather stations are operated by road agencies to monitor the travel conditions in their representative areas. In addition to standard weather above, road weather stations frequently include sensors measuring conditions in the road. These include * Road temperature * Road Condition The road temperature can be measured either in-situ or remotely. In-situ observation involves placing a sensor block into the road pavement, ideally matching as many conditions as the pavement so its measured temperature reflects that of the surrounding pavement. Remotely, passive infrared emissions, measured by a special camera looking at the road, can measure the road skin temperature as well. Both sub freezing or extremely hot conditions are common on road surfaces, and have implications for maintenance and treatment. Road condition is often measured using in-situ sensors or optical techniques. They are designed to determine wetness or ice on a given road surface sample. ## Ocean Weather Nautical considerations are a very important part of the weather enterprise, and Synoptic is no exception, with thousands of publicly and privately owned buoy data sources available. Weather buoys often measure the same variables as mentioned above, as well as oceanic factors such as water information (temperature, turbidity, salinity, etc.) and dynamic information such as wave heights. Water information is sensed by a pack of sensors attached to the buoy anchor line, and using similar techniques to the above. Temperature is measured the same way, comparing the electrical characteristics of metal exposed to the water at the given temperature. Frequently multiple temperature sensors will be placed at different depths. Wave heights are measured by using the buoy's anchor line, which is capable of extending and retracting based on the bouncing of the buoy. The extension or retraction of this line is determined from some median state, and this is reported as the current wave height. This wave height information is critical for mariners and ocean safety organizations. ### Limitations and Considerations Due to their hardened nature, buoys are occasionally able to survive hurricanes and severe weather events better than land-based stations which are not engineered for the constant assault of ocean waves. In addition, the surface/in-situ observations to determine El NiΓ±o (ENSO) sea surface temperature patterns comes from a network of carefully gridded buoys in the Pacific Ocean. ## Soil Conditions Many weather stations are established to assist with agriculture, and one of the most important considerations for agriculture is the moisture and temperature in the soil. Soil temperature measurements employ the same techniques as above. Soil moisture is measured by determining how easily electrical current travels through a short distance of soil. The less moisture that is present, the harder it is for the electricity to travel. For this reason soil moisture sensors often resemble forks, where one tine produces a current and the other attempts to receive it. This can then be stabbed into the soil at the desired height to give a measurement from relatively undisrupted soil. ### Applications and Considerations Soil sensors can be placed at various depths depending on the requirements of the data recipients. Frequently 5cm and 10cm are common. Different stations may perform soil measurement differently. Soil sensors ideally will be located some distance away from the sensor, and might even include multiple ground coverings to represent the different forms of water processing that may happen. Soil sensor electronics may be damaged by complete submersion in water, so flooding can result in permanent damage or disabling of a soil sensor set. ## The Sun Weather stations can measure the amount of sunlight that reaches the ground. This is called shortwave radiation, and it is measured via a pyranometer, which is a device that directly converts incoming solar radiation into a small but measurable amount of electricity. It is also a radiometer which accepts only short-wavelength electromagnetic waves. In effect they are small, precise solar panels. The amount is expressed in watts per meter squared, representing a total amount of solar energy that arrives at the surface every second. These radiometers An alternative form of solar sensor involves collocated black and white panels, each with thermometers. Using a calibrated system, the difference in temperature between the hot black panels, and cool white panels in direct sunlight represents the air temperature. These sensors are more expensive than the modern methods, however. ### The opposite of the sun For the atmosphere, the energy that comes from the sun is balanced by energy leaving. At the surface we can also measure that departing energy, as it reflects how the surface will warm up during the day, or cool at night. This is measured using a longwave radiometer, which filters out shortwave (visible) light, points down towards the ground, and only measures the emissions that are actually created by the ground (which happen 24 hours per day, not just when the sun is up). Finally, there is a sensor that can combine all these into an interesting single number, called a net radiometer, which measures both longwave and shortwave radiation from both directions, and can subtract the energy going up from the energy coming down, and give a total energy balance for any time. ## Air Quality Air quality is an entire category of observations, but for our purposes here, it can be reduced to the sensing of particles or chemicals in the air. Particles can be measured either in a gross fashion, using techniques similar to visibility, above, or by passing air through careful filters and weighting them after a fixed period of time. In the case of PM2.5 (particulate matter less than 2.5 micrometers(Β΅m) in size), two filters are employed, one filter rejects all particles over 2.5 Β΅m in size, and within the enclosed chamber, either a second filter attempts to acquire all contained particles, or lasers are used to determine the number of contained particles. Lasers can also be used to determine contents of specific chemicals, based on the tendency of chemicals to absorb specific wavelengths of electromagnetic energy. In this sense, a chamber can be built to hold sampled air, and a laser of specific frequency can be used to get a measure of how much of a certain molecule is in the air. ## Fuel Moisture Fire weather stations keep track of a variable representing the moisture and temperature of fuels of a certain diameter. This is done (often) by attaching sensors inside a wooden dowel of the represented diameter, and measuring its temperature and moisture within, using methods similar to those above. This stick is then located in a representative location such that it can approximate the conditions experienced by an actual fallen stick. ## Weather Condition Some airport weather stations will produce a coded description of the present weather at their station. These conditions are often computed by examining the other variables measured, including cloud heights, temperatures, winds, precipitation, visibility, and others, to make a guess at what is actually happening. Often times, for larger airports, this value can also be set manually. --- language: "en" --- # Independently reported high or low temperatures A common source of confusion can arise from observing platforms which submit both regular frequency observations (say, hourly) as well as summary-type statistical measurements, such as a 6 or 24 hour max temperature (variables `air_temp_high_6_hour` and `air_temp_high_24_hour` are variables which will exhibit this quality). It is common for the reported maximum value to be higher than any of the individual reported values. This is because the extreme value indicated is often reported from a more frequent sample of the atmosphere than the regular reports. Though it varies by variable, an hourly report is often a sample of a short period of time around when the report is given. This means that any variations that happened between those reports are not actually shared by the station, but may be considered for the max value reports. This principle is true even in the case of high frequency reports, at 5 or even 1 minute reporting frequency. Sensors often sample temperatures, for instance, tens or hundreds of times per second. ![Untitled drawing (2).png](https://docs.synopticdata.com/__attachments/a_91b02495bcf7033f579d2bbee1ed61c84eaa0ba47ad0d9ab948006567f5a1637/Untitled%20drawing%20(2).png?cb=779d6b220131301172dd67ae5794beba) Example of a continuous temperature observation where blue arrows indicate reporting events. The purple arrow indicates where the maximum reported value would be, but the green indicates the maximum sampled value, and is higher. --- language: "en" --- # 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`,`/variables`and some [errors](https://docs.synopticdata.com/services/errors.md) 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](https://docs.synopticdata.com/services/errors.md) 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](https://docs.synopticdata.com/services/errors.md) 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](https://docs.synopticdata.com/services/json-output-format.md#period-of-record) | | `RESTRICTED` , `RESTRICTED_DATA` | `true` - Public, `false` - Restricted data access | boolean | | `RESTRICTED_METADATA` | `true` - Public, `false` - Restricted metadata 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" } #### Siting objects `SITING` (station-specific key) is also returned in each station object for data and Metadata services (not the Networks service) when passed with `complete=1`. By default, this is a list with a single dictionary containing most recent siting attributes, or can be a list of multiple dictionaries showing full siting history if `sitinghistory=1`. Example JSON of a SITING object: JSON "SITING": [ { "start": "end": "slope_cat": "slope_deg": "aspect_deg": "aspect_card": "cover": "treatment": "hydro_cond": "curve": }, {}, ] ### 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](https://docs.synopticdata.com/services/latest.md), [Nearest](https://docs.synopticdata.com/services/nearest-time.md) 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. When `value_percentile` is added to a Latest request, the nearest percentile is returned as follows: JSON "OBSERVATIONS": { "air_temp_value_1": { "value": 11.461, "date_time": "2025-02-28T22:00:00Z", "value_percentile": 49.9 } } [Time Series](https://docs.synopticdata.com/services/time-series.md), [Latency](https://docs.synopticdata.com/services/latency.md) 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](https://docs.synopticdata.com/services/precipitation.md) 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](https://docs.synopticdata.com/services/quality-control-segments.md) 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](https://docs.synopticdata.com/services/qc-flag-types.md)). | 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_SUMMARY`details 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](https://docs.synopticdata.com/services/networks.md) Within the MNET object, the [Networks service](https://docs.synopticdata.com/services/networks.md) returns objects per Network containing station statistics and metadata. Example Networks output: "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](https://docs.synopticdata.com/services/network-types.md) 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](https://docs.synopticdata.com/services/variables.md) 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](https://docs.synopticdata.com/services/network-types.md) 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](https://docs.synopticdata.com/services/quality-control-types.md) 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 `QCTYPES`contains 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 | --- language: "en" --- # Latency Returns transmission latency for a station or set of stations based on a start and end date/time. ## Request Format A Latency request is an HTTP URL with the following form: https://api.synopticdata.com/v2/stations/latency This service reports the delay time (in minutes) of an observation received at our ingest servers relative to the observation's timestamp. Due to the nature of computer clock drift and time synchronization, some observations can be received "before they occur". This results in a negative latency value. This can occur from in incorrect time stamp as provided by the station, or (more often than not) natural clock drift. 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](https://docs.synopticdata.com/account/public-api-tokens.md). * 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. Station Selection Parameters These selectors individually or combined to target the desired stations. **Exclusion Operator** Selectors noted as *(excludable)* may be specified with a `!` preceding a value to remove/exclude from the selection from a result set. So `stid=!KSLC` would prevent KSLC from returning in a query. This should be used in combination with different selectors. Remember to only include any given selector once. `stid` (string, *excludable* ), Single or comma separated list of SynopticLabs station IDs. Use a `!` before any value to exclude matching stations. Example: `stid=mtmet,kslc,fps`. Try it Now `state` (string, *excludable* ), Single or comma separated list of abbreviated 2 character states. If country is not included, default is United States (`US`). Use a `!` before any value to exclude matching stations. Example: `state=ut,wy,dc`. `country` (string, *excludable* ), Single or comma separated list of abbreviated 2 or 3 character countries. Use a `!` before any value to exclude matching stations. Example: `country=us,ca,mx`. `nwszone` (string, *excludable* ), Single or comma separated list of National Weather Service Zones. Use a `!` before any value to exclude matching stations. Example: `nwszone=UT003,CA041`. `nwsfirezone` (string, *excludable* ), Single or comma separated list of National Weather Service Fire Zones. Use a `!` before any value to exclude matching stations. Example: `nwsfirezone=LOX241` `cwa` (string, *excludable* ), Single or comma separated list of National Weather Service County Warning Areas. Use a `!` before any value to exclude matching stations. Example: `cwa=LOX`. `gacc` (string, *excludable* ), Single or comma separated list of Geographic Area Coordination Centers. Use a `!` before any value to exclude matching stations. Example: `gacc=GB`. `subgacc` (string, *excludable* ), Single or comma separated list of Sub Geographic Area Coordination Centers. Use a `!` before any value to exclude matching stations. Example: `subgacc=EB07`. `county` (string, *excludable* ), Single or comma separated list of counties. Use the `state` parameter to filter by state in the case of duplicate county names (i.e. "King"). Use a `!` before any value to exclude matching stations. Example: `county=king&state=wa`. `vars` (string), Single or comma separated list of sensor variables [found here](https://docs.synopticdata.com/services/station-variables.md). 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. *Some web services use this argument to adjust what information is delivered.* Example: `vars=wind_speed,pressure`. Try it Now `varsoperator` (string), Define how `&vars` is understood. `or` (the default) means any station with any variable in the list is used. `and` means a station must report every variable to be included. Example: `varsoperator=and`. `network` (number, string, *excludable* ), Single or comma separated list of network IDs or short names. The ID can be found be using the [Networks](https://docs.synopticdata.com/services/networks.md) service and are also listed [here](https://docs.synopticdata.com/services/station-networks-providers.md). Use a `!` before any value to exclude specific networks from a result set. Example: `network=153` or `network=44,251`. `radius` (string), 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 with units of miles. Adding `limit=n` to the query will limit the number of returned stations to **n** stations, and will order the stations by `DISTANCE`. Some examples are: `radius=41.5,-120.25,20`, `radius=wbb,10`, `radius=41.5,-120.25,20&limit=10`. `bbox` (string), 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`. **Bounding Box Thinning** A new feature allows you to use the API to thin the returned station set within a bounding box by providing some additional arguments. These arguments only take effect when the `bbox` parameter is used: `height` (number) the height of the map viewport in pixels `width` (number) the width of the map viewport in pixels `spacing` (number) the preferred number of pixels a station on the map should consume `networkimportance` (numbers, comma-separated) a list of comma separated network IDs that will be considered in the order provided. When there is a collision of stations within the defined "spacing" area, any station matching the list of preferred networks will be shown over any other. `status` (string), A value of either active or inactive returns only stations that are currently set as active in the archive. Stations are set to active if they have reported an observation in the last 30 days. By default, omitting this parameter will return all stations. Example: `status=active`. * `start` and `end` * `start` \& `end`, Defines the start and end 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. The start parameter must be used with the end 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. **Optional Parameters** * `obtimezone` (UTC \[default\], local), Indicates if the time zone of the response is in UTC or the local timezone of the station where the data was observed. Sets the timezone applied to the observation output (input times associated with `start` and `end` are always UTC). Example: `obtimezone=local` * `showemptystations` (0 \[default\], 1), Indicates if stations with no observations for the requested time span will be returned. 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. * `stats` (min, max, mean, median, count, stdev, all), Indicates what statistical values to return. Values can not be combined. * `stats=min` returns the minimum value and time stamp. * `stats=max` returns the maximum value and time stamp. * `stats=mean` returns the mean (average) value and start and end time stamps. * `stats=median` returns the median value and start and end time stamps. * `stats=count` returns the number of mins in time span. * `stats=stdev` returns the standard deviation value and start and end time stamps. * `stats=all` returns all statistics. * `complete` (0 \[default\], 1), 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. Example: `complete=1`. * `fields` (string), Case-insensitive comma-separated list of metadata attributes to include in the output response. Default is to include all attributes. Only works with attributes defined in the default metadata set (e.g. attributes shown via `complete=1` cannot be selected). Example: `fields=stid,name`. * `sitinghistory` (0 \[default\], 1), Will return all historical siting metadata for each station, as a list within the `SITING` key (requires `complete=1` to be enabled). Example: `sitinghistory=1`. The following example returns the latency and statistics for `stid=wbb` in for January 1, 2018: https://api.synopticdata.com/v2/stations/latency?stid=wbb&start=201801010000&end=201801012359&stats=all&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](https://en.wikipedia.org/wiki/ISO_8601) format. This behavior can be changed by passing a string with a valid [strftime](https://strftime.org/) 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](https://en.wikipedia.org/wiki/Unix_time) time in terms of seconds (this parameter cannot be used with `obtimezone`). This is a special function in addition to the supported [strftime](https://strftime.org/) arguments. * `output` (json \[default\], xml), Indicates the response format of the request. It's recommended to use the [JSON](https://json.org/) format which there are well supported parsing libraries in all major languages. ## Request Response **JSON Format** The Latency 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: JSON { 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", LATENCY: { date_time: ["2018-01-01T00:00:00Z","2018-01-01T00:01:00Z",...], values: [-3,5,...] }, RESTRICTED_DATA: "0", STID: "WBB", LONGITUDE: "-111.84755", UNITS: { position: "m", elevation: "ft" }, STATE: "UT", STATISTICS: { count: 1440, start: "201801010000", minimum: -3, end: "201801012359", mintime: "2018-01-01T00:00:00Z", standard_deviation: 2.766415596008301, maxtime: "2018-01-01T00:01:00Z", median: 3, average: 2.2166666984558105, maximum: 5 }, LATITUDE: "40.76623", TIMEZONE: "America/Denver", ID: "1" } ], SUMMARY: { DATA_QUERY_TIME: "116.713047028 ms", RESPONSE_CODE: 1, RESPONSE_MESSAGE: "OK", METADATA_RESPONSE_TIME: "17.0068740845 ms", DATA_PARSING_TIME: "5.17821311951 ms", VERSION: "v2.21.0", TOTAL_DATA_TIME: "121.893167496 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{}` * `LATENCY[]`, contains a timestamps and latency values in (in minutes) * `STATISTICS[]`, contains statistics. --- language: "en" --- # Latency of observation data on the Synoptic platform Synoptic uses the term "latency" to refer to the period of time between when a sample is measured and when it is available to end users from Synoptic services. There are two contributors to latency: 1. Provider latency, the amount of time it takes the upstream events to make the data available to Synoptic. Our data teams work with providers to help them minimize this time by reducing upstream processing, or using simpler techniques. Ultimately providers control this latency. Synoptic works diligently to acquire data with the lowest-latency available. 2. Acquisition latency - the time between when the data was available, and when synoptic acquired it. Certain inefficient delivery methods (such as providing multiple days of data per push) also result in significant re-processing of existing data, adding seconds of latency. Synoptic can tune scheduling and optimize processing to minimize this time, but it is a function of the provider. 3. Synoptic platform latency. This is the factor Synoptic maintains full responsibility for. Synoptic employs a distributed event-based architecture to process billions of daily observations with ++under 10 seconds of total latency++ . During this time data are organized into our foundational data model, given quality checks, including spatial and temporal comparisons, and made available to streaming (e.g. [push streaming](https://docs.synopticdata.com/services/push-streaming.md)), request-based ( [Weather API](https://docs.synopticdata.com/services/weather-api.md)) applications, and other data delivery systems. The total latency for any observation can be queried from Weather API's [Latency](https://docs.synopticdata.com/services/latency.md) data service. You can also view an aggregated representation of latency per network on the [Data Availability Dashboard](https://docs.synopticdata.com/services/data-availability-dashboard.md) . ## How do I minimize latency when accessing data? Synoptic's [Push Streaming](https://docs.synopticdata.com/services/push-streaming.md) is the minimum-latency mechanism to access observation data. This is a WebSocket-based utility for receiving observations within 2 seconds of their deliverable accessibility. Some users will thrash Weather API to achieve minimal latency without the push streaming service. This is generally difficult to stay within concurrency requirements, and will perform poorly for more than a small number of stations. ## Factors that cause latency to vary Latency varies from our upstream sources for a variety of reasons. Shared systems or dependencies on networking managed by others is a common source of delay. Scheduling and conflicts within upstream systems can also delay observations. Issues at the observing station or telemetry - including bandwidth limitations, and variable sizes of reports (some stations report more variables at certain times) will also alter the time it takes for data to be available to Synoptic. Once received by Synoptic, we added latency should not vary substantially, as our platform elastically scales to meet demand. Periods were a significant number of reports are received faster than our scale-in capacity (such as short term backfills) may result in brief slowdowns on the order of seconds. Synoptic is constantly innovating on our platform to further minimize potential latency impacts. Synoptic will alert our [http://status.synopticdata.com](http://status.synopticdata.com/) page if there are factors within our control causing an increase to latency beyond several minutes. Synoptic does not currently publish any general latency metrics, due to the fact almost all latency experienced by customers is upstream. Refer to [Dataset-specific documentation](https://docs.synopticdata.com/services/dataset-specific-documentation.md) to learn more about latency characteristics of selected datasets. --- language: "en" --- # Latest Returns the most recent observation from a station or set of stations. Requests to the Latest service are limited to 75,000 stations and must contain either a Station Selection Parameter or the `within` parameter. See [Request Volume Limitations](https://docs.synopticdata.com/services/api-performance-and-limits.md#Request-Volume-Limitations) for more info. ## 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](https://docs.synopticdata.com/account/public-api-tokens.md). **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. Station Selection Parameters These selectors individually or combined to target the desired stations. **Exclusion Operator** Selectors noted as *(excludable)* may be specified with a `!` preceding a value to remove/exclude from the selection from a result set. So `stid=!KSLC` would prevent KSLC from returning in a query. This should be used in combination with different selectors. Remember to only include any given selector once. `stid` (string, *excludable* ), Single or comma separated list of SynopticLabs station IDs. Use a `!` before any value to exclude matching stations. Example: `stid=mtmet,kslc,fps`. Try it Now `state` (string, *excludable* ), Single or comma separated list of abbreviated 2 character states. If country is not included, default is United States (`US`). Use a `!` before any value to exclude matching stations. Example: `state=ut,wy,dc`. `country` (string, *excludable* ), Single or comma separated list of abbreviated 2 or 3 character countries. Use a `!` before any value to exclude matching stations. Example: `country=us,ca,mx`. `nwszone` (string, *excludable* ), Single or comma separated list of National Weather Service Zones. Use a `!` before any value to exclude matching stations. Example: `nwszone=UT003,CA041`. `nwsfirezone` (string, *excludable* ), Single or comma separated list of National Weather Service Fire Zones. Use a `!` before any value to exclude matching stations. Example: `nwsfirezone=LOX241` `cwa` (string, *excludable* ), Single or comma separated list of National Weather Service County Warning Areas. Use a `!` before any value to exclude matching stations. Example: `cwa=LOX`. `gacc` (string, *excludable* ), Single or comma separated list of Geographic Area Coordination Centers. Use a `!` before any value to exclude matching stations. Example: `gacc=GB`. `subgacc` (string, *excludable* ), Single or comma separated list of Sub Geographic Area Coordination Centers. Use a `!` before any value to exclude matching stations. Example: `subgacc=EB07`. `county` (string, *excludable* ), Single or comma separated list of counties. Use the `state` parameter to filter by state in the case of duplicate county names (i.e. "King"). Use a `!` before any value to exclude matching stations. Example: `county=king&state=wa`. `vars` (string), Single or comma separated list of sensor variables [found here](https://docs.synopticdata.com/services/station-variables.md). 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. *Some web services use this argument to adjust what information is delivered.* Example: `vars=wind_speed,pressure`. Try it Now `varsoperator` (string), Define how `&vars` is understood. `or` (the default) means any station with any variable in the list is used. `and` means a station must report every variable to be included. Example: `varsoperator=and`. `network` (number, string, *excludable* ), Single or comma separated list of network IDs or short names. The ID can be found be using the [Networks](https://docs.synopticdata.com/services/networks.md) service and are also listed [here](https://docs.synopticdata.com/services/station-networks-providers.md). Use a `!` before any value to exclude specific networks from a result set. Example: `network=153` or `network=44,251`. `radius` (string), 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 with units of miles. Adding `limit=n` to the query will limit the number of returned stations to **n** stations, and will order the stations by `DISTANCE`. Some examples are: `radius=41.5,-120.25,20`, `radius=wbb,10`, `radius=41.5,-120.25,20&limit=10`. `bbox` (string), 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`. **Bounding Box Thinning** A new feature allows you to use the API to thin the returned station set within a bounding box by providing some additional arguments. These arguments only take effect when the `bbox` parameter is used: `height` (number) the height of the map viewport in pixels `width` (number) the width of the map viewport in pixels `spacing` (number) the preferred number of pixels a station on the map should consume `networkimportance` (numbers, comma-separated) a list of comma separated network IDs that will be considered in the order provided. When there is a collision of stations within the defined "spacing" area, any station matching the list of preferred networks will be shown over any other. `status` (string), A value of either active or inactive returns only stations that are currently set as active in the archive. Stations are set to active if they have reported an observation in the last 30 days. By default, omitting this parameter will return all stations. Example: `status=active`. * `complete` (0 \[default\], 1), 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. Example: `complete=1`. * `fields` (string), Case-insensitive comma-separated list of metadata attributes to include in the output response. Default is to include all attributes. Only works with attributes defined in the default metadata set (e.g. attributes shown via `complete=1` cannot be selected). Example: `fields=stid,name`. * `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. * `fuel_moisture` (gm, %), Fuel Moisture: Grams, %. 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. * `sitinghistory` (0 \[default\], 1), Will return all historical siting metadata for each station, as a list within the `SITING` key (requires `complete=1` to be enabled). Example: `sitinghistory=1`. * `value_percentile` (complete, daily_min, daily_max), Returns the nearest percentile for the observed value. Only available for air temperature, wind speed or wind gust. `complete`, `daily_min` or `daily_max` determine which percentile dataset is used. * `complete` uses a percentile distribution derived from all observations in the full period-of-record for each station and variable. * `daily_min` and `daily_max` use a percentile distribution derived from all daily minimum or maximum values spanning the full period-of-record for each station and variable. These are timezone-specific, and will respect the `obtimezone` argument. **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](https://en.wikipedia.org/wiki/ISO_8601) format. This behavior can be changed by passing a string with a valid [strftime](https://strftime.org/) 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](https://en.wikipedia.org/wiki/Unix_time) time in terms of seconds (this parameter cannot be used with `obtimezone`). This is a special function in addition to the supported [strftime](https://strftime.org/) arguments. * `output` (json \[default\], xml, geojson), Indicates the response format of the request. It's recommended to use the [JSON](https://json.org/) 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](https://docs.synopticdata.com/services/mesonet-data-qc.md), 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](https://docs.synopticdata.com/services/mesonet-data-qc.md) 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`. `all` is equivalent to `qc_checks=synopticlabs`, and only applies the Synoptic basic+advanced QC suite. [++Click here++](https://docs.synopticdata.com/services/mesonet-data-qc.md) to read more about the basic and advanced groups. 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: 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 } } * `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. --- language: "en" --- # Synoptic Data QC ## Introduction The `/timeseries`, `/latest` and `/nearesttime` API services provide Synoptic QC (i.e. data checks) as additional attributes delivered alongside the data. QC is performed immediately when new data is received, and is available for "real time" data in addition to historical data. Examples applying a suite of Synoptic data checks are shown below. API users can elect to return these flags alongside the data, or to automatically remove flagged data. Air temperature observations during June, 2019 for a 30-mile radius centered in Houston, TX: ![image-20230524-141907.png](https://docs.synopticdata.com/__attachments/a_2a776270803021ed36ccf1f61f18f4733d292270ee2ee0596a51eb90e53ab46e/image-20230524-141907.png?cb=fa4a3429811aff24e436d4e1021bf4cb) Wind gust observations during Feb, 2020 for a 30-mile radius centered in Seattle, WA: ![image-20230524-141919.png](https://docs.synopticdata.com/__attachments/a_002ffcad535b49596fcc08e31c98f5c1ffd9dd5de93d122be8dee18da2ec4e60/image-20230524-141919.png?cb=3480f0cc8a109b755133c3a515234ace) There are many potential causes of erroneous data: sensor failure, poor sensor siting or calibration, data transmission errors, or incorrect conversion of the transmitted data arising from invalid metadata. The Synoptic data checks are intended to identify: (1) physically implausible values and (2) values that may not be representative of the conditions prevailing at that time (outliers). Synoptic's QC can significantly reduce erroneous data, however all data accessible via the Synoptic Weather API must be considered provisional. Official data archives for some networks are available directly from data providers. ### Basic QC * Range Check (`sl_range_check`) * Rate of Change Check (`sl_rate_check`) * Temporal Persistence Check (`sl_pers_check`) * Wind Speed vs Maximum Gust Check (`sl_windspd_maxgust_check`) * Wind Gust Factor Check (`sl_wind_gust_factor_check`) * Secondary Range Check (`sl_secondary_range_check`) * Secondary Persistence Check (`sl_secondary_pers_check`) * Soil Moisture Freezing Check (`sl_soil_moisture_freeze_check`) * Sensor Status Signal Check (`sl_sensor_status_signal_check`) Note that **by default, the range check is automatically applied to remove data from all Weather API requests**. In addition, the range check acts as a single entry point, where no further basic or advanced data checks are run after a failed range check. ### Advanced QC * Spatial Value Check (`sl_spatial_value_check`) (8 variables) * Percentile Checks (`sl_percentile_looutlier_check`, `sl_percentile_hioutlier_check`, `sl_percentile_loflag_check`, `sl_percentile_hiflag_check`) (air temperature only) * Snow Depth History Check (`sl_snow_depth_hist_check`) Basic QC checks are implemented using known physical relationships for each variable (e.g. range, rate and persistence thresholds) and often have defined WMO equivalent standards. Basic checks compare observed data against thresholds or against other variables within a station report, whereas advanced checks leverage secondary derived datasets (e.g. historical percentiles or gridded products), or use spatial comparisons with neighboring stations. API users can specify individual qc checks, such as `qc_checks=sl_range_check,sl_rate_check`, or all `basic` or `advanced` checks can be enabled with `qc_checks=basic` or `qc_checks=advanced`. In most cases, **it is best to specify the full suite of Synoptic basic and advanced qc checks with** `qc_checks=synopticlabs`. For additional details on usage, see "Data Checks and Quality Control" in the docs specific to each service. Note that `sl_percentile_loflag_check` and `sl_percentile_hiflag_check` are not included in the `synopticlabs` suite, such that a user can elect to remove data for all `synopticlabs` checks without removing any valid observations. In addition, the legacy MesoWest data checks (`mw_multvariate_lin_reg_check`, `mw_24h_wind_persistence_check` and `mw_uu2dvar_rejection`) are not included in the `synopticlabs` check suite, and must be enabled individually or with `qc_checks=mesowest`. Please contact us for additional information on the appropriate application of Synoptic data checks for your use case. ### QC via the Weather API Within the [Time Series](https://docs.synopticdata.com/services/time-series.md), [Latest](https://docs.synopticdata.com/services/latest.md) and [Nearest Time](https://docs.synopticdata.com/services/nearest-time.md) services, users can add QC parameters to their queries to return and optionally apply QC checks. By default, the Weather API doesn't return data that has been flagged as non-plausible by the [Synoptic Range Check](https://docs.synopticdata.com/services/mesonet-data-qc.md#Range-check). 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. * `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`. `all` is equivalent to `qc_checks=synopticlabs`, and only applies the Synoptic basic+advanced QC suite. Some examples of modifying the default QC checks are: * `qc_checks=synopticlabs,ma_range_check`, Applies the Synoptic QC suite (basic + advanced) and the MADIS range check * `qc_checks=synopticlabs,madis`, Applies the Synoptic and MADIS QC suites. ### QC segments service Nearly all users will rely on the `/timeseries`, `/latest` and `/nearesttime` API services to identify the values that fail relevant data checks. However, those services rely on code to access the archived data checks that are also available to users via the [QC segment API service](https://docs.synopticdata.com/services/quality-control-segments.md) `/qcsegments`. For efficient storage and short access times, only the start and end times are stored for each period for which any values have failed a data check (referred to as a QC segment). ## Data Checks Summary | Data Check | API name | Description | |--------------------------------------------------------------------------------------------------|---------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | [Range check](https://docs.synopticdata.com/services/mesonet-data-qc.md#Range-check) | `sl_range_check` | Identifies physically implausible values. For example, air temperature of 65Β°C (150Β°F) or -62Β°C (-80Β°F). | | [Rate of change check](https://docs.synopticdata.com/services/mesonet-data-qc.md#Time-rate-of-change-check) | `sl_rate_check` | Identifies if the absolute difference in two consecutive values is greater than the maximum plausible rate of change expected for the observed time interval. | | [Persistence check](https://docs.synopticdata.com/services/mesonet-data-qc.md#Persistence-check) | `sl_pers_check` | Identifies if a sequence of observations appear unchanging. For example, an air temperature sensor reporting the same value every 15 minutes for 24 hours. | | [Wind speed vs. maximum gust check](https://docs.synopticdata.com/services/mesonet-data-qc.md#Wind-speed-vs.-wind-gust-check) | `sl_windspd_maxgust_check` | Flags both wind speed and gust if the wind speed is greater than the wind gust. | | [Wind gust factor check](https://docs.synopticdata.com/services/mesonet-data-qc.md#Wind-speed-vs.-wind-gust-check) | `sl_wind_gust_factor_check` | Flags wind gust (and speed for some conditions) using the ratio of wind gust to wind speed. | | [Secondary range check](https://docs.synopticdata.com/services/mesonet-data-qc.md#Secondary-range-check) | `sl_secondary_range_check` | If wind speed (or gust) is flagged with the Range Check, then apply the Secondary Range Check flag to wind gust (or speed). | | [Secondary persistence check](https://docs.synopticdata.com/services/mesonet-data-qc.md#Secondary-persistence-check) | `sl_secondary_pers_check` | If wind speed (or gust) is flagged with the Persistence Check, then apply the Secondary Persistence Check flag to wind gust (or speed). | | [Soil moisture freezing check](https://docs.synopticdata.com/services/mesonet-data-qc.md#Soil-moisture-freezing-check) | `sl_soil_moisture_freeze_check` | Flags soil moisture when soil temperature is \< 0Β°C. | | [Sensor status signal check](https://docs.synopticdata.com/services/mesonet-data-qc.md#Sensor-status-signal-check) | `sl_sensor_status_signal_check` | Indicates bad sensor status, from provider-sourced status signal. | | [Snow depth history check](https://docs.synopticdata.com/services/mesonet-data-qc.md#Snow-depth-history-check) | `sl_snow_depth_hist_check` | Compares current snow depth observations against the median of multi-day snow depth history. | | [Percentile high outlier check](https://docs.synopticdata.com/services/mesonet-data-qc.md#Percentile-high-outlier-check) | `sl_percentile_hioutlier_check` | Uses the percentile distribution from the station's historical record to identify high outliers (air temperature only). | | [Percentile low outlier check](https://docs.synopticdata.com/services/mesonet-data-qc.md#Percentile-low-outlier-check) | `sl_percentile_looutlier_check` | Uses the percentile distribution from the station's historical record to identify low outliers (air temperature only). | | [Percentile high flag check](https://docs.synopticdata.com/services/mesonet-data-qc.md#Percentile-high-flag-check) | `sl_percentile_hiflag_check` | Uses the percentile distribution from the station's historical record to identify "interesting" values that are near or above the historical high value for that date and time (air temperature only). | | [Percentile low flag check](https://docs.synopticdata.com/services/mesonet-data-qc.md#Percentile-low-flag-check) | `sl_percentile_loflag_check` | Uses the percentile distribution from the station's historical record to identify "interesting" values that are near or below the historical low value for that date and time (air temperature only). | | [Spatial value check](https://docs.synopticdata.com/services/mesonet-data-qc.md#Spatial-value-check) | `sl_spatial_value_check` | Compares the current observation value to nearest-in-time values from neighboring stations within distance and elevation thresholds (air temperature, relative humidity, dew point temperature, wind speed, wind gust, pressure and altimeter). | | [Linear regression check](https://docs.synopticdata.com/services/mesonet-data-qc.md#Linear-regression-check) | `mw_multvariate_lin_reg_check` | Spatial analysis check courtesy of the University of Utah MesoWest program. | | [24-hr wind persistence check](https://docs.synopticdata.com/services/mesonet-data-qc.md#24-hr-wind-persistence-check) | `mw_24h_wind_persistence_check` | Persistence check to identify unchanging wind speed values, courtesy of the University of Utah MesoWest program. This check is redundant to the `sl_pers_check`. | | [UU2DVAR rejection check](https://docs.synopticdata.com/services/mesonet-data-qc.md#UU2DVAR-rejection-check) | `mw_uu2dvar_rejection` | Spatial analysis check courtesy of the University of Utah Variational Surface Analysis (UU2DVAR). | [See a full list of our QC Checks](https://docs.synopticdata.com/services/qc-flag-types.md) ## Data Check Descriptions Technical descriptions of the Synoptic and MesoWest data checks. ### Range check > Is the value physically plausible? **API Name** : `sl_range_check` Physically implausible values are identified using this check. Only if a value passes this check will the remaining QC checks be applied. | Variable | Unit | Minimum | Maximum | |---------------------------------------------|----------------|----------|----------| | Altimeter | Pascals | 85000 | 108000 | | Pressure | Pascals | 60000 | 108000 | | Temperature | Celsius | -59.44 | 57.22 | | Dew Point | Celsius | -59.44 | 35 | | Relative Humidity | % | 0.01 | 103 | | Wind Speed | m/s | 0 | 102.89 | | Wind Direction | Degrees | 0 | 360 | | Wind Gust | m/s | 0 | 102.89 | | Snow depth | Millimeters | 0 | 12700 | | Solar Radiation | W/m\*\*2 | 0 | 1500 | | Soil Temperature | Celsius | -50 | 85 | | Precipitation accumulated | Millimeters | 0 | NULL | | Sea level pressure | Pascals | 85000 | 108000 | | Hours of sun | Hours | 0 | 24 | | Water Temperature | Celsius | -17.78 | 57.22 | | Weather conditions | code | 0 | 512000 | | Cloud layer 3 height/coverage | code | 0 | 8009 | | Low cloud symbol | code | 0 | 9 | | Mid cloud symbol | code | 10 | 19 | | High cloud symbol | code | 20 | 29 | | Pressure Tendency | code | 0 | 8999 | | Quality check flag | code | -1 | 9 | | Precipitation storm | Millimeters | 0 | 3810 | | Snowfall | Millimeters | 0 | 3810 | | Precipitation 1hr | Millimeters | 0 | 254 | | Precipitation 3hr | Millimeters | 0 | 762 | | Precipitation 5min | Millimeters | 0 | 25.4 | | Precipitation 10min | Millimeters | 0 | 50.8 | | Precipitation 15min | Millimeters | 0 | 76.2 | | Road sensor number | | 1 | 10 | | Road Temperature | Celsius | -40 | 65.56 | | Road Freezing Temperature | Celsius | -17.78 | 4.44 | | Road Surface Conditions | code | 1 | 100 | | unknown | | 0 | 100 | | Cloud layer 1 height/coverage | code | 0 | 18009 | | Cloud layer 2 height/coverage | code | 0 | 8009 | | Precipitation 6hr | Millimeters | 0 | 762 | | Precipitation 24hr | Millimeters | 0 | 1143 | | Visibility | Statute miles | -0.25 | 200 | | Remarks | text | NULL | NULL | | Raw observation | text | NULL | NULL | | 6 Hr High Temperature | Celsius | -59.44 | 57.22 | | 6 Hr Low Temperature | Celsius | -59.44 | 57.22 | | Peak Wind Speed | m/s | 0 | 102.89 | | Fuel Temperature | Celsius | -40 | 60 | | Fuel Moisture | gm | 0 | 100 | | Ceiling | Meters | 0 | 12192 | | Pressure change | code | 0 | 2000 | | Precipitation smoothed | Millimeters | 0 | 7620 | | IR Soil Temperature | Celsius | -59.44 | 57.22 | | Temperature in case | Celsius | -59.44 | 57.22 | | Soil Moisture | % | 0 | 100 | | Battery voltage | volts | 0 | 50 | | Data Insert Date/Time | minutes | 0 | 16000000 | | Data Update Date/Time | minutes | 0 | 16000000 | | Snow smoothed | Millimeters | 0 | 12700 | | Precipitation manual | Millimeters | 0 | 3810 | | Precipitation 1hr manual | Millimeters | 0 | 254 | | Precipitation 3hr manual | Millimeters | 0 | 762 | | Precipitation 5min manual | Millimeters | 0 | 25.4 | | Precipitation 10min manual | Millimeters | 0 | 50.8 | | Precipitation 15min manual | Millimeters | 0 | 76.2 | | Precipitation 6hr manual | Millimeters | 0 | 762 | | Precipitation 24hr manual | Millimeters | 0 | 1143 | | Snow manual | Millimeters | 0 | 12700 | | Snow interval | Millimeters | 0 | 3810 | | Road Subsurface Temperature | Celsius | -40 | 65.56 | | Water Temperature | Celsius | -17.78 | 57.22 | | Evapotranspiration | Millimeters | 0 | 127 | | Snow water equivalent | Millimeters | 0 | 2540 | | Precipitation 30 min | Millimeters | 0 | 127 | | All variables | | NULL | NULL | | Precipitable water vapor | Millimeters | 0 | 127 | | 24 Hr High Temperature | Celsius | -59.44 | 57.22 | | 24 Hr Low Temperature | Celsius | -59.44 | 57.22 | | Peak Wind Direction | Degrees | 0 | 360 | | Precipitation (weighing gauge) | Millimeters | 0 | 3810 | | Net Radiation | W/m\*\*2 | -500 | 1000 | | 1500 m Pressure | Pascals | 70000 | 100000 | | Wet bulb temperature | Celsius | -59.44 | 57.22 | | Soil Moisture tension | centibars | 0 | 300 | | Air Temperature at 2 meters | Celsius | -59.44 | 57.22 | | Air Temperature at 10 meters | Celsius | -59.44 | 57.22 | | Precipitation 1min | Millimeters | 0 | 12.7 | | 18 Inch Soil Temperature | Celsius | -50 | 85 | | 20 Inch Soil Temperature | Celsius | -50 | 85 | | 18 Inch Soil Temperature2 | Celsius | -50 | 85 | | Pressure | Pascals | 60000 | 108000 | | Temperature | Celsius | -59.44 | 57.22 | | Relative Humidity | % | 0 | 100 | | Wind Speed | m/s | 0 | 102.89 | | Wind Direction | Degrees | 0 | 360 | | Wind Gust | m/s | 0 | 128.61 | | Latitude | Degrees | -90 | 90 | | Longitude | Degrees | -180 | 180 | | Elevation | Meters | -91.44 | 9144 | | Platform True Direction | Degrees | 0 | 360 | | Primary Swell Wave Direction | Degrees | 0 | 360 | | Primary Swell Wave Period | Seconds | 0 | 99 | | Primary Swell Wave Height | Meters | 0 | 10.25 | | Secondary Swell Wave Direction | Degrees | 0 | 360 | | Secondary Swell Wave Period | Seconds | 0 | 99 | | Secondary Swell Wave Height | Meters | 0 | 10.25 | | Tide Indicator | code | 0 | 10 | | Tide Departure | Meters | 0 | 30.48 | | Platform True Speed | m/s | 0 | 64.31 | | Wave Period | Seconds | 0 | 99 | | Wave Height | Meters | 0 | 33.63 | | Surface Temperature | Celsius | -50 | 85 | | Net Shortwave Radiation | W/m\*\*2 | -500 | 1000 | | Net Longwave Radiation | W/m\*\*2 | -500 | 1000 | | Sonic Temperature | Celsius | -59.44 | 57.22 | | Vertical Velocity | m/s | -2 | 2 | | Zonal Wind Standard Deviation | m/s | 0 | 5 | | Meridional Wind Standard Deviation | m/s | 0 | 5 | | Vertical Wind Standard Deviation | m/s | 0 | 5 | | Temperature Standard Deviation | Celsius | 0 | 5 | | Vertical Heat Flux | m/s C | -2 | 2 | | Friction Velocity | m/s | 0 | 5 | | SIGW/USTR | nondimensional | 0 | 5 | | Sonic Obs Total | nondimensional | 0 | 5000 | | Sonic Warnings | nondimensional | 0 | 5000 | | Moisture Standard Deviation | g/m\*\*3 | 0 | 5 | | Vertical Moisture Flux | m/s g/m\*\*3 | -1 | 1 | | Dew Point | Celsius | -59.44 | 57.22 | | Virtual Temperature | Celsius | -59.44 | 57.22 | | Geopotential Height | Meters | -300 | 30000 | | Sonic Wind Speed | m/s | 0 | 102.89 | | Sonic Wind Direction | Degrees | 0 | 360 | | Outgoing Shortwave Radiation | W/m\*\*2 | 0 | 1000 | | Clear Sky Solar Radiation | W/m\*\*2 | 0 | 1500 | | Estimated Snowfall Rate | Millimeters | 0 | NULL | | Grip 1 Ice Friction Code | | 0 | 1 | | Grip 2 Level of Grip | | 0 | 1 | | Soil Temperature 2 | Celsius | -50 | 85 | | Soil Moisture 2 | % | 0 | 100 | | Soil Temperature 3 | Celsius | -50 | 85 | | Soil Temperature 4 | Celsius | -50 | 85 | | Photosynthetically Active Radiation | umol/m\*\*2 s | 0 | 2500 | | PM 2.5 Concentration | ug/m3 | 0 | 1000000 | | Flow Rate | liters/min | -1000 | 10000 | | Internal Relative Humidity | % | 0 | 100 | | Air Flow Temperature | Celsius | -59.44 | 57.22 | | Ozone Concentration | ppb | 0 | 500 | | Precipitation since 00 UTC | Millimeters | 0 | 1143 | | Stream flow | ft3/s | 0 | 15000000 | | Gauge height | ft | NULL | NULL | | Black Carbon Concentration | ug/m3 | 0 | 200 | | Precipitation since local midnight | Millimeters | 0 | 1143 | | Particulate Concentration | ug/m3 | 0 | 10000 | | Filter Percentage | % | 0 | 100 | | Sensor Error Code | code | 0 | 1000 | | Electric Conductivity | dS/m | 0 | 10 | | Permittivity | | 0 | 100 | | Precipitation since 7 AM local | Millimeters | 0 | 1219.2 | | Snow 24hr | Millimeters | 0 | 12700 | | Snow since 7 AM local | Millimeters | 0 | 12700 | | Past weather | code | 0 | 9 | | Precipitation 12hr | Millimeters | 0 | 609.6 | | METAR Origin | code | 0 | 1 | | Surface Level | Millimeters | -2540 | 2540 | | Incoming Longwave Radiation | W/m\*\*2 | 0 | 1500 | | Outgoing Longwave Radiation | W/m\*\*2 | 0 | 1500 | | Derived Aerosol Boundary Layer Depth | Meters | 0 | 12192 | | Precipitation Rate | Millimeters/hr | 0 | 10 | | Carbon Monoxide Concentration | ppm | -10 | 1000000 | | Ammonia Concentration | ppb | -10 | 1000000 | | NOx-Computed Nitrogen Dioxide Concentration | ppb | -10 | 1000000 | | NOy-Computed Nitrogen Dioxide Concentration | ppb | -10 | 1000000 | | Nitric Oxide Concentration | ppb | -10 | 1000000 | | Nitrogen Oxides Concentration | ppb | -10 | 1000000 | | Total Reactive Nitrogen Concentration | ppb | -10 | 1000000 | | PM 10 Concentration | ug/m3 | 0 | 1000000 | | Sulfur Dioxide Concentration | ppb | -10 | 1000000 | | 370nm Aethelometer Channel | ug/m3 | -10 | 1000000 | | Precipitation Interval | Millimeters | 0 | NULL | | Snow Core Water Equivalent | Millimeters | 0 | NULL | | Fosberg Fire Weather Index | | 0 | 100 | | Visibility Code | | NULL | NULL | | Incoming UV Radiation | W/m\*\*2 | 0 | 500 | | Outgoing UV Radiation | W/m\*\*2 | 0 | 500 | | Water Current Speed | m/s | 0 | 5.14 | | Water Current Direction | Degrees | 0 | 360 | | Mean Tide Level | Meters | -20 | 20 | | Mean Sea Level | Meters | -20 | 20 | | Mean Lower Low Water | Meters | -20 | 20 | | Mean Low Water | Meters | -20 | 20 | | Mean High Water | Meters | -20 | 20 | | Mean Higher High Water | Meters | -20 | 20 | | Columbia River Datum | Meters | -20 | 20 | | International Great Lakes Datum | Meters | -20 | 20 | | Great Lakes Low Water Datum | Meters | -20 | 20 | | North American Vertical Datum | Meters | -20 | 20 | | Station Datum | Meters | -20 | 20 | | Raw SYNOP Message | text | NULL | NULL | | Total Solar Radiation | MJ/m\*\*2 | NULL | NULL | | Wet Bulb Globe Temperature | Celsius | -59.44 | 65.56 | | Electric Field Alarm Rate | | NULL | NULL | | Lightning Strike Count | | NULL | NULL | | Freezing Rain Status Signal | code | NULL | NULL | | Freezing Rain Ice Signal | code | NULL | NULL | | Wind Gust Time | epoch | NULL | NULL | | SYNOP Weather Condition | code | NULL | NULL | | Wind Chill | Celsius | -113.8 | 9.8 | | Heat Index | Celsius | 25.4 | 310.4 | | Tide Water Level | Meters | NULL | NULL | | Water Electrical Conductivity | mS/cm | NULL | NULL | | Water Salinity | psu | NULL | NULL | | Water Oxygen Saturation | % | 0 | 100 | | Water Dissolved Oxygen | ppm | NULL | NULL | | Water Chlorophyll Concentration | ug/l | NULL | NULL | | Water Turbidity | FTU | NULL | NULL | | Water pH | | NULL | NULL | | Water Eh | millivolts | NULL | NULL | | Water Column Height | Meters | NULL | NULL | | Dominant Wave Period | Seconds | NULL | NULL | | Mean Wave Direction | Degrees | NULL | NULL | | Low Cloud Type | code | 0 | 20 | | Mid Cloud Type | code | 0 | 20 | | High Cloud Type | code | 0 | 20 | | Total Cloud Coverage | Oktas | 0 | 8 | | Low Cloud Coverage | Oktas | 0 | 8 | | Mid Cloud Coverage | Oktas | 0 | 8 | | High Cloud Coverage | Oktas | 0 | 8 | | Minutes of Sunshine | Minutes | 0 | 60 | | Diffuse Radiation | W/m\*\*2 | 0 | 1200 | | Cloud Drift Direction Low | Degrees | 0 | 360 | | Cloud Drift Direction Mid | Degrees | 0 | 360 | | Cloud Drift Direction High | Degrees | 0 | 360 | | Change in Pressure | Pascals | -1000000 | 1000000 | | Water Level | Meters | -20 | 20 | | Groundwater Level | Meters | -20 | 50 | | Fluorescent Dissolved Organic Matter | RFU | 0 | 200 | | Blue-Green Algae | RFU | 0 | 100 | | Water Ammonium Concentration | mg/L | 0 | 5 | | Water Nitrate Concentration | mg/L | 0 | 50 | | Maximum wave height | m | 0 | 40 | | Oxidation reduction potential | mV | -600 | 600 | | UV Index | Index | 0 | 15 | | Air Quality Index Raw | | NULL | NULL | | Air Quality Index US | Index | 0 | 500 | | Air Quality Index EU | Index | 0 | 6 | | Grass Minimum Temperature | Celsius | -59.44 | 57.22 | | Leaf Wetness | NULL | NULL | NULL | | CFFDRS Fine Fuel Moisture Code | code | 0 | 101 | | CFFDRS Drought Code | code | 0 | 1500 | | CFFDRS Duff Moisture Code | code | 0 | 300 | | CFFDRS Fire Weather Index | Index | 0 | 100 | | CFFDRS Initial Spread Index | Index | 0 | 50 | | CFFDRS Drought Severity Rating | Index | 0 | 6 | | CFFDRS Build Up Index | Index | 0 | 200 | | Fire Danger Code Category | text | NULL | NULL | | Fire Danger Code Numeric | code | 1 | 5 | ### Rate of change check > Is the change between two consecutive values unrealistic? **API Name** : `sl_rate_check` The rate change check compares the absolute difference between two consecutive observations to the maximum plausible rate of change expected within the time interval. | Variable name | Unit | Rules | |--------------------|---------|---------------------------------------------------------------| | Pressure Altimeter | Pascals | 5 min: 925 15 min: 1000 30 min: 1500 60 min: 1500 | | Temperature | Celsius | 1-3 min: 3 4 min: 4 5 min: 5 15 min 7.5 30 min: 15 60 min: 20 | ### Persistence check > Do the values appear to be unchanging? #### `sl_pers_check` For parameters for which it is appropriate to do so, the persistence check compares the range of values (difference between the maximum and minimum) within a specified time period relative to the minimum plausible range expected for that parameter. The following table lists the variable, time period evaluated, and the minimum plausible range expected for that variable.. | Variable name | Unit | Evaluation period | Min number of obs | Required change | |-------------------------------------|---------------|-------------------|-------------------|-----------------| | Altimeter | Pascals | 24 hrs | 24 | 5.0 | | Pressure | Pascals | 24 hrs | 24 | 5.0 | | Temperature | Celsius | 24 hrs | 24 | 0.1 | | Dew Point | Celsius | 24 hrs | 24 | 0.1 | | Relative Humidity | % | 24 hrs | 24 | 0.5 | | Wind Speed | m/s | 24 hrs | 24 | 0.25 | | Wind Direction | Degrees | 24 hrs | 24 | 2.5 | | Wind Gust | m/s | 24 hrs | 24 | 0.25 | | Solar Radiation | W/m\*\*2 | 48 hrs | 48 | 0.5 | | Soil Temperature | Celsius | 48 hrs | 48 | 0.05 | | Sea_level pressure | Pascals | 24 hrs | 24 | 5.0 | | Water Temperature | Celsius | 48 hrs | 48 | 0.05 | | Road Temperature | Celsius | 24 hrs | 24 | 0.1 | | Sonic_Wind Direction | Degrees | 24 hrs | 24 | 1.0 | | Peak_Wind Speed | m/s | 24 hrs | 24 | 0.25 | | Fuel Temperature | Celsius | 72 hrs | 72 | 0.1 | | Fuel Moisture | gm | 24 hrs | 24 | 0.1 | | Sonic_Wind Speed | m/s | 24 hrs | 24 | 0.1 | | IR_Soil Temperature | Celsius | 24 hrs | 24 | 0.1 | | Road Subsurface Temperature | Celsius | 48 hrs | 48 | 0.05 | | Water Temperature | Celsius | 48 hrs | 48 | 0.05 | | Peak_Wind Direction | Degrees | 24 hrs | 24 | 2.5 | | Net Radiation | W/m\*\*2 | 48 hrs | 48 | 0.5 | | Air_Temperature at_2_meters | Celsius | 24 hrs | 24 | 0.1 | | Air_Temperature at_10_meters | Celsius | 24 hrs | 24 | 0.1 | | Pressure | Pascals | 24 hrs | 24 | 5.0 | | Temperature | Celsius | 24 hrs | 24 | 0.1 | | Relative Humidity | % | 24 hrs | 24 | 0.5 | | Wind Speed | m/s | 24 hrs | 24 | 0.25 | | Wind Direction | Degrees | 24 hrs | 24 | 2.5 | | Wind Gust | m/s | 24 hrs | 24 | 2.5 | | Surface Temperature | Celsius | 24 hrs | 24 | 0.1 | | Net Shortwave Radiation | W/m\*\*2 | 48 hrs | 48 | 0.5 | | Net Longwave Radiation | W/m\*\*2 | 48 hrs | 48 | 0.5 | | Sonic Temperature | Celsius | 24 hrs | 24 | 0.1 | | Dew Point | Celsius | 24 hrs | 24 | 0.1 | | Virtual Temperature | Celsius | 24 hrs | 24 | 0.1 | | Outgoing Shortwave Radiation | W/m\*\*2 | 48 hrs | 48 | 0.5 | | Photosynthetically Active Radiation | umol/m\*\*2 s | 48 hrs | 48 | 0.5 | | PM_2.5 Concentration | ug/m3 | 24 hrs | 24 | 0.5 | | Ozone Concentration | ppb | 24 hrs | 24 | 0.5 | | Black Carbon Concentration | ug/m3 | 24 hrs | 24 | 0.5 | | Particulate Concentration | ug/m3 | 24 hrs | 24 | 0.5 | ### Wind speed vs. maximum gust check > Is the wind speed value greater than the wind gust value? **API Name** : `sl_windspd_maxgust_check` If the reported wind speed is greater than the wind gust, both the wind speed and gust values are flagged. Note: the conventions for reporting wind speed and gust differ among data providers. The wind gust reported may be a maximum wind speed within the time interval for that observation. ### Wind gust factor check > Is the ratio of wind gust to wind speed unrealistic? **API Name** : `sl_wind_gust_factor_check` If the ratio of wind gust to wind speed exceeds a threshold value, wind gust is flagged. If wind gust and wind speed are the same (ratio of 1), or if wind speed is zero with a non-zero gust, both wind speed and gust are flagged. Wind gusts must exceed 31.3 m/s (70 mph) to be considered by this check. The outlier threshold is defined with a power-law curve, derived from large data samples of wind speed and gust. ### Secondary range check **API Name** : `sl_secondary_range_check` This check is used to "cross-flag" between wind speed and wind gust, as these variables are usually reported from the same sensor. If wind speed (or gust) is out-of-range, then apply the secondary range check to wind gust (or speed). ### Secondary persistence check **API Name** : `sl_secondary_pers_check` This check is used to "cross-flag" between wind speed and wind gust, as these variables are usually reported from the same sensor. If wind speed (or gust) is persisting, then apply the secondary persistence check to wind gust (or speed). ### Soil moisture freezing check **API Name** : `sl_soil_moisture_freezing_check` Flag soil moisture when soil temp is \< 0Β°C. ### Sensor status signal check **API Name** : `sl_sensor_status_signal_check` Indicates bad sensor status, from provider-sourced status signal. Synoptic can ingest sensor health status signal as a variable, and then use this to flag the corresponding data from the sensor. ### Snow Depth History Check > Is the current snow depth observation an outlier compared to the median of the multi-day snow depth history? **API Name** : `sl_snow_depth_hist_check` Compares the current snow depth observation against a median of multi-day history (e.g. 3 days). Outliers are flagged that can commonly result from sonic snow depth sensors. ### Percentile high outlier check > Is the value a high outlier compared to the percentile distribution of the station's historical record? **API Name** : `sl_percentile_hioutlier_check` This flag is applied to air temperature values if: **value \> (99.5th percentile + 10Β°C)** Synoptic Data completes yearly re-analysis of the historical record of air temperature data for every station in our database. A series of outlier identification algorithms are run to identify and remove obvious outliers in the historical record. Using this "cleaned" record, we then leverage the percentile distribution of the data to compare to current observations. To be used in this check, a station must have at least 3 years of continuous air temperature data. This check is intended to identify values that are very likely to be erroneous (significantly beyond any historically high or low temperatures) for the date and hour of the observation. We use extreme air temperature events to calibrate the threshold, with the intention that flagged data is likely unrealistic and can be removed from an API request. ### Percentile low outlier check > Is the value a low outlier compared to the percentile distribution of the station's historical record? **API Name** : `sl_percentile_looutlier_check` This flag is applied to air temperature values if: **value \< (0.5th percentile - 15Β°C)** See technical details for the percentile outlier checks as described above for the percentile high outlier check. ### Percentile high flag check > Is the value near or above historical high values compared to the percentile distribution of the station's historical record? **API Name** : `sl_percentile_hiflag_check` This flag is applied to air temperature values if: **99.5th percentile \< value \< (99.5th percentile + 10Β°C)** The percentile high flag is intended to indicate air temperature data that may be near or above historical maximum temperatures for the date and hour of the observation. These flags should not be used to remove data from an API request, but instead may be used to indicate "interesting" or historically significant observations. **This check is not included in the** `synopticlabs` test suite. ### Percentile low flag check > Is the value near or below historical low values compared to the percentile distribution of the station's historical record? **API Name** : `sl_percentile_loflag_check` This flag is applied to air temperature values if: **(0.5th percentile - 15Β°C) \< value \< 0.5th percentile** The percentile low flag is intended to indicate air temperature data that may be near or below historical minimum temperatures for the date and hour of the observation. These flags should not be used to remove data from an API request, but instead may be used to indicate "interesting" or historically significant observations. **This check is not included in the** `synopticlabs` test suite. ### Spatial value check > Is the value significantly different than neighboring observations? **API Name** : `sl_spatial_value_check` This flag is applied to multiple variables according to thresholds defined in the following table. **Value thresholds** indicate the threshold for flagging the current value, as: *abs(value - median( neighbor values) \>= threshold* . **Neighbor thresholds** indicate the threshold for agreement between neighbor values, as: *(max(neighbor values) - min(neighbor values)) \<= threshold*. Thresholds are not provided for pressure or relative humidity, as these variables are flagged via derived altimeter and derived dew point temperature, respectively. | Variable | Unit | Value threshold | Neighbors threshold | |-----------------------|---------|------------------------|---------------------| | Altimeter | Pascals | 3000 | 3000 | | Pressure | Pascals | (flagged by altimeter) | -- | | Air Temperature | Celsius | 10 | 15 | | Dew Point Temperature | Celsius | 15 | 15 | | Relative Humidity | % | (flagged by dew point) | -- | | Wind Speed | m/s | 20 | 15 | | Wind Gust | m/s | 40 | 20 | To run this check there must be at least two neighboring stations that meet the following requirements: * Within 30 km distance and 200 meters elevation * Closest-in-time values are within -1.5 hrs and +0.5 hrs of the current value * Cannot have any open QC flags ### Linear regression check **API Name** : `mw_multvariate_lin_reg_check` A multivariate linear regression check courtesy of the University of Utah MesoWest program. This check identifies air temperature, moisture, and pressure observations that appear to be significantly different than surrounding observations. More information on this check can be obtained [here](https://mesowest.utah.edu/html/help/regress.html). ### 24-hr wind persistence check **API Name** : `mw_24h_wind_persistence_check` Persistence check to identify unchanging wind speed values, courtesy of the University of Utah MesoWest program. This check is redundant to the `sl_pers_check`. ### UU2DVAR rejection check **API Name** : `mw_uu2dvar_rejection` A spatial comparison check with surrounding observations and gridded surface meteorological fields courtesy of the University of Utah Variational Surface Analysis (UU2DVAR). Observations that have been flagged by this check indicate they were statistically rejected from the UU2DVAR algorithm. For more information on UU2DVAR, please consult [this publication](https://journals.ametsoc.org/doi/full/10.1175/WAF-D-12-00027.1). --- language: "en" --- # Metadata Returns metadata (information about stations) for a station or set of stations ## Request Format A Metadata request is an HTTP URL with the following form: https://api.synopticdata.com/v2/stations/metadata 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](https://docs.synopticdata.com/account/public-api-tokens.md). * 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. Station Selection Parameters These selectors individually or combined to target the desired stations. **Exclusion Operator** Selectors noted as *(excludable)* may be specified with a `!` preceding a value to remove/exclude from the selection from a result set. So `stid=!KSLC` would prevent KSLC from returning in a query. This should be used in combination with different selectors. Remember to only include any given selector once. `stid` (string, *excludable* ), Single or comma separated list of SynopticLabs station IDs. Use a `!` before any value to exclude matching stations. Example: `stid=mtmet,kslc,fps`. Try it Now `state` (string, *excludable* ), Single or comma separated list of abbreviated 2 character states. If country is not included, default is United States (`US`). Use a `!` before any value to exclude matching stations. Example: `state=ut,wy,dc`. `country` (string, *excludable* ), Single or comma separated list of abbreviated 2 or 3 character countries. Use a `!` before any value to exclude matching stations. Example: `country=us,ca,mx`. `nwszone` (string, *excludable* ), Single or comma separated list of National Weather Service Zones. Use a `!` before any value to exclude matching stations. Example: `nwszone=UT003,CA041`. `nwsfirezone` (string, *excludable* ), Single or comma separated list of National Weather Service Fire Zones. Use a `!` before any value to exclude matching stations. Example: `nwsfirezone=LOX241` `cwa` (string, *excludable* ), Single or comma separated list of National Weather Service County Warning Areas. Use a `!` before any value to exclude matching stations. Example: `cwa=LOX`. `gacc` (string, *excludable* ), Single or comma separated list of Geographic Area Coordination Centers. Use a `!` before any value to exclude matching stations. Example: `gacc=GB`. `subgacc` (string, *excludable* ), Single or comma separated list of Sub Geographic Area Coordination Centers. Use a `!` before any value to exclude matching stations. Example: `subgacc=EB07`. `county` (string, *excludable* ), Single or comma separated list of counties. Use the `state` parameter to filter by state in the case of duplicate county names (i.e. "King"). Use a `!` before any value to exclude matching stations. Example: `county=king&state=wa`. `vars` (string), Single or comma separated list of sensor variables [found here](https://docs.synopticdata.com/services/station-variables.md). 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. *Some web services use this argument to adjust what information is delivered.* Example: `vars=wind_speed,pressure`. Try it Now `varsoperator` (string), Define how `&vars` is understood. `or` (the default) means any station with any variable in the list is used. `and` means a station must report every variable to be included. Example: `varsoperator=and`. `network` (number, string, *excludable* ), Single or comma separated list of network IDs or short names. The ID can be found be using the [Networks](https://docs.synopticdata.com/services/networks.md) service and are also listed [here](https://docs.synopticdata.com/services/station-networks-providers.md). Use a `!` before any value to exclude specific networks from a result set. Example: `network=153` or `network=44,251`. `radius` (string), 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 with units of miles. Adding `limit=n` to the query will limit the number of returned stations to **n** stations, and will order the stations by `DISTANCE`. Some examples are: `radius=41.5,-120.25,20`, `radius=wbb,10`, `radius=41.5,-120.25,20&limit=10`. `bbox` (string), 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`. **Bounding Box Thinning** A new feature allows you to use the API to thin the returned station set within a bounding box by providing some additional arguments. These arguments only take effect when the `bbox` parameter is used: `height` (number) the height of the map viewport in pixels `width` (number) the width of the map viewport in pixels `spacing` (number) the preferred number of pixels a station on the map should consume `networkimportance` (numbers, comma-separated) a list of comma separated network IDs that will be considered in the order provided. When there is a collision of stations within the defined "spacing" area, any station matching the list of preferred networks will be shown over any other. `status` (string), A value of either active or inactive returns only stations that are currently set as active in the archive. Stations are set to active if they have reported an observation in the last 30 days. By default, omitting this parameter will return all stations. Example: `status=active`. **Optional Parameters** * `complete` (0 \[default\], 1), Indicates if the complete metadata for the station will be returned. By default only the most common metadata values are returned. * `sensorvars` (0 \[default\], 1), Indicates if the stations sensor information will be returned. If true, then the response will contain a complete list of all the sensors the station has ever owned, regardless if they are currently active. Each sensor element contains a `PERIOD_OF_RECORD` value that describes the period of the sensor being active. * `obrange` (start, end), Used to return station metadata for a specific period defined with start and end times. Accepted time format is **YYYYmmddHHMM** where *YYYY* is year, *mm* is month, *dd* is day, *HH* is hour and *MM* is minute (**YYYYmmdd** is also accepted). The `start` parameter must be used with the `end` parameter. For example: `obrange=20130601,20130602`. If no `end` is provided the response will contain all the stations returned from `start` until the current time. * `pedon` (0 \[default\], 1), Includes a `PEDON` key in the response for each station object, with a list of objects representing pedon soil analysis reports. By default, only the most recent pedon report is returned. * `pedonhistory` (0 \[default\], 1), Will return all historical pedon reports available for each station, as a list within the `PEDON` key. * `sitinghistory` (0 \[default\], 1), Will return all historical siting metadata for each station, as a list within the `SITING` key (requires `complete=1` to be enabled). Example: `sitinghistory=1`. * `fields` (string), Case-insensitive comma-separated list of metadata attributes to include in the output response. Default is to include all attributes. Only works with attributes defined in the default metadata set (e.g. attributes shown via `complete=1` cannot be selected). Example: `fields=stid,name`. **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](https://en.wikipedia.org/wiki/ISO_8601) format. This behavior can be changed by passing a string with a valid [strftime](https://strftime.org/) 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](https://en.wikipedia.org/wiki/Unix_time) time in terms of seconds (this parameter cannot be used with `obtimezone`). This is a special function in addition to the supported [strftime](https://strftime.org/) arguments. * `output` (json \[default\], xml, geojson), Indicates the response format of the request. It's recommended to use the [JSON](https://json.org/) format which there are well supported parsing libraries in all major languages. ## Request Response **JSON Format** The Metadata 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: JSON { 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: { wind_speed: { wind_speed_1: { position: "42.0", PERIOD_OF_RECORD: { start: "1997-01-01T00:00:00Z", end: "2023-07-31T17:55:00Z" } } }, ... }, ELEV_DEM: "4727.7", LONGITUDE: "-111.84755", UNITS: { position: "m", elevation: "ft" }, STATE: "UT", RESTRICTED: false, LATITUDE: "40.76623", TIMEZONE: "America/Denver", ID: "1" } ], SUMMARY: { NUMBER_OF_OBJECTS: 1, RESPONSE_CODE: 1, VERSION: "v2.21.0", RESPONSE_MESSAGE: "OK", METADATA_RESPONSE_TIME: "16.7059898376 ms" } } * `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. * `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. --- language: "en" --- # Nearest Time Returns the observation closest to the time requested. Requests to the Nearest Time service are limited to 100,000 station-hours. See [Request Volume Limitations](https://docs.synopticdata.com/services/api-performance-and-limits.md#Request-Volume-Limitations) for more info. ## Request Format A Nearest Time request is an HTTP URL with the following form: https://api.synopticdata.com/v2/stations/nearesttime 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](https://docs.synopticdata.com/account/public-api-tokens.md). * `attime`, The date and time of the closest observation to be returned. In the form of **YYYYmmddHHMM** Where *YYYY* is year, *mm* is month, *dd* is day, *HH* is hour, and *MM* is minutes. For example: `attime=201306011800`. All times are requested in UTC, but may be returned in either UTC or local time format for each station. See the `obtimezone` parameter. * `within` (*required* if `attime` is defined), Restricts the response to observations in a time window previous to `attime` (in minutes), or previous to the current time (if `attime` is not defined), i.e. `within=60` would return only observations within the last 60 minutes. Note that if `attime` and `within` are not included in a `nearesttime` request, the request behaves as a `latest` request. We recommend using the [Latest service](https://docs.synopticdata.com/services/latest.md) for these request patterns. **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. Station Selection Parameters These selectors individually or combined to target the desired stations. **Exclusion Operator** Selectors noted as *(excludable)* may be specified with a `!` preceding a value to remove/exclude from the selection from a result set. So `stid=!KSLC` would prevent KSLC from returning in a query. This should be used in combination with different selectors. Remember to only include any given selector once. `stid` (string, *excludable* ), Single or comma separated list of SynopticLabs station IDs. Use a `!` before any value to exclude matching stations. Example: `stid=mtmet,kslc,fps`. Try it Now `state` (string, *excludable* ), Single or comma separated list of abbreviated 2 character states. If country is not included, default is United States (`US`). Use a `!` before any value to exclude matching stations. Example: `state=ut,wy,dc`. `country` (string, *excludable* ), Single or comma separated list of abbreviated 2 or 3 character countries. Use a `!` before any value to exclude matching stations. Example: `country=us,ca,mx`. `nwszone` (string, *excludable* ), Single or comma separated list of National Weather Service Zones. Use a `!` before any value to exclude matching stations. Example: `nwszone=UT003,CA041`. `nwsfirezone` (string, *excludable* ), Single or comma separated list of National Weather Service Fire Zones. Use a `!` before any value to exclude matching stations. Example: `nwsfirezone=LOX241` `cwa` (string, *excludable* ), Single or comma separated list of National Weather Service County Warning Areas. Use a `!` before any value to exclude matching stations. Example: `cwa=LOX`. `gacc` (string, *excludable* ), Single or comma separated list of Geographic Area Coordination Centers. Use a `!` before any value to exclude matching stations. Example: `gacc=GB`. `subgacc` (string, *excludable* ), Single or comma separated list of Sub Geographic Area Coordination Centers. Use a `!` before any value to exclude matching stations. Example: `subgacc=EB07`. `county` (string, *excludable* ), Single or comma separated list of counties. Use the `state` parameter to filter by state in the case of duplicate county names (i.e. "King"). Use a `!` before any value to exclude matching stations. Example: `county=king&state=wa`. `vars` (string), Single or comma separated list of sensor variables [found here](https://docs.synopticdata.com/services/station-variables.md). 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. *Some web services use this argument to adjust what information is delivered.* Example: `vars=wind_speed,pressure`. Try it Now `varsoperator` (string), Define how `&vars` is understood. `or` (the default) means any station with any variable in the list is used. `and` means a station must report every variable to be included. Example: `varsoperator=and`. `network` (number, string, *excludable* ), Single or comma separated list of network IDs or short names. The ID can be found be using the [Networks](https://docs.synopticdata.com/services/networks.md) service and are also listed [here](https://docs.synopticdata.com/services/station-networks-providers.md). Use a `!` before any value to exclude specific networks from a result set. Example: `network=153` or `network=44,251`. `radius` (string), 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 with units of miles. Adding `limit=n` to the query will limit the number of returned stations to **n** stations, and will order the stations by `DISTANCE`. Some examples are: `radius=41.5,-120.25,20`, `radius=wbb,10`, `radius=41.5,-120.25,20&limit=10`. `bbox` (string), 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`. **Bounding Box Thinning** A new feature allows you to use the API to thin the returned station set within a bounding box by providing some additional arguments. These arguments only take effect when the `bbox` parameter is used: `height` (number) the height of the map viewport in pixels `width` (number) the width of the map viewport in pixels `spacing` (number) the preferred number of pixels a station on the map should consume `networkimportance` (numbers, comma-separated) a list of comma separated network IDs that will be considered in the order provided. When there is a collision of stations within the defined "spacing" area, any station matching the list of preferred networks will be shown over any other. `status` (string), A value of either active or inactive returns only stations that are currently set as active in the archive. Stations are set to active if they have reported an observation in the last 30 days. By default, omitting this parameter will return all stations. Example: `status=active`. * `complete` (0 \[default\], 1), 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. Example: `complete=1`. * `fields` (string), Case-insensitive comma-separated list of metadata attributes to include in the output response. Default is to include all attributes. Only works with attributes defined in the default metadata set (e.g. attributes shown via `complete=1` cannot be selected). Example: `fields=stid,name`. * `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` * `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. * `fuel_moisture` (gm, %), Fuel Moisture: Grams, %. 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`. * `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. * `sitinghistory` (0 \[default\], 1), Will return all historical siting metadata for each station, as a list within the `SITING` key (requires `complete=1` to be enabled). Example: `sitinghistory=1`. * `value_percentile` (complete, daily_min, daily_max), Returns the nearest percentile for the observed value. Only available for air temperature, wind speed or wind gust. `complete`, `daily_min` or `daily_max` determine which percentile dataset is used. * `complete` uses a percentile distribution derived from all observations in the full period-of-record for each station and variable. * `daily_min` and `daily_max` use a percentile distribution derived from all daily minimum or maximum values spanning the full period-of-record for each station and variable. These are timezone-specific, and will respect the `obtimezone` argument. **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](https://en.wikipedia.org/wiki/ISO_8601) format. This behavior can be changed by passing a string with a valid [strftime](https://strftime.org/) 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](https://en.wikipedia.org/wiki/Unix_time) time in terms of seconds (this parameter cannot be used with `obtimezone`). This is a special function in addition to the supported [strftime](https://strftime.org/) arguments. * `output` (json \[default\], xml, geojson), Indicates the response format of the request. It's recommended to use the [JSON](https://json.org/) format which there are well supported parsing libraries in all major languages. * 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](https://docs.synopticdata.com/services/mesonet-data-qc.md), 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](https://docs.synopticdata.com/services/mesonet-data-qc.md) 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`. `all` is equivalent to `qc_checks=synopticlabs`, and only applies the Synoptic basic+advanced QC suite. [++Click here++](https://docs.synopticdata.com/services/mesonet-data-qc.md) to read more about the basic and advanced groups. 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 Nearest Time 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: JSON { UNITS: { wind_speed: "m/s" }, 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-08-01T23:20:00Z" }, ELEVATION: "4226", NAME: "Salt Lake City, Salt Lake City International Airport", STID: "KSLC", SENSOR_VARIABLES: { wind_speed: { } }, ELEV_DEM: "4235.6", LONGITUDE: "-111.96503", UNITS: { position: "m", elevation: "ft" }, STATE: "UT", OBSERVATIONS: { wind_speed_value_1: { date_time: "2023-01-01T00:00:00Z", value: 2.572 } }, RESTRICTED: false, QC_FLAGGED: false, LATITUDE: "40.77069", TIMEZONE: "America/Denver", ID: "53" } ], SUMMARY: { DATA_QUERY_TIME: "44.5201396942 ms", RESPONSE_CODE: 1, RESPONSE_MESSAGE: "OK", METADATA_RESPONSE_TIME: "92.4820899963 ms", DATA_PARSING_TIME: "166.312932968 ms", VERSION: "v2.21.0", TOTAL_DATA_TIME: "210.834026337 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. --- language: "en" --- # Network Types Returns network category metadata ## Request Format https://api.synopticdata.com/v2/networktypes Returns a list of network types. You can also see a list of them [here](https://docs.synopticdata.com/services/network-types-table.md). 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](https://docs.synopticdata.com/account/public-api-tokens.md). **Optional Parameters** * `id`, An internal SynopticLabs ID number for the network type. Example: `id=1,2,3` **Response Format Parameters** * `output` (json \[default\], xml), Indicates the response format of the request. It's recommended to use the [JSON](https://json.org/) format which there are well supported parsing libraries in all major languages. ## Request Response **JSON Format** The QC Types 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: JSON { MNETCAT: [ { PERIOD_OF_RECORD: { start: "1997-01-01T00:00:00Z", end: "2023-07-31T17:55:00Z" }, DESCRIPTION: "Agricultural", ID: "1", NAME: "AG" }, ... ], SUMMARY: { DATA_PARSING_TIME: "0.00119209289551 ms", VERSION: "v2.21.0", TOTAL_DATA_TIME: "25.0599384308 ms", NUMBER_OF_OBJECTS: 14, RESPONSE_CODE: 1, RESPONSE_MESSAGE: "OK", METADATA_RESPONSE_TIME: "0.0250558853149 ms" } } * `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`. * `MNETCAT[]` * `DESCRIPTION`, description of network. * `NAME`, short name of network type. * `ID`, network type ID. * `PERIOD_OF_RECORD`, furthest extent of reporting history across all networks of the type. --- language: "en" --- # Network Types Table Network types categorize the general application or purpose of a network of stations. The values in the `ID` column can be used when identifying networks/providers. | ID | Description | Name | |------|----------------------------|---------------| | `1` | Agricultural | AG | | `2` | Air Quality | AQ | | `3` | Offshore, CA, MX | EXT | | `4` | Federal and state networks | FED+ | | `5` | Hydrological | HYDRO | | `6` | State and Local | LOCAL | | `7` | NWS/FAA | NWS | | `8` | CWOP | PUBLIC | | `9` | Fire weather | RAWS | | `10` | Road and rail weather | TRANS | | `11` | Public Utility | UTILITY | | `12` | Research and Education | RESEARCH | | `13` | Commercial | COMMERCIAL | | `14` | International | INTERNATIONAL | --- language: "en" --- # Networks Returns metadata and analytics for the networks available through the Weather API. ## Request Format https://api.synopticdata.com/v2/networks Returns a list of networks both current and previous that have data within the Weather API dataset. You can also explore networks [here](https://docs.synopticdata.com/services/station-networks-providers.md). *This service returns basic information regarding restricted networks. Meaning you may see networks that will require an upgraded service account to access.* 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](https://docs.synopticdata.com/account/public-api-tokens.md). **Optional Parameters** * `id` (network id), Single or comma separated list of network IDs. Example: `&id=1,2,3,4`. * `shortname` (network short name) Single or comma separated list of network short names. Example: `&shortname=uunet,raws`. * `sortby` (alphabet) Only valid value is alphabet for determining the sorting order. By default networks are sorted by ID. Example: `&sortby=alphabet`. **Response Format Parameters** * `output` (json \[default\], xml), Indicates the response format of the request. It's recommended to use the [JSON](https://json.org/) format which there are well supported parsing libraries in all major languages. ## Request Response **JSON Format** The Network 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: JSON { 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" } ], SUMMARY: { DATA_PARSING_TIME: "0.00190734863281 ms", VERSION: "v2.21.0", TOTAL_DATA_TIME: "58.0790042877 ms", NUMBER_OF_OBJECTS: 1, RESPONSE_CODE: 1, RESPONSE_MESSAGE: "OK", METADATA_RESPONSE_TIME: "0.0580739974976 ms" } } * `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`. * `MNET[]` * `CATEGORY`, network type. See [Network Types service](https://docs.synopticdata.com/services/network-types.md) for details * `REPORTING_STATIONS`, number of stations currently reporting in this network. Interval is defined below. * `LAST_OBSERVATION`, time stamp of last observation seen. * `URL`, network/data provider's URL, if available. * `PERCENT_REPORTING`, percentage of active stations currently reporting data. * `PERIOD_CHECKED`, the interval of time used to calculate analytics. In minutes. * `TOTAL_STATIONS`, total number of stations assigned to this network. * `ACTIVE_STATIONS`: number of stations currently set to active status. * `LONGNAME`, formal name of network. * `SHORTNAME`, short name of network. This can be used to with the `network` selector. * `PERCENT_ACTIVE`, percentage of active stations compared to the total number of stations assigned to this network. * `ID`, network ID number. This can be used to with the `network` selector. * `TOTAL_RESTRICTED`, number of stations in the network whose data may be restricted for public distribution * `ACTIVE_RESTRICTED`, number of those restricted stations which are active --- language: "en" --- # Opt-in public datasets Synoptic aggregates and distributes earth observation data shared with us from hundreds of global partners. Many of these partners share data with us publicly, which means it is automatically available for any customer within their service boundaries (e.g. spatial and archive access). Some of the public datasets we aggregate are more complex for use, such as high spatial density with very low observation frequency. These datasets complicate how the data are used, and as a result we do not include them by default in your data requests. These datasets remain fully available as all public data from Synoptic, but you will need to ask us to include them in your responses before you can use them. ## Exploring opt-in datasets Synoptic public data viewer applications contain all datasets, including opt-in, so you can use those to explore the data available. Using this insight you can make a careful decision about whether accessing a given opt-in public dataset is in the interest of your data application. Opt-in networks are not visible in availability applications, and may not be available for data download. You can [contact us](https://synopticdata.com/contact-us) if you have questions about a dataset not being available in a public data application. ## How to request access If you evaluate the available opt-in datasets and would like access to one or more, simply [contact us](https://synopticdata.com/contact-us)requesting the dataset you wish to access. ## Available opt-in datasets Click the dataset name to learn more about it, and why it is available as opt-in only. | **Name** | **Network ID** | **Spatial distribution** | **Description** | |-----------------------------|----------------|--------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | USGS-HYDRO | `203` | United States | Stream gauges, spatially dense hydrological dataset. | | COCORAHS | `262` | North America | Manual precipitation observations by individuals. Most reports are daily totals [https://explore.synopticdata.com/metadata/map/3560,-7623,2?network=262\&status=ACTIVE](https://explore.synopticdata.com/metadata/map/3560,-7623,2?network=262&status=ACTIVE) | | [SYNOP](https://docs.synopticdata.com/services/synop.md) | `284` | Global | Legacy dataset provided by countries around the globe. Resolution commonly 6 hourly, sometimes as high as 1 hour. | --- language: "en" --- # Percentiles Return percentile distributions for air temp, wind speed or wind gust. Percentiles are available for various distributions (depending on variable) such as full period-of-record, daily minimum or maximum, or hourly. Percentile distributions are updated monthly, and have Synoptic basic and advanced quality control applied. For an in-depth explanation of our percentiles computation, refer to [Statistics and Percentiles Services Explained](https://docs.synopticdata.com/services/statistics-and-percentiles-services-explained.md). Requests to the Percentiles service are limited to 50,000 stations, with a specific limit of 150,000 station-hours for `data=hourly`. See [Request Volume Limitations](https://docs.synopticdata.com/services/api-performance-and-limits.md#Request-Volume-Limitations) for more info. ## Request Format A Percentiles request is an HTTP URL with the following form: https://api.synopticdata.com/v2/stations/percentiles 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](https://docs.synopticdata.com/account/public-api-tokens.md). * At least one station selection parameter *(required):* Station Selection Parameters These selectors individually or combined to target the desired stations. **Exclusion Operator** Selectors noted as *(excludable)* may be specified with a `!` preceding a value to remove/exclude from the selection from a result set. So `stid=!KSLC` would prevent KSLC from returning in a query. This should be used in combination with different selectors. Remember to only include any given selector once. `stid` (string, *excludable* ), Single or comma separated list of SynopticLabs station IDs. Use a `!` before any value to exclude matching stations. Example: `stid=mtmet,kslc,fps`. Try it Now `state` (string, *excludable* ), Single or comma separated list of abbreviated 2 character states. If country is not included, default is United States (`US`). Use a `!` before any value to exclude matching stations. Example: `state=ut,wy,dc`. `country` (string, *excludable* ), Single or comma separated list of abbreviated 2 or 3 character countries. Use a `!` before any value to exclude matching stations. Example: `country=us,ca,mx`. `nwszone` (string, *excludable* ), Single or comma separated list of National Weather Service Zones. Use a `!` before any value to exclude matching stations. Example: `nwszone=UT003,CA041`. `nwsfirezone` (string, *excludable* ), Single or comma separated list of National Weather Service Fire Zones. Use a `!` before any value to exclude matching stations. Example: `nwsfirezone=LOX241` `cwa` (string, *excludable* ), Single or comma separated list of National Weather Service County Warning Areas. Use a `!` before any value to exclude matching stations. Example: `cwa=LOX`. `gacc` (string, *excludable* ), Single or comma separated list of Geographic Area Coordination Centers. Use a `!` before any value to exclude matching stations. Example: `gacc=GB`. `subgacc` (string, *excludable* ), Single or comma separated list of Sub Geographic Area Coordination Centers. Use a `!` before any value to exclude matching stations. Example: `subgacc=EB07`. `county` (string, *excludable* ), Single or comma separated list of counties. Use the `state` parameter to filter by state in the case of duplicate county names (i.e. "King"). Use a `!` before any value to exclude matching stations. Example: `county=king&state=wa`. `vars` (string), Single or comma separated list of sensor variables [found here](https://docs.synopticdata.com/services/station-variables.md). 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. *Some web services use this argument to adjust what information is delivered.* Example: `vars=wind_speed,pressure`. Try it Now `varsoperator` (string), Define how `&vars` is understood. `or` (the default) means any station with any variable in the list is used. `and` means a station must report every variable to be included. Example: `varsoperator=and`. `network` (number, string, *excludable* ), Single or comma separated list of network IDs or short names. The ID can be found be using the [Networks](https://docs.synopticdata.com/services/networks.md) service and are also listed [here](https://docs.synopticdata.com/services/station-networks-providers.md). Use a `!` before any value to exclude specific networks from a result set. Example: `network=153` or `network=44,251`. `radius` (string), 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 with units of miles. Adding `limit=n` to the query will limit the number of returned stations to **n** stations, and will order the stations by `DISTANCE`. Some examples are: `radius=41.5,-120.25,20`, `radius=wbb,10`, `radius=41.5,-120.25,20&limit=10`. `bbox` (string), 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`. **Bounding Box Thinning** A new feature allows you to use the API to thin the returned station set within a bounding box by providing some additional arguments. These arguments only take effect when the `bbox` parameter is used: `height` (number) the height of the map viewport in pixels `width` (number) the width of the map viewport in pixels `spacing` (number) the preferred number of pixels a station on the map should consume `networkimportance` (numbers, comma-separated) a list of comma separated network IDs that will be considered in the order provided. When there is a collision of stations within the defined "spacing" area, any station matching the list of preferred networks will be shown over any other. `status` (string), A value of either active or inactive returns only stations that are currently set as active in the archive. Stations are set to active if they have reported an observation in the last 30 days. By default, omitting this parameter will return all stations. Example: `status=active`. **Optional Parameters** * `vars` (air_temp, wind_speed, wind_gust), Percentiles are only available for these three variables (pass one or multiple). If omitted, all three variables will be returned. * `data` (complete \[default\], daily_min, daily_max, hourly), The data used to calculate percentile distributions. * `complete` (default) returns a single percentile distribution for each station derived from all observations in the full period-of-record. * `daily_min` and `daily_max` return a single distribution for each station derived from all daily minimum or maximum values spanning the full period-of-record. These are timezone-specific, and will respect the `obtimezone` arg. * `hourly` is only available for `vars=air_temp`, with percentile distributions available for each hour of the year. `hourly` requires `start` and `end` or `recent`(in minutes) formatted as **mmddHH** (to the nearest hour). For example, `start=120100&end=121000` will return hourly percentiles for Dec 1 00 UTC through Dec 10 00 UTC (spanning all years of record). Hourly air temp percentiles cannot be returned together with the other percentile data types. * `percentiles` (all \[default\], number), single number or comma-separated list of numbers for the percentiles to return. Available percentiles include (0, 0.5, 1, 1.5, 2, 3, 4, 5, 10, 15, 20, 25, 30, 35, 40, 45, 50, 55, 60, 65, 70, 75, 80, 85, 90, 95, 96, 97, 98, 98.5, 99, 99.5, 100). * `complete` (0 \[default\], 1), 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. Example: `complete=1`. * `fields` (string), Case-insensitive comma-separated list of metadata attributes to include in the output response. Default is to include all attributes. Only works with attributes defined in the default metadata set (e.g. attributes shown via `complete=1` cannot be selected). Example: `fields=stid,name`. * `obtimezone` (UTC \[default\], local), Indicates whether to use the station-local or UTC day for calculating percentiles for `data=daily_min` or `data=daily_max`. Example: `obtimezone=local`. * `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 for the requested time period will be returned. Default behavior is to remove any variables from the `PERCENTILES` element if no data is present. Setting to 1 will return keys in the `PERCENTILES` element for any requested variables. This guarantees that all keys in the `SENSOR_VARIABLES` element will be present in the `PERCENTILES` 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. * `fuel_moisture` (gm, %), Fuel Moisture: Grams, %. 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`. * `sitinghistory` (0 \[default\], 1), Will return all historical siting metadata for each station, as a list within the `SITING` key (requires `complete=1` to be enabled). Example: `sitinghistory=1`. The following example will request all percentiles for wind gust, using "complete" period-of-record data, reported by KSLC (Salt Lake City Airport): https://api.synopticdata.com/v2/stations/percentiles?stid=kslc&vars=wind_gust&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](https://en.wikipedia.org/wiki/ISO_8601) format. This behavior can be changed by passing a string with a valid [strftime](https://strftime.org/) 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](https://en.wikipedia.org/wiki/Unix_time) time in terms of seconds (this parameter cannot be used with `obtimezone`). This is a special function in addition to the supported [strftime](https://strftime.org/) arguments. * `output` (json \[default\], xml), Indicates the response format of the request. It's recommended to use the [JSON](https://json.org/) format which there are well supported parsing libraries in all major languages. ## Request Response **JSON Format** The Percentiles 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: JSON { STATION: [ { ID: "53", STID: "KSLC", NAME: "Salt Lake City, Salt Lake City International Airport", ELEVATION: "4226.0", LATITUDE: "40.77069", LONGITUDE: "-111.96503", STATUS: "ACTIVE", MNET_ID: "1", STATE: "UT", TIMEZONE: "America/Denver", ELEV_DEM: "4235.6", PERIOD_OF_RECORD: { start: "1997-01-01T00:00:00Z", end: "2025-02-19T05:54:00Z" }, UNITS: { position: "m", elevation: "ft" }, PERCENTILES: { wind_gust_set_1: [ { timezone: null, percentile_data: "complete", percentiles: [ { percentile: 0, value: 6.69 }, { percentile: 0.5, value: 7.2 }, { percentile: 1, value: 7.2 }, { percentile: 1.5, value: 7.2 }, { percentile: 2, value: 7.2 }, { percentile: 3, value: 7.202 }, { percentile: 4, value: 7.717 }, { percentile: 5, value: 7.72 }, { percentile: 10, value: 8.23 }, { percentile: 15, value: 8.75 }, { percentile: 20, value: 9.26 }, { percentile: 25, value: 9.77 }, { percentile: 30, value: 9.774 }, { percentile: 35, value: 10.29 }, { percentile: 40, value: 10.8 }, { percentile: 45, value: 11.318 }, { percentile: 50, value: 11.32 }, { percentile: 55, value: 11.83 }, { percentile: 60, value: 12.35 }, { percentile: 65, value: 12.86 }, { percentile: 70, value: 12.861 }, { percentile: 75, value: 13.38 }, { percentile: 80, value: 13.89 }, { percentile: 85, value: 14.92 }, { percentile: 90, value: 15.948 }, { percentile: 95, value: 17.49 }, { percentile: 96, value: 17.491 }, { percentile: 97, value: 18.52 }, { percentile: 98, value: 19.034 }, { percentile: 98.5, value: 19.55 }, { percentile: 99, value: 20.58 }, { percentile: 99.5, value: 21.61 }, { percentile: 100, value: 34.47 } ] } ] }, SENSOR_VARIABLES: { wind_gust: { wind_gust_set_1: {} } }, RESTRICTED: false, RESTRICTED_METADATA: false } ], SUMMARY: { NUMBER_OF_OBJECTS: 1, RESPONSE_CODE: 1, RESPONSE_MESSAGE: "OK", METADATA_PARSE_TIME: "0.2 ms", METADATA_DB_QUERY_TIME: "6.2 ms", DATA_QUERY_TIME: "10.3 ms", DATA_PARSING_TIME: "0.0 ms", TOTAL_DATA_TIME: "10.4 ms", VERSION: "v2.25.2" }, UNITS: { wind_gust: "m/s" } } * `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 the `RESPONSE_CODE`. * `VERSION`, is the API's current version number. * `METADATA_PARSE_TIME`, is the amount of time it took for the API to parse the metadata. * `METADATA_QUERY_TIME`, is the amount of time it took for the API to query 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. * `STATION[]` * `SENSOR_VARIABLES[]`, summary of variables in the STATISTICS element. * `PERCENTILES[]`, contains all the station's statistics over the specified period. * `UNITS{}` * A list of the units of each variable in the `PERCENTILES`element. --- language: "en" --- # Precipitation Returns derived precipitation totals or intervals for a requested time period and set of stations. This service encompasses Synoptic's Advanced Precipitation Service. For an in-depth explanation of our precipitation data processing, refer to [Precipitation Service Explained](https://docs.synopticdata.com/services/precipitation-service-explained.md). Requests to the Precipitation service have specific volume limitations depending on the `pmode` used. ## Request Format A Precipitation request is an HTTP URL with the following form: https://api.synopticdata.com/v2/stations/precip 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](https://docs.synopticdata.com/account/public-api-tokens.md). * 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. Station Selection Parameters These selectors individually or combined to target the desired stations. **Exclusion Operator** Selectors noted as *(excludable)* may be specified with a `!` preceding a value to remove/exclude from the selection from a result set. So `stid=!KSLC` would prevent KSLC from returning in a query. This should be used in combination with different selectors. Remember to only include any given selector once. `stid` (string, *excludable* ), Single or comma separated list of SynopticLabs station IDs. Use a `!` before any value to exclude matching stations. Example: `stid=mtmet,kslc,fps`. Try it Now `state` (string, *excludable* ), Single or comma separated list of abbreviated 2 character states. If country is not included, default is United States (`US`). Use a `!` before any value to exclude matching stations. Example: `state=ut,wy,dc`. `country` (string, *excludable* ), Single or comma separated list of abbreviated 2 or 3 character countries. Use a `!` before any value to exclude matching stations. Example: `country=us,ca,mx`. `nwszone` (string, *excludable* ), Single or comma separated list of National Weather Service Zones. Use a `!` before any value to exclude matching stations. Example: `nwszone=UT003,CA041`. `nwsfirezone` (string, *excludable* ), Single or comma separated list of National Weather Service Fire Zones. Use a `!` before any value to exclude matching stations. Example: `nwsfirezone=LOX241` `cwa` (string, *excludable* ), Single or comma separated list of National Weather Service County Warning Areas. Use a `!` before any value to exclude matching stations. Example: `cwa=LOX`. `gacc` (string, *excludable* ), Single or comma separated list of Geographic Area Coordination Centers. Use a `!` before any value to exclude matching stations. Example: `gacc=GB`. `subgacc` (string, *excludable* ), Single or comma separated list of Sub Geographic Area Coordination Centers. Use a `!` before any value to exclude matching stations. Example: `subgacc=EB07`. `county` (string, *excludable* ), Single or comma separated list of counties. Use the `state` parameter to filter by state in the case of duplicate county names (i.e. "King"). Use a `!` before any value to exclude matching stations. Example: `county=king&state=wa`. `vars` (string), Single or comma separated list of sensor variables [found here](https://docs.synopticdata.com/services/station-variables.md). 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. *Some web services use this argument to adjust what information is delivered.* Example: `vars=wind_speed,pressure`. Try it Now `varsoperator` (string), Define how `&vars` is understood. `or` (the default) means any station with any variable in the list is used. `and` means a station must report every variable to be included. Example: `varsoperator=and`. `network` (number, string, *excludable* ), Single or comma separated list of network IDs or short names. The ID can be found be using the [Networks](https://docs.synopticdata.com/services/networks.md) service and are also listed [here](https://docs.synopticdata.com/services/station-networks-providers.md). Use a `!` before any value to exclude specific networks from a result set. Example: `network=153` or `network=44,251`. `radius` (string), 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 with units of miles. Adding `limit=n` to the query will limit the number of returned stations to **n** stations, and will order the stations by `DISTANCE`. Some examples are: `radius=41.5,-120.25,20`, `radius=wbb,10`, `radius=41.5,-120.25,20&limit=10`. `bbox` (string), 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`. **Bounding Box Thinning** A new feature allows you to use the API to thin the returned station set within a bounding box by providing some additional arguments. These arguments only take effect when the `bbox` parameter is used: `height` (number) the height of the map viewport in pixels `width` (number) the width of the map viewport in pixels `spacing` (number) the preferred number of pixels a station on the map should consume `networkimportance` (numbers, comma-separated) a list of comma separated network IDs that will be considered in the order provided. When there is a collision of stations within the defined "spacing" area, any station matching the list of preferred networks will be shown over any other. `status` (string), A value of either active or inactive returns only stations that are currently set as active in the archive. Stations are set to active if they have reported an observation in the last 30 days. By default, omitting this parameter will return all stations. Example: `status=active`. * Either `start` and `end` or `recent` (one is required but not both) * `start` \& `end`, Defines the start and end 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. The start parameter must be used with the end 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** * `pmode` (totals \[default\], intervals, last), Defines the interval mode to calculate precipitation. **If omitted the default is** `totals`, however the returned JSON format will be different to align with legacy requirements (see JSON format examples below). Therefore, we recommend explicitly defining `pmode` for all cases. * `pmode=totals`, Returns totals for the start and end dates. * `pmode=intervals`, Returns accumulated precipitation for intervals provided in the additional `interval` argument. Valid keywords for `interval` are **hour** , **day** , **week** , **month** , **year** , or non-zero **integer in hours** . Integers must be a factor or multiple of 24 (1,2,3,4,6,8,12,24,48,72,etc). Default value is day if `interval` is not provided. Partial intervals at the end of a requested range are still returned. Note that all keywords or integers provided to `interval` will use UTC time zone to define the start and end of each interval. However, each interval respects the requested start hour such that intervals can be offset for a local time zone. * `pmode=last`, Returns accumulated precipitation intervals based on `end` date. The additional `accum_hours` argument accepts a comma separated list of hours, starting from `end` and moving back through time. If `accum_hours` is omitted the default is 1. If a `start` value is given, it is ignored. If `end` is omitted, the default is "now". Each interval always ends on the `end` date. * `search` (nearest, legacy \[default\]), Used to enable the "nearest" search mode when `pmode=totals`. **If omitted the default is** `legacy`. * `search=nearest`, The "nearest" search mode enables searching for precip reports both before and after the requested start and end. If discluded, the `legacy` precip totals method will be used which only looks back from the requested start and end. * `window` (15 \[default\]), Defines a time window (minutes) for the "nearest" search mode. Used to search both before and after the requested `start` and `end` to identify the `first_report` and `last_report` for precip totals. Only supported when `pmode=totals` and `search=nearest`. Default is `window=15`, maximum allowed is `window=60`. * `interval_window`, Defines a time window (hours) to allow returned intervals that are less than and/or greater than the requested interval. This parameter is useful for stations that may not report at regular frequency, resulting in variable interval durations between reports. Only applicable with `pmode=intervals` requests, and can be passed as a single argument or as two comma-separated args that define windows specific to shorter and longer allowed intervals. For example, `interval_window=0` returns interval data that *only* match requested `interval`. `interval_window=0,1` returns intervals at requested `interval`, but will return intervals up to duration of `interval` + 1 hour in the case that duration of `interval` is not available. Default value is `interval_window=0.5,0.5`, which returns interval data between `interval` - 0.5 hours and `interval` + 0.5 hours if interval data at the requested `interval` are not available. * `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` and `precip_accum_six_hour`). By default, the precipitation service will use the single most representative and consistently reporting variable to calculate derived precipitation. * `complete` (0 \[default\], 1), 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. Example: `complete=1`. * `fields` (string), Case-insensitive comma-separated list of metadata attributes to include in the output response. Default is to include all attributes. Only works with attributes defined in the default metadata set (e.g. attributes shown via `complete=1` cannot be selected). Example: `fields=stid,name`. * `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 with `start` and `end` are always UTC). Example: `obtimezone=local` * `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. * `units` (metric \[default\], english, \[custom format\]), Defines the unit of measure for returned data. For standard measurements used by many in North America `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. * `precip` (mm, cm, in), Precipitation: Millimeters, centimeters, inches. * `sitinghistory` (0 \[default\], 1), Will return all historical siting metadata for each station, as a list within the `SITING` key (requires `complete=1` to be enabled). Example: `sitinghistory=1`. **Note:** If a station has moved \>5 km during the requested time range, precipitation for the most recent location will be returned. The following example requests precipitation from from `stid=wbb` for all of January 2017 in terms of day intervals. https://api.synopticdata.com/v2/stations/precip?stid=wbb&start=201701010000&end=201702010000&pmode=intervals&interval=day&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](https://en.wikipedia.org/wiki/ISO_8601) format. This behavior can be changed by passing a string with a valid [strftime](https://strftime.org/) 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](https://en.wikipedia.org/wiki/Unix_time) time in terms of seconds (this parameter cannot be used with `obtimezone`). This is a special function in addition to the supported [strftime](https://strftime.org/) arguments. * `output` (json \[default\], xml), Indicates the response format of the request. It's recommended to use the [JSON](https://json.org/) format which there are well supported parsing libraries in all major languages. ## Request Response **JSON Format** The Precipitation 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: JSON { "UNITS": { "precipitation": "Millimeters" }, "STATION": [ { "STATUS": "ACTIVE", "MNET_ID": "153", "PERIOD_OF_RECORD": { "start": "1997-01-01T00:00:00Z", "end": "2018-01-10T12:00:00Z" }, "ELEVATION": "4806", "NAME": "U of U William Browning Building", "RESTRICTED": false, "STID": "WBB", "ELEV_DEM": "4738", "LONGITUDE": "-111.84755", "STATE": "UT", "LATITUDE": "40.76623", "TIMEZONE": "America/Denver", "ID": "1", "OBSERVATIONS": { "precipitation": [ { "count": 12, "first_report": "2017-01-31T23:00:00Z", "interval": 1, "report_type": "precip_accum_five_minute", "last_report": "2017-01-31T23:55:00Z", "total": 0 } ] } } ], "SUMMARY": { "DATA_QUERY_TIME": 169.8219776154, "RESPONSE_CODE": 1, "RESPONSE_MESSAGE": "OK", "NUMBER_OF_OBJECTS": 1 } } If `pmode` is omitted, the `OBSERVATIONS` block will be of this form (to comply with legacy output formats): JSON "OBSERVATIONS": { "ob_start_time_1": "2017-01-31T23:00:00Z", "total_precip_value_1": 0, "ob_end_time_1": "2017-01-31T23:55:00Z", "count_1": 12 }, * `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[]` * `OBSERVATIONS[]`, contains all the observational data. --- language: "en" --- # Precipitation Service Explained Synoptic's [Weather API Precipitation Service](https://docs.synopticdata.com/services/precipitation.md) is a powerful and flexible tool, processing raw precipitation data from [station networks](https://docs.synopticdata.com/services/station-networks-providers.md) and serving it in a uniform format through Weather API. Precipitation is reported from hundreds of networks with different reporting conventions and precipitation sensor types. For example, precipitation may be reported in 15 minute accumulations, hourly accumulations, accumulation since local midnight, or continuous accumulation over the calendar year or water year (`precip_accum`). Across our data providers, precipitation is reported in more than 20 different forms (see [Station Variables](https://docs.synopticdata.com/services/station-variables.md) that include `precip`). The large variety of precipitation measurement types (i.e. precipitation variables) makes it challenging for users to compare precipitation amounts over geographic areas with stations reporting a variety of variable types. Finding precipitation totals for a defined time period and collection of stations requires tailoring the precipitation processing to each station's specific variable type, and accounting for events such as station resets. Synoptic's Precipitation Service eliminates these variable-specific complications for the user, providing access to derived precipitation data that can be easily integrated into downstream applications. Real-time precipitation data is processed and stored in Synoptic's derived precipitation database. We have dedicated years to developing robust QC methods to remove outlier data, such as physically implausible dips and spikes. Through the Precipitation Service, we enable flexible retrieval of both current and historical data over time periods and intervals defined by the user. The result is access to real-time, quality-controlled, and consistently formatted precipitation data reported by more than 60,000 stations, all from a single API retrieval endpoint. ## Basic Precipitation Basic derived precipitation is provided for single or multiple stations via the [Time Series Service](https://docs.synopticdata.com/services/time-series.md#Basic-Precipitation) by adding `precip=1` to the request. This will replace any raw precipitation variables with two derived variables, `precip_intervals` and `precip_accumulated`. `precip_intervals` represent precipitation received in the intervals between consecutive observations. `precip_accumulated` is the cumulative sum of the interval values for the requested time period. This essentially standardizes the returned precipitation data for any network and request period. Basic precipitation is also available in csv output for individual stations. Note that basic precipitation intervals and accumulations are only provided at the reporting frequency of the station. For custom user-defined time intervals and totals, the advanced precipitation features must be used. ### Advanced Precipitation Advanced derived precipitation is provided with the [Precipitation Service](https://docs.synopticdata.com/services/precipitation.md) (the `/precip` endpoint). Please see our [pricing page](https://synopticdata.com/pricing) for access options. This service allows for user-defined "modes" (`pmode`) including: * `totals`: accumulation totals over a defined period between `start` and `end`. * `intervals`: precipitation between `start` and `end`, reported in time intervals defined as integer hours (e.g. `1`,`3`,`6`,...), `hour`, `day`, `week`, `month` or `year`. * `last`: precipitation intervals over defined periods prior to a specified `end` time (current or historic). Requests can include multiple station networks over broad geographic regions and time periods, where all results are returned with uniform format. The Precipitation Service accepts the same station selection parameters available to other web services, such as `state`, `county`, `network`, `radius` and `bbox`. Example request patterns may include: * Daily precipitation for all precipitation-measuring stations in California for the 2020-21 water year. * 1-yr, 5-yr and 10-yr precipitation totals for all stations in the entire SNOTEL network. * Precipitation totals over the past hour for all RAWS stations in a radius from a defined lat/lon coordinate. * Precipitation totals for the 1,3,6,12,24,48 and 72-hr periods prior to the current request time, for any network or geographic area. Header image: ETI precipitation gauge at [JHR](https://viewer.synopticdata.com/map/data/now/precipitation24hr/JHR/plots/precipitation#map=9.31/43.5994/-110.8521) in northwest Wyoming. --- language: "en" --- # Push Streaming ## Synoptic Push Streaming Services The data push services allow users to "plug" into the real-time data streams after data checks have been applied. Nearly 100 million observations flow through this system every day, and these data services allow for the filtering of various domains and observed surface conditions from over 260 mesonet networks and over 120,000 active stations. Data streaming is available for customers with [our higher tier commercial accounts](https://synopticdata.com/commercial-pricing). ## Connection and Data Format Details ### Establishing Connections The connection protocol uses secure websockets (`wss://`). Establishing a connection to the data push services requires a wss connection to our server endpoint. The connection arguments can take one of two forms: initial connections and reestablishing connections. #### Initial Connections wss://push.synopticdata.com/feed/{valid_api_token}/?{optional_arguments} This form expects a valid [API token](https://docs.synopticdata.com/account/public-api-tokens.md) and any optional arguments to limit the selection domain. For example: `wss://push.synopticdata.com/feed/{valid_api_token}/?state=ca&vars=air_temp,wind_speed` In this case, all observations originating from stations within the state of California that report air temperature or wind speed will send to the established connection within seconds of the observation entering our data ingest system. The initial response will take this form JSON { "code": "success", "messages": ["Starting new session."], "session": "993624a1-2563-412e-9cfb-647535a364ac", "type": "auth" } or JSON { "code": "failed", "messages": ["invalid token"], "session": "", "type": "auth" } ## Re-establishing Connections `wss://push.synopticdata.com/feed/[your token]/993624a1-2563-412e-9cfb-647535a364ac` Upon successful initial connections, a session ID is provided that can be used to reestablish a severed or stopped connection. This is useful to ensure all data since the last push is resumed at the exact location without missing a single observation. The use of this form will ignore all optional arguments and use the arguments supplied with the initial connection if any were given. The response for reestablishing connections will take this form JSON { "code": "success", "messages": ["Restarting from provided session id."], "session": "33258f22-77b7-4514-8a30-a792e97e170a", "type": "auth" } A connection can be resumed up to 3 days after its last disconnect. ### Response Types All response objects returned from the data push service are valid JSON. Every JSON object will contain the key of "type" which indicates exactly what the object represents. There are 3 types. | JSON Reponse Type | Description | |-------------------|-----------------------------------------------------------------------------------------------------------------------------------------| | `auth` | Used to indicate the status of attempted authentication. Successful authentications will provide a session ID. | | `metadata` | Used to indicate all information in the JSON object is metadata relating to UNITS or STATIONS. | | `data` | Used to indicate all information in the JSON object is observational data matching the domain criteria provided for the active session. | #### Stopping Connections Connections can be explicitly stopped at any time. Sending the command to terminate the existing websocket connection takes this form JSON { "feed_action": "stop" } Stopping a connection or simply severing the network connection is effectively the same thing. If the connection is reestablished, all data not pushed since the last successful push will begin to flow. #### Data Object Response Formats By default, basic metadata of all data elements are also sent. Metadata will always flow prior to the first occurrence of data, which guarantees metadata is available for any given observational data object. The metadata format takes this form JSON { "units": [ { "sensor": "air_temp", "unit": "Celsius" }, { "sensor": "wind_speed", "unit": "m/s" } ], "type": "metadata", "stations": [ { "latitude": "40.76623", "stid": "WBB", "elevation": 4806.0, "network": 153, "longitude": "-111.84755" }, { "latitude": "38.89724", "stid": "MOA18", "elevation": 829.0, "network": 156, "longitude": "-92.21807" }, ... ] } Objects containing observational data will have this form JSON { "type": "data", "data": [ { "set": 1, "stid": "KXBP", "value": -6.69, "qc": [], "date": 201801132215, "sensor": "wind_speed" }, { "set": 1, "stid": "C4824", "value": 6.56, "qc": [], "date": 201801132220, "sensor": "air_temp" }, { "set": 1, "stid": "C4824", "value": 0.0, "qc": [], "date": 201801132220, "sensor": "wind_speed" }, { "set": 1, "stid": "D7524", "value": -8.33, "qc": [], "date": 201801132221, "sensor": "air_temp" } ] } The "data" entry is a list of observations broken into individual variable values. This pattern follows other data services such as the Weather API. Each nested object of data contain the following keys: | Key | Description | |----------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `stid` | The station identifier known within all Synoptic data services. | | `date` | The date and time of the observation. This is in the form of yyyymmddhhmm (year, month, day, hour, minute) in UTC. | | `sensor` | The sensor (variable) name the data represents. The names used are the same as all Synoptic data services (see API). | | `set` | The instance of the sensor for the given station. Some stations may report more than one instance of a sensor, such as air temperature at 2 meters and 10 meters, or soil temperature at 10 cm below the surface and 30 cm below the surface. | | `value` | The value of the sensed observation for that moment in time. The units will be in what was supplied on the initial connection. Default is metric. The metadata JSON object will contain all unit information for clarification. | | `qc` | A list of all data checks and quality control flags that indicate a failed test. For example, `sl_rate_change` reflects a rate change test failed for the given observation. | ## Web Socket Connection Arguments ### Domain Selection | Argument | Description Example | |---------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `state` | Provide a list of state codes to limit the observation domain to consider. Example `state=ut,ca,nv` | | `network` | Provide a list of network IDs to consider. All other observations are ignored. Example `network=1,65,2,153` | | `radius` | Provide a latitude and longitude with a radius in miles. Only observations originating from the radius will be considered. Alternatively, provide a station ID and a radius. Example `radius=41.5,-111.2,50 or radius=KLAX,100` | | `nwszone` | Provide a list of NWS county warning areas as the domain to consider. Example `nwszone=VA525,UT003` | | `nwsfirezone` | Provide a list of NWS fire zones as the domain to consider. Example `nwsfirezone=SLC478` | | `bbox` | Provide a bounding box as the domain to listen to. The rectangle must be in the form of (`min_lon`, `min_lat`, `max_lon`, `max_lat`). Example `bbox=-100,30,-90,40` | | `stid` | Provide a distinct set of stations to monitor. Only these stations will have data returned. Example `stid=KSLC,WBB,KSFO` | #### Sensor and Data Checks | Argument | Description Example | |--------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `vars` | Provide a list of sensor names to limit returning only those data elements. Sensor names are in the form found on the Weather API. All names are identical. The response returned will contain these names as the sensor as well. Omitting this argument will return all available sesnsors for the matching stations within the selection domain. Example `vars=air_temp,wind_speed,wind_gust,pressure,relative_humidity` | | `qc` | A list of data checks that remove observations matching the given list. By default, no observations will be returned that have been flagged with a failed range test (sl_range_check). It is up to the user to decide what flags are important to apply to the data based on the use case. If set to off then all data will be returned *without data checks and quality control* (not recommended). Example `qc=sl_rate_change,sl_persistence` | | `no_derived` | Indicate whether variables derived by Synoptic should not be returned (e.g. dew point temperature). Only observations as reported by the station will be returned. | #### Filter Conditions | Argument | Description Example | |-------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `filter_on` | ⚠️ *Will be deprecated in next release.* Set of conditional expressions defined similar to a SQL where statement. Only data matching the criteria set will be returned in the feed. Each condition must be enclosed within parenthesis and have a sensor name, evaluator, and value. Conditional phrases may be chained together with "and" or "or" operators. Nested conditional phrases may also be used to create complex queries. All nested phrases must also be enclosed with parenthesis. Allowed evaluators include: `> >= < <= =` Example `(air_temp < 0) and (wind_speed > 10)` | #### Time Selection | Argument | Description Example | |----------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `rewind` | Provide a number of minutes behind the current time to start the feed. Once all observations have been returned for matches prior to the current time, the feed will resume in real-time mode. This option is useful to "seed" an application with recent data for trending. Example `rewind=5` | #### Units and Metadata | Argument | Description Example | |------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `units` | Provide the units to return data in. Default is metric and the absence of this argument is metric. Note, the filter_on comparison values will match the units provided. For example, if mph is set for wind, then a filter of (wind_gust \> 30) will look for gusts greater than 30 miles per hour. Example `units=english or units=temp|f,wind|ms` | | `metadata` | Select if metadata is also returned within the responses. By default, all stations and units will return metadata. The metadata responses will always return within their own discrete messages in the feed, noted with the type of "metadata". If metadata is not needed, adding a value of 0 or off will disable it. Metadata is returned exactly once for any unique station or unit seen within the feed. Metadata will always be sent prior to any observation the first time it is seen from any new connection. It is the developers responsibilty to organize metadata to be useful when applicable. | --- language: "en" --- # Push streaming code examples Listening to a websocket stream can be very simple, but unlike [Weather API](https://docs.synopticdata.com/services/weather-api.md) it is not as easy as typing a formatted URL into a browser. Here we have collected some very bare code examples you can use to get started with listening to WebSockets in your applications. ## Javascript Javascript (and NodeJS) is a popular, native language for working with WebSockets in a browser or server environment. The `WebSocket` object/class is a native part of the language, and creates a very simple interface for receiving WebSocket Messages. [Learn More](https://developer.mozilla.org/en-US/docs/Web/API/WebSocket) 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; ## WSCat This is a terminal utility built on NodeJS, that you can use to direclty watch a websocket from a command line. When specifying a URL with parameters in the command line, remember to enclose the URL in quotes. [Learn about wscat](https://www.npmjs.com/package/wscat). Bash wscat -c "wss://push.synopticdata.com/feed/{Your Token}/?{Arguments}" ## Python There are a number of Python implementations of websockets, and they all work largely the same. This quick example uses websocket-client (`pip install websocket-client`), but others, including `Tornado` have the feature built-in. 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. You can learn more about `websocket-client` [here](https://pypi.org/project/websocket-client/). Learn about `tornado.websocket` [here](https://www.tornadoweb.org/en/stable/websocket.html). --- language: "en" --- # Push streaming demos [Condition Monitor](https://demos.synopticdata.com/push-monitor/index.html) ![https://developers.synopticdata.com/assets/img/condmonitor.png](https://developers.synopticdata.com/assets/img/condmonitor.png) Explore selection parameters in a comprehensive interface *** ** * ** *** [Map Based Display](https://demos.synopticdata.com/push-map/index.html) ![https://developers.synopticdata.com/assets/img/apscreenshot.png](https://developers.synopticdata.com/assets/img/apscreenshot.png) A simple interface for trying different parameter combinations. *** ** * ** *** [Live Updating Table](https://demos.synopticdata.com/stream-table/index.html) ![https://developers.synopticdata.com/assets/img/tabpushdemo.png](https://developers.synopticdata.com/assets/img/tabpushdemo.png) This table keeps its cells with the immediate most recent values from a set of stations. --- language: "en" --- # Push streaming service arguments The push streaming service accepts most [Station Selection Parameters](https://docs.synopticdata.com/services/station-selection-parameters.md) consistent with the Weather API service. This guide outlines all the parameters the Push Streaming Service accepts. ## Web Socket Connection Arguments ### Domain Selection | Argument | Description Example | |---------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `state` | Provide a list of state codes to limit the observation domain to consider. Example `state=ut,ca,nv` | | `network` | Provide a list of network IDs to consider. All other observations are ignored. Example `network=1,65,2,153` | | `radius` | Provide a latitude and longitude with a radius in miles. Only observations originating from the radius will be considered. Alternatively, provide a station ID and a radius. Example `radius=41.5,-111.2,50 or radius=KLAX,100` | | `nwszone` | Provide a list of NWS county warning areas as the domain to consider. Example `nwszone=VA525,UT003` | | `nwsfirezone` | Provide a list of NWS fire zones as the domain to consider. Example `nwsfirezone=SLC478` | | `bbox` | Provide a bounding box as the domain to listen to. The rectangle must be in the form of (`min_lon`, `min_lat`, `max_lon`, `max_lat`). Example `bbox=-100,30,-90,40` | | `stid` | Provide a distinct set of stations to monitor. Only these stations will have data returned. Example `stid=KSLC,WBB,KSFO` | #### Sensor and Data Checks | Argument | Description Example | |--------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `vars` | Provide a list of sensor names to limit returning only those data elements. Sensor names are in the form found on the Mesonet data API. All names are identical. The response returned will contain these names as the sensor as well. Omitting this argument will return all available sesnsors for the matching stations within the selection domain. Example `vars=air_temp,wind_speed,wind_gust,pressure,relative_humidity` | | `qc` | A list of data checks that remove observations matching the given list. By default, no observations will be returned that have been flagged with a failed range test (sl_range_check). It is up to the user to decide what flags are important to apply to the data based on the use case. If set to off then all data will be returned *without data checks and quality control* (not recommended). Example `qc=sl_rate_change,sl_persistence` | | `no_derived` | Indicate whether variables derived by Synoptic should not be returned (e.g. dew point temperature). Only observations as reported by the station will be returned. | #### Filter Conditions | Argument | Description Example | |-------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `filter_on` | ⚠️ *Will be deprecated in next release.*Set of conditional expressions defined similar to a SQL where statement. Only data matching the criteria set will be returned in the feed. Each condition must be enclosed within parenthesis and have a sensor name, evaluator, and value. Conditional phrases may be chained together with "and" or "or" operators. Nested conditional phrases may also be used to create complex queries. All nested phrases must also be enclosed with parenthesis. Allowed evaluators include: `> >= < <= =` Example `(air_temp < 0) and (wind_speed > 10)` | #### Time Selection | Argument | Description Example | |----------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `rewind` | Provide a number of minutes behind the current time to start the feed. Once all observations have been returned for matches prior to the current time, the feed will resume in real-time mode. This option is useful to "seed" an application with recent data for trending. Example `rewind=5` | #### Units and Metadata | Argument | Description Example | |------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `units` | Provide the units to return data in. Default is metric and the absence of this argument is metric. Note, the filter_on comparison values will match the units provided. For example, if mph is set for wind, then a filter of (wind_gust \> 30) will look for gusts greater than 30 miles per hour. Example `units=english or units=temp|f,wind|ms` | | `metadata` | Select if metadata is also returned within the responses. By default, all stations and units will return metadata. The metadata responses will always return within their own discrete messages in the feed, noted with the type of "metadata". If metadata is not needed, adding a value of 0 or off will disable it. Metadata is returned exactly once for any unique station or unit seen within the feed. Metadata will always be sent prior to any observation the first time it is seen from any new connection. It is the developers responsibilty to organize metadata to be useful when applicable. | --- language: "en" --- # QC Flag Types These are the active QC flags in our production system. Some MADIS flags may not be active. The "Check Identifier" values in the table can be used in the Weather API with the `qc_checks=` argument. [Learn about our QC](https://docs.synopticdata.com/services/mesonet-data-qc.md) | Check Identifier | Name | Provider | QC ID | |-----------------------------------------------|----------------------------------------------------------------------------|--------------------|-------| | sl_range_check | SynopticLabs Range Check | Synoptic Data | 1 | | sl_pers_check | SynopticLabs Temporal Persistence Check | Synoptic Data | 3 | | sl_windspd_maxgust_check | SynopticLabs Wind Speed vs. Maximum Gust | Synoptic Data | 10 | | sl_rate_check | SynopticLabs Rate Change Check | Synoptic Data | 81 | | sl_wind_gust_factor_check | SynopticLabs Wind Gust Factor Check | Synoptic Data | 86 | | sl_secondary_range_check | SynopticLabs Secondary Range Check | Synoptic Data | 87 | | sl_secondary_pers_check | SynopticLabs Secondary Persistence Check | Synoptic Data | 88 | | sl_soil_moisture_freeze_check | SynopticLabs Soil Moisture Freezing Check | Synoptic Data | 89 | | sl_sensor_status_signal_check | SynopticLabs Sensor Status Signal Check | Synoptic Data | 90 | | sl_snow_depth_hist_check | SynopticLabs Snow Depth History Check | Synoptic Data | 91 | | sl_percentile_hiflag_check | SynopticLabs Percentile High Flag Check | Synoptic Data | 100 | | sl_percentile_hioutlier_check | SynopticLabs Percentile High Outlier Check | Synoptic Data | 101 | | sl_percentile_loflag_check | SynopticLabs Percentile Low Flag Check | Synoptic Data | 102 | | sl_percentile_looutlier_check | SynopticLabs Percentile Low Outlier Check | Synoptic Data | 103 | | sl_spatial_value_check | SynopticLabs Spatial Value Check | Synoptic Data | 105 | | ma_range_check | MADIS Range Check | MADIS (NOAA) | 13 | | ma_position_check | MADIS Position Consistency Check | MADIS (NOAA) | 14 | | ma_int_cons_check | MADIS Internal Consistency Check | MADIS (NOAA) | 15 | | ma_temp_cons_check | MADIS Temporal Consistency Check | MADIS (NOAA) | 16 | | ma_stat_spatial_cons_check | MADIS Statistical Spatial Consistency Check | MADIS (NOAA) | 17 | | ma_stat_cons_check | MADIS Spatial Consistency Check | MADIS (NOAA) | 18 | | ma_fcst_cons_check | MADIS Forecast Model Consistency Check | MADIS (NOAA) | 19 | | ma_stat_model_cons_check | MADIS Statistical Model Consistency Check | MADIS (NOAA) | 20 | | ma_kal_filter_check | MADIS Kalman Filter Check | MADIS (NOAA) | 21 | | ma_slp_stnpres_check | MADIS SLP vs. Station Pressure | MADIS (NOAA) | 22 | | ma_pres_chng_stn_pres_check | MADIS Pressure Change vs. Station Pressure | MADIS (NOAA) | 23 | | ma_airtemp_dwpt_check | MADIS Air Temperature vs. Dewpoint Temperature | MADIS (NOAA) | 24 | | ma_airtemp_mmtemp_check | MADIS Air Temperature vs. Max/Min Temperature | MADIS (NOAA) | 25 | | ma_airtemp_SST_check | MADIS Air Temperature vs. SST | MADIS (NOAA) | 26 | | ma_winddir_windspd_check | MADIS Wind Direction vs. Wind Speed | MADIS (NOAA) | 27 | | ma_windspd_maxgust_check | MADIS Wind Speed vs. Maximum Gusts | MADIS (NOAA) | 28 | | ma_windspd_preswx_check | MADIS Wind Speed vs. Present Weather | MADIS (NOAA) | 29 | | ma_windspd_peak_windspd_check | MADIS Wind Speed vs. Peak Wind Speed | MADIS (NOAA) | 30 | | ma_windspd_max_windspd_check | MADIS Wind Speed vs. Maximum Wind Speed | MADIS (NOAA) | 31 | | ma_winddir10m_windspd10m_check | MADIS Wind Direction at 10m vs. Wind Speed at 10m | MADIS (NOAA) | 32 | | ma_winddir20m_windspd20m_check | MADIS Wind Direction at 20m vs. Wind Speed at 20m | MADIS (NOAA) | 33 | | ma_maxgust_peak_windspd_check | MADIS Maximum Gusts vs. Peak Wind Speed | MADIS (NOAA) | 34 | | ma_maxgust_max_windspd_check | MADIS Maximum Gusts vs. Maximum Wind Speed | MADIS (NOAA) | 35 | | ma_peak_windspd_preswx_check | MADIS Peak Wind Speed vs. Present Weather | MADIS (NOAA) | 36 | | ma_hvis_preswx_check | MADIS Horizontal Visibility (VV) vs. Present Weather (ww) | MADIS (NOAA) | 37 | | ma_preswx_airtemp_check | MADIS Present Weather vs. Air temperature | MADIS (NOAA) | 38 | | ma_preswx_totcldcov_check | MADIS Present Weather vs. Total Cloud Cover | MADIS (NOAA) | 39 | | ma_preswx_lmcldcov_check | MADIS Present Weather vs. Low/Middle Cloud Cover | MADIS (NOAA) | 40 | | ma_preswx_accprecip_check | MADIS Present Weather vs. Accumulated Precipitation | MADIS (NOAA) | 41 | | ma_preswx_airtemp_windspd_dwpt_check | MADIS Present Weather vs. Air temperature; Wind Speed; and Dewpoint | MADIS (NOAA) | 42 | | ma_pastwx_accprecip_check | MADIS Past Weather vs. Accumulated Precipitation | MADIS (NOAA) | 43 | | ma_totcldcov_layer_cldcov_check | MADIS Total Cloud Cover vs. Layer Cloud cover | MADIS (NOAA) | 44 | | ma_totcldcov_lmcldcov_check | MADIS Total Cloud Cover vs. Low/Middle Cloud Cover | MADIS (NOAA) | 45 | | ma_totcldcov_lmhcldtype_check | MADIS Total Cloud Cover vs. Low/Middle/High Cloud Type | MADIS (NOAA) | 46 | | ma_totcldcov_lmcldcov_lmhcldtype_check | MADIS Total Cloud Cover vs. L/M Cloud Cover and Low/Middle/High Cloud Type | MADIS (NOAA) | 47 | | ma_totcldcov_vis_check | MADIS Total Cloud Cover vs. Visibility | MADIS (NOAA) | 48 | | ma_tocldcov_preswx_check | MADIS Total Cloud Cover vs. Present Weather | MADIS (NOAA) | 49 | | ma_lmcldcov_lmhcldtype_check | MADIS Low/Middle Cloud Cover vs. Low/Middle/High Cloud Types | MADIS (NOAA) | 50 | | ma_lmcldcov_layercldtype_check | MADIS Low/Middle Cloud Cover vs. Layer Cloud Type | MADIS (NOAA) | 51 | | ma_lcldtype_layercldtype_check | MADIS Low Cloud Type vs. Layer Cloud Type | MADIS (NOAA) | 52 | | ma_lcldtype_lmcldcov_check | MADIS Low Cloud Type vs. Low/Middle Cloud Cover | MADIS (NOAA) | 53 | | ma_lmcldtype_lmcldcov_check | MADIS Low/Middle Cloud Type vs. Low/Middle Cloud Cover | MADIS (NOAA) | 54 | | ma_lcldtype_mhcldtype_check | MADIS Low Cloud Type vs. Middle/High Cloud Type | MADIS (NOAA) | 55 | | ma_lcldtype_hcldtype_totcldcov_lmcldcov_check | MADIS Low Cloud Type vs. High Cloud Type and Total and L/M Cloud Cover | MADIS (NOAA) | 56 | | ma_mcldtype_hcldtype_check | MADIS Middle Cloud Type vs. High Cloud Type | MADIS (NOAA) | 57 | | ma_mcldtype_hcldtype_totcldcov_lmcldcov_check | MADIS Middle Cloud Type vs. High Cloud Type and Total and L/M Cloud Cover | MADIS (NOAA) | 58 | | ma_mcldtype_layercldtype_check | MADIS Middle Cloud Type vs. Layer Cloud Type | MADIS (NOAA) | 59 | | ma_mcldtype_lcldtype_layercldtype_check | MADIS Middle Cloud Type vs. Low Cloud Type and Layer Cloud Type | MADIS (NOAA) | 60 | | ma_hcldtype_layercldtype_check | MADIS High Cloud Type vs. Layer Cloud Type | MADIS (NOAA) | 61 | | ma_hcldtype_lmcldtype_layercldtype | MADIS High Cloud Type vs. L/M Cloud Type and Layer Cloud Type | MADIS (NOAA) | 62 | | ma_hcldtype_totcldcov_check | MADIS High Cloud Type vs. Total Cloud Cover | MADIS (NOAA) | 63 | | ma_layercldcov_cldlayerreps_check | MADIS Layer Cloud Cover vs. Cloud Layer Reports | MADIS (NOAA) | 64 | | ma_layercldcov_lmhcldtype_check | MADIS Layer Cloud Cover vs. Low/Middle/High Cloud Type | MADIS (NOAA) | 65 | | ma_layercldcov_lmhcldcov_check | MADIS Layer Cloud Cover vs. Low/Middle/High Cloud Cover | MADIS (NOAA) | 66 | | ma_layercldtype_lmhcldtype_check | MADIS Layer Cloud Type vs. Low/Middle/High Cloud type | MADIS (NOAA) | 67 | | ma_layercldtype_lmhcldcov_layercldcov_check | MADIS Layer Cloud Type vs. Low/Middle Cloud Cover and Layer Cloud Cover | MADIS (NOAA) | 68 | | ma_layercldbase_lmhcldtype_check | MADIS Layer Cloud Base vs. Low/Middle/High cloud type | MADIS (NOAA) | 69 | | ma_layercldbase_layercldtype_check | MADIS Layer Cloud Base vs. Layer Cloud Type | MADIS (NOAA) | 70 | | ma_layercldbase_lmhcldcov_check | MADIS Layer Cloud Base vs. Low/Middle Cloud Cover | MADIS (NOAA) | 71 | | ma_layercldbase_hcldtype_layercldtype_check | MADIS Layer Cloud Base vs. High Cloud Type and Layer Cloud Type | MADIS (NOAA) | 72 | | ma_accprecip_snowdepth_check | MADIS Accumulated Precip (during period) vs. Snow Depth | MADIS (NOAA) | 73 | | ma_accprecip_snowfall_check | MADIS Accumulated Precip (during period) vs. Snowfall | MADIS (NOAA) | 74 | | ma_accprecip_24hrprecip_check | MADIS Accumulated Precip (during period) vs. Accumulated Precip (24h) | MADIS (NOAA) | 75 | | ma_snowdepth_swe_check | MADIS Snow Depth vs. Snow Water Equivalent | MADIS (NOAA) | 76 | | arlfrd_manual_check | ARLFRD Manual Data Check | undefined | 77 | | mw_multvariate_lin_reg_check | MesoWest Multivariate Linear Regression Check | University of Utah | 78 | | mw_24h_wind_persistence_check | MesoWest 24 Hour Wind Persistence Check | University of Utah | 79 | | mw_uu2dvar_rejection | MesoWest UU2DVAR Rejection | University of Utah | 80 | --- language: "en" --- # Quality control Synoptic Data applies its own and external Quality Control to all the data that is ingested across our systems to provide users across of all our data services insight into the validity of each observation. Consult the following articles for a full catalog and description of how each Quality Control check is applied: * [Synoptic Data QC](https://docs.synopticdata.com/services/mesonet-data-qc.md) * [QC Flag Types](https://docs.synopticdata.com/services/qc-flag-types.md) --- language: "en" --- # Quality Control Segments Returns data for a station or set of stations for a time span ## Request Format A QC Segments request is an HTTP URL with the following form: https://api.synopticdata.com/v2/stations/qcsegments 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](https://docs.synopticdata.com/account/public-api-tokens.md). * 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. Station Selection Parameters These selectors individually or combined to target the desired stations. **Exclusion Operator** Selectors noted as *(excludable)* may be specified with a `!` preceding a value to remove/exclude from the selection from a result set. So `stid=!KSLC` would prevent KSLC from returning in a query. This should be used in combination with different selectors. Remember to only include any given selector once. `stid` (string, *excludable* ), Single or comma separated list of SynopticLabs station IDs. Use a `!` before any value to exclude matching stations. Example: `stid=mtmet,kslc,fps`. Try it Now `state` (string, *excludable* ), Single or comma separated list of abbreviated 2 character states. If country is not included, default is United States (`US`). Use a `!` before any value to exclude matching stations. Example: `state=ut,wy,dc`. `country` (string, *excludable* ), Single or comma separated list of abbreviated 2 or 3 character countries. Use a `!` before any value to exclude matching stations. Example: `country=us,ca,mx`. `nwszone` (string, *excludable* ), Single or comma separated list of National Weather Service Zones. Use a `!` before any value to exclude matching stations. Example: `nwszone=UT003,CA041`. `nwsfirezone` (string, *excludable* ), Single or comma separated list of National Weather Service Fire Zones. Use a `!` before any value to exclude matching stations. Example: `nwsfirezone=LOX241` `cwa` (string, *excludable* ), Single or comma separated list of National Weather Service County Warning Areas. Use a `!` before any value to exclude matching stations. Example: `cwa=LOX`. `gacc` (string, *excludable* ), Single or comma separated list of Geographic Area Coordination Centers. Use a `!` before any value to exclude matching stations. Example: `gacc=GB`. `subgacc` (string, *excludable* ), Single or comma separated list of Sub Geographic Area Coordination Centers. Use a `!` before any value to exclude matching stations. Example: `subgacc=EB07`. `county` (string, *excludable* ), Single or comma separated list of counties. Use the `state` parameter to filter by state in the case of duplicate county names (i.e. "King"). Use a `!` before any value to exclude matching stations. Example: `county=king&state=wa`. `vars` (string), Single or comma separated list of sensor variables [found here](https://docs.synopticdata.com/services/station-variables.md). 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. *Some web services use this argument to adjust what information is delivered.* Example: `vars=wind_speed,pressure`. Try it Now `varsoperator` (string), Define how `&vars` is understood. `or` (the default) means any station with any variable in the list is used. `and` means a station must report every variable to be included. Example: `varsoperator=and`. `network` (number, string, *excludable* ), Single or comma separated list of network IDs or short names. The ID can be found be using the [Networks](https://docs.synopticdata.com/services/networks.md) service and are also listed [here](https://docs.synopticdata.com/services/station-networks-providers.md). Use a `!` before any value to exclude specific networks from a result set. Example: `network=153` or `network=44,251`. `radius` (string), 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 with units of miles. Adding `limit=n` to the query will limit the number of returned stations to **n** stations, and will order the stations by `DISTANCE`. Some examples are: `radius=41.5,-120.25,20`, `radius=wbb,10`, `radius=41.5,-120.25,20&limit=10`. `bbox` (string), 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`. **Bounding Box Thinning** A new feature allows you to use the API to thin the returned station set within a bounding box by providing some additional arguments. These arguments only take effect when the `bbox` parameter is used: `height` (number) the height of the map viewport in pixels `width` (number) the width of the map viewport in pixels `spacing` (number) the preferred number of pixels a station on the map should consume `networkimportance` (numbers, comma-separated) a list of comma separated network IDs that will be considered in the order provided. When there is a collision of stations within the defined "spacing" area, any station matching the list of preferred networks will be shown over any other. `status` (string), A value of either active or inactive returns only stations that are currently set as active in the archive. Stations are set to active if they have reported an observation in the last 30 days. By default, omitting this parameter will return all stations. Example: `status=active`. * Either `start` and `end`, or `recent` (one is required but not both) * `start` \& `end`, Defines the `start` and `end` 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. The `start` parameter must be used with the `end` 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** * `inside` (0 \[default\], 1), Requires the QC segment start within the requested time span. Example: `inside=1`. * `complete` (0 \[default\], 1), 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. Example: `complete=1`. * `fields` (string), Case-insensitive comma-separated list of metadata attributes to include in the output response. Default is to include all attributes. Only works with attributes defined in the default metadata set (e.g. attributes shown via `complete=1` cannot be selected). Example: `fields=stid,name`. * `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` * `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. * `qc_checks` (\[flag name\], \[flag source\], all) defines a list of data checks applied to data values. The settings of other QC parameters determines how the data and data checks are returned. * `all` is equivalent to `synopticlabs`, and will return all QC in Synoptic's basic and advanced checks. * "flag name" allows the targeting of a flag by name or (comma-separated) list. i.e. `sl_range_check,sl_rate_check`. * "flag source" allows targeting a data check provider i.e. `synopticlabs` or `madis`. * `sitinghistory` (0 \[default\], 1), Will return all historical siting metadata for each station, as a list within the `SITING` key (requires `complete=1` to be enabled). Example: `sitinghistory=1`. The following example will request all the stations in Utah with an open QC segment within the last two hours: https://api.synopticdata.com/v2/stations/qcsegments?state=ut&recent=120&token=YOUR_TOKEN_HERE The following example will request only the QC segments for air temperature at KSLC (Salt Lake City Airport) on January 3, 2015: https://api.synopticdata.com/v2/stations/qcsegments?stid=kslc&start=201501030000&end=201501032359&vars=air_temp&token=YOUR_TOKEN_HERE **Response Format Parameters** * `output` (json \[default\], xml, geojson), Indicates the response format of the request. It's recommended to use the [JSON](https://json.org/) format which there are well supported parsing libraries in all major languages. * GeoJSON will only return the best guess sensor if the station has multiple sensors of the same type. ## Request Response **JSON Format** The QC Segments 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: JSON { QC_SHORTNAMES: { 18: "ma_stat_cons_check" }, QC_SOURCENAMES: { 18: "MADIS" }, SUMMARY: { DATA_QUERY_TIME: "110.540151596 ms", RESPONSE_CODE: 1, RESPONSE_MESSAGE: "OK", METADATA_RESPONSE_TIME: "127.150058746 ms", DATA_PARSING_TIME: "1.11985206604 ms", VERSION: "v2.21.0", TOTAL_DATA_TIME: "111.660003662 ms", NUMBER_OF_OBJECTS: 1, FUNCTION_USED: "qc_segment_parser" }, STATION: [ { STATUS: "ACTIVE", MNET_ID: "195", PERIOD_OF_RECORD: { start: "2016-12-14T16:52:00Z", end: "2023-08-01T22:57:00Z" }, ELEVATION: "3885", NAME: "ARNOLD CA", QC: [ { start: "2018-01-21T17:00:00Z", qc_flag: 18, sensor: "air_temp_qc_1", end: "2018-01-21T17:00:00Z", is_open: false } ], STID: "ARLC1", SENSOR_VARIABLES: { air_temp: { air_temp_qc_1: { } } }, ELEV_DEM: "3818.9", LONGITUDE: "-120.36000", UNITS: { position: "m", elevation: "ft" }, STATE: "CA", RESTRICTED: false, LATITUDE: "38.23000", TIMEZONE: "America/Los_Angeles", ID: "42541" } ], QC_NAMES: { 18: "MADIS Spatial Consistency Check" } } * `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. * `QC[]`, contains the QC segments. * `start`, start of segment. * `end`: end time of segment. If the segment is open, the end time will be time of query. * `qc_flag`, QC check ID (see [QC Types](/services/qc-flag-types.md)). * `sensor`, sensor name and instance. * `is_open`, is the segment open or closed. * `QC_SHORTNAMES{}`, key/value pairs of QC flag IDs to short names. * `QC_NAMES{}`, key/value pair of QC flag IDs to flag's formal name. * `QC_SOURCENAMES{}`, key/value pairs of QC flag IDs to provider name. **Note**: The data in this example is simulated. --- language: "en" --- # Quality Control Types Returns details about a quality control (data attribute) flag ## Request Format https://api.synopticdata.com/v2/qctypes Returns a list of the available data checks provided by both Synoptic Data and our third party providers. For an in-depth \& technical description of the Synoptic Data data checks, [you can read here](https://docs.synopticdata.com/services/quality-control.md). This service also provides some information from third party vendors. You can also explore currently available data checks [here](https://docs.synopticdata.com/services/qc-flag-types.md). 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](https://docs.synopticdata.com/account/public-api-tokens.md). **Optional Parameters** * `shortname`, Requests a data check by its short name. This is used to target a particular test. Example: `shortname=sl_range_check` * `id`, An internal Synoptic ID number for a test or test. Example: `id=1,2,3` The following example returns basic information about the Synoptic Range Check. https://api.synopticdata.com/v2/qctypes?token=YOUR_TOKEN_HERE&shortname=sl_range_check **Response Format Parameters** * `output` (json \[default\], xml), Indicates the response format of the request. It's recommended to use the [JSON](https://json.org/) format which there are well supported parsing libraries in all major languages. ## Request Response **JSON Format** The QC Types 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: JSON { QCTYPES: [ { SOURCE_ID: "1", SHORTNAME: "sl_range_check", ID: "1", NAME: "SynopticLabs Range Check" } ], SUMMARY: { DATA_PARSING_TIME: "0.0250339508057 ms", VERSION: "v2.21.0", TOTAL_DATA_TIME: "20.8718776703 ms", NUMBER_OF_OBJECTS: 1, RESPONSE_CODE: 1, RESPONSE_MESSAGE: "OK", METADATA_RESPONSE_TIME: "0.0208418369293 ms" } } * `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`. * `QCTYPES[]` * `SOURCE_ID`, provider's ID number. See table below. * `SHORTNAME`, short name description of data check. * `ID`, data check ID. This is the ID used in reporting data attributes. * `NAME`, formal name of data check. ## Provider IDs | ID | Provider | |----|--------------| | 1 | Synoptic | | 2 | MADIS (NOAA) | --- language: "en" --- # Road surface condition codes Road surface condition codes are available via the Weather API by including `road_surface_condition` as a requested variable. This variable is reported by Road Weather Information System (RWIS) stations, commonly part of state Department of Transportation (DOT) networks. An API response including this variable might look like: JSON "road_surface_condition_value_1": { "date_time": "2020-01-06T22:36:00Z", "value": 9 } The following table provides descriptions for each code value. ## Road Surface Condition Code Values Note that some descriptions are repeated, due to the history of different road sensor types outputting different numeric codes. | Code | Description | |------|------------------| | 0 | No Report | | 1 | Dry | | 2 | Trace Moisture | | 3 | Moist | | 4 | Wet | | 5 | Chemically Wet | | 6 | Ice | | 7 | Frost | | 8 | Snow | | 9 | Slush | | 11 | Dry | | 12 | Trace Moisture | | 13 | Wet | | 14 | Chemically Wet | | 15 | Ice Watch | | 16 | Ice Warning | | 17 | Frost | | 18 | Snow Watch | | 19 | Snow Warning | | 21 | Snow/Ice Watch | | 22 | Snow/Ice Warning | | 23 | Wet Below | | 24 | Damp | | 25 | Absorption | | 26 | Error | | 27 | No Report | --- language: "en" --- # Settings and Favorites ## Favorites ![image-20250425-154816.png](https://docs.synopticdata.com/__attachments/a_341d653837361c851817c1a6912dcc4fb6956153b5426f3598f82aa9da677f34/image-20250425-154816.png?cb=043d2cb5f2bbbbd2ff4d7cba81c41302) Users with a free Synoptic account can create a library of custom visualizations from Synoptic Data Viewer's pages by saving views as Favorites. While signed in, click the Favorite icon ( ![favorite_24dp_666666_FILL1_wght400_GRAD0_opsz24.png](https://docs.synopticdata.com/__attachments/a_66494828059e2df83dd1b3c37fbfb995b7df4ee5d721923f1c0bff157d0b30f1/favorite_24dp_666666_FILL1_wght400_GRAD0_opsz24.png?cb=cec95e8aeb6dffcf62c67fafb255c464) ) in the upper right corner to save a customized visualization. Favorites can then be accessed clicking the user avatar in the upper right corner. Favorites are categorized by their respective Viewer pages. ## Global Settings ![image-20250425-154919.png](https://docs.synopticdata.com/__attachments/a_b20be5edc463fde804e1d22155dbb4ce257ba2faecc40b43cf5df30242459428/image-20250425-154919.png?cb=9f392e2d4776b1ec447d5099f224b798) Global Settings allows the user to select how the data is represented or is able to appear across all pages within Synoptic Data Viewer. Global settings are preserved for return visits for all users, and for users with a free Synoptic account, global settings will transfer across devices. ### Datetime Toggle between timestamps appearing in UTC (GMT) or station local time. Also, the option to select between the datetime formats of the 12- or 24-hour clock for local time. ### Units Variable units can be selected in Metric or English systems, or specified individually (for instance, some users may desire English units, but desire speed units in miles per hour). ### Display Change settings related to the UI and display of various elements on the Data Viewer. Select between wind barbs or arrows for wind display, and choose to show station tooltips on mouse click or hover on map displays. ### Duration Set the duration for time series across Synoptic Data Viewer's tabs to 1,3, or 7 days. Changes will affect all timeseries charts and tabular displays of timeseries data. ### Variable Group Variables groups filter the data (in the Table tab if toggled on) based on the observation needs of common use cases. To view the list of variables in a group click on ![info](https://docs.synopticdata.com/__attachments/a_3817059c778a18d3057501c200a5a0c477adc7759f0bbc8049b63af356ac78f3/atlassian-info?cb=feab5cd71111204d6b52545f3027dd0c) next to the selection dropdown. ### METAR Reports Setting METAR Reports to all returns only the high frequency observations while official only adds hourly and special reports (applicable only to the ASOS/AWOS network). ### Quality Control Mode Allows the users to toggle on/off QC which will return flags alongside potentially erroneous values ([Synoptic Data QC](https://docs.synopticdata.com/services/mesonet-data-qc.md)). There is also the ability for QC flagged values to be removed or kept. Basic, Basic + Advanced, or a custom defined set of one or more QC checks can be selected here. Basic and Advanced checks include: [Basic QC](https://docs.synopticdata.com/services/mesonet-data-qc.md#Basic-QC) * SynopticLabs Range Check * SynopticLabs Temporal Persistence Check * SynopticLabs Wind Speed vs. Maximum Gusts * SynopticLabs Wind Speed vs. Wind Direction * SynopticLabs Rate Change Check [Advanced QC](https://docs.synopticdata.com/services/mesonet-data-qc.md#Advanced-QC) * SynopticLabs Percentile High Outlier Check * SynopticLabs Percentile Low Outlier Check * SynopticLabs Spatial Percentile Check * SynopticLabs Spatial Value Check --- language: "en" --- # Station reporting status A key metadata field for stations is "Status". This field indicates whether or not the station is actively reporting observations, as received by Synoptic. Status is set to inactive after 30 days of no new data. Every 24 hours, inactive stations that have resumed reporting will be set back to active. [Next Page](https://docs.synopticdata.com/llms-full.txt/1)