Synoptic API Web Service Tutorial

Use this as a resource to familiarize yourself with the characteristics of API queries and responses.

API JSON Response Format

The default way the API sends data is JSON. This example can help you understand how the data are strutured.

JSON is described at http://www.json.org/ if you are unfamiliar. Many popular programming languages, including Python and C++ have interpreters for JSON data.

While other formats will soon be available for retrieving data (CSV, XML, etc.), JSON is the recommended format for most developers.

Components of a query

Queries are divided into two or three parts, depending on the result and the type of query.

  1. UNITS Variable Metadata (only with data queries)
  2. STATION Stations and data (present except when no stations/data were found)
  3. SUMMARY Query Summary information

Query summary

Starting in reverse, the query summary is the only element which is included in every query. There are three main forms this block can take:

{
  "SUMMARY": {
    "RESPONSE_CODE": 200,
    "RESPONSE_MESSAGE": "Authentication Failure.",
    "RESPONSE_TIME": " 0 ms"
  }
}
Failed token authentication
{
	"SUMMARY": {
	"TOTAL_TIME": "75.0072002411 ms", 
	"NUMBER_OF_OBJECTS": 0, 
	"RESPONSE_CODE": 1, 
	"RESPONSE_MESSAGE": "OK", 
	"METADATA_RESPONSE_TIME": "45.3038215637 ms"
	}
}
Zero responses resulted from a request
{
  "SUMMARY": {
  "TOTAL_TIME": "116.430997849 ms", 
  "DATA_QUERY_TIME": "72.1111297607 ms", 
  "RESPONSE_CODE": 1, 
  "RESPONSE_MESSAGE": "OK", 
  "METADATA_RESPONSE_TIME": "21.9569206238 ms", 
  "DATA_PARSING_TIME": "0.111103057861 ms", 
  "TOTAL_DATA_TIME": "72.2250938416 ms", 
  "NUMBER_OF_OBJECTS": 1, 
  "FUNCTION_USED": "sorted_time_data_parser"
 }
}
Successful query with response objects

Full Query Examples

The other two sections of query are best demonstrated with example outputs. For these and the rest of the examples in this demonstration, we will be using a formatted and interactive display of JSON data. At any time, you can click the top-right corner of the display to be shown the raw appearance of the JSON data.

Select any of the example queries to see the appearance of different kinds of queries. Using your mouse, hover over different elements of the query to see an explanation of that particular element.

Select a query type to begin
Query TypeDescription/Use
networks Information about networks
networktypes Translate the network type values
stations (metadata only) Single station metadata
stations (single observation) Station with a single observation (latestobs=1)
stations (time series observation) Station with timeseries data

Metadata Queries

Getting station metadata is simple, try it here.

Requesting station metadata is among the simplest queries avaialble. For a station where the ID is known, you simply pass the ID as a stid argument. Enhanced metadata is provided with the complete=1 argument.

https://api.synoptic.io/v2/stations/metadata?stid=&complete=&token=YourToken
Make Request!

Data Queries

See all it takes to request data from the API.

Choose the type of data request to try

Latestobs (single observation) Timeseries (multiple observations) Climatology (multiple observations over entire period of record) Statistics (aggregate statistics computed for multiple observations)

The API is designed to serve data to users, so requesting observational data from the API is very simple.

For /station data requests, there are 3 services which are involved with observation requests. Those are:

  • /timeseries, to request data within limits as specified by start and end as YYYYMMDDhhmm strings specifiying UTC bounds
  • /nearesttime, to request the observation closest to now (within=*some number of minutes*) or closest to some date/time, using the parameter attime
  • /climatology, to request data within limits as specified by startclim and endclim as MMDDhhmm strings specifying UTC bounds over every year in the archive
There are three other services besides these and /metadata under /station: /statistics, /precipitation, and /latency outlined in the documentation.

Time Zones
Observations can be returned with time stamps either in UTC, or in the local time to the station. This is controlled by the parameter obtimezone, which defaults to UTC. However, an entry of obtimezone=local will produce station local timestamps.

By default, the API will not return a station when there is no data within the time period. You can override this functionality, and return all stations within your query (as specified by any selection parameters from above) by setting the showemptystations=1.

Network Queries

Use the API to get information about station networks.

The API contains information regarding the networks within Synoptic, which can be used to better understand the stations in our network. Network queries provide a bridge between network IDs of stations, and network type IDs in network data. We will use some quick examples to show how these can be used.

Network queries have only 3 data parameters, (1) network ID (number), (2) Network shortname (shortened textual name of network), and (3) sorting order, which has 3 options: blank= by ID number, alphabet by string name, station_count= by number of reporting stations.

https://api.synoptic.io/v2/networks?id=&shortname=&sortby=&token=YourToken
Query Networks

Or, you can try a networktypes query.

https://api.synoptic.io/v2/networktypes?id=&token=YourToken
Query Network Types


Metadata-based Station Selection

Stations returned in queries are selected using station metadata. This example lets you explore how you can construct metadata queries, and what the resulting stations are.

Make Request!

Characteristic Parameter Query Value
network
Synoptic network ID (your app should learn these IDs using a single /network query).
vars
string variable IDs, only return stations that report that
status
Return only stations which are actively reporting in our system active, or the opposite inactive.
Location Parameter Query Value
state
US State, 2-letter id
county
County/parish/borough (US/Canada only), full name
radius
Distance from a lat/lon point as [lat,lon,radius (mi)]
bbox
Stations within a [lon/lat] box in the order [lonmin,latmin,lonmax,latmax] e.g. bbox=-120,40,-119,41
cwa
NWS county warning area (string)* e.g. cwa=LOX
nwszone
NWS Zone (string)* e.g. nwszone=UT003,CA041
nwsfirezone
NWS Fire Zone (string)* e.g. nwsfirezone=LOX241
gacc
Name of Geographic Area Coordination Center** e.g. gacc=EBCC
subgacc
Name of Sub Geographic Area Coordination Center** e.g. subgacc=EB07

And this is the JSON of the query you made

Several of these areas come from the National Weather Service or the National Interagency Fire Center. To determine specific values for these regions visit:
* http://www.nws.noaa.gov/organization.php
** http://gacc.nifc.gov/

Hello World code examples

Here are some examples of how to write code to interact with the API.

Using jQuery, we utilize a JSONP request, which is simply a getJSON query with a callback argument in the URL. These kinds of queries are allowed across domains (whereas regular JSON/AJAX queries must fulfill the same-origin policy).

With Python, JSON objects translate effectively to dictionaries. We just use the urllib2 library to grab the API query output, and the json library to convert the output to the dictionary object.

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.

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.

We will add more examples regularly, please check back!