get started!

API Tutorials

We have created this collection of interactive demos to help you explore and understand the API and its outputs. We update this experience often, so be sure to check back for new resources. Click on a tutorial title to expand its contents.

For code examples please view the documentation for the API product you are developing with. For a more comprehensive exploration of each API's outputs, please visit the API Explorer. For more inspiration and examples like these tutorials, check our our ever-expanding API Gallery and blog!

API JSON Response Format

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

JSON is described at 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", 
    "RESPONSE_CODE": 1, 
    "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, 
    "METADATA_RESPONSE_TIME": "21.9569206238 ms", 
    "DATA_PARSING_TIME": "0.111103057861 ms", 
    "TOTAL_DATA_TIME": "72.2250938416 ms", 
    "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.
Make Request!

Data Queries

See all it takes to request data from the API.

Choose the type of data request to try

Nearesttime Timeseries Climatology Statistics

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: multiple observations. To request data within limits as specified by start and end as YYYYMMDDhhmm strings specifiying UTC bounds
  • /nearesttime: Single observation closest to a time. To request the observation closest to now (within=*some number of minutes*) or closest to some date/time, using the parameter attime
  • /climatology: Multiple observations over entire period of record.o request data within limits as specified by startclim and endclim as MMDDhhmm strings specifying UTC bounds over every year in the archive
  • /statistics: Aggregate statistics computed for multiple observations.
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 MesoWest, 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.
Query Networks

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