An API (application programming interface) is a web service that provides you with customized data. Using an API is an easy way to get either large amounts of data from one source or to simply get a few types of data from multiple sources. Nearly every internet service out there uses an API of some sort.

To understand how SynopticLabs Mesonet API works, let’s think of it as a pizza. By combining a common set of ingredients with a varied set of toppings, each pizza has a personalized flavor. As you will see, the API is very similar. We will explain the different elements that make up every API query and some of the more common options that can be customized.

The easiest way to get data from the API is to type your requests into the URL of your web browser, which will then show the results immediately. We return data using JSON (JavaScript Object Notation), so you may want to download a browser plug-in to view the data in a clean format.

Authentication and gaining access

All SynopticLabs products require an API key because our systems are designed around a key & token methodology. We provide users with a private key that then is used to generate the tokens necessary in the API query. To get your own key, simply head to http://synopticlabs.org/api/signup/ and sign up with your email. We will immediately send you a private key in a welcome email. Once you have your private key, you can generate a token by entering the following URL in your web browser or any other HTTP client.

https://api.mesowest.net/v2/auth?apikey=YOUR-API-KEY-HERE

You should see a response similar to

{ TOKEN: "tk2016jun1616ylsFT0PRmJ4gbGSL3qT74" }

This token can be used in your data requests. Every request to any of our APIs requires &token=YOUR-TOKEN-HERE somewhere in the URL as a way to authorize the query.

If you forget or lose your key or token, you can view them from our account manager page (a link to your account page is also included in your API welcome email): http://synopticlabs.org/api/account/

Note: Your key is to be kept private and is only used to generate tokens

You can use one token every time you access the API. However, developers expecting to embed API calls into other software may want to use a separate token for each usage type.

Also, if you want to try out the API as you browse through the following, use the &token=demotoken. However, that token provides limited functionality and shouldn’t be used for any but the most basic testing.

Constructing your request

All data requests to the Mesonet API begin with this root URL address:

https://api.mesowest.net/v2/

From this root address, you will then add the service and resource you are interested in. For example users interested in station weather data for a given period would utilize the service /station and the resource /timeseries. Below is a summary of the services available:

Service Description
/networks Queries networks and basic network information based on their MesoWest Network ID
/networktypes Returns the type of network (state, federal, agricultural, air quality, etc)
/variables Returns a list of all possible variables and their units
/stations Returns information about a station or returns reported observations (see below)

After selecting the service, users will then choose the resource that fits their data needs. Each service has a specific set of resources that can be applied. A complete guide to the resources and services can be found at Mesonet API Reference page http://synopticlabs.org/api/mesonet/reference/. In this guide we will discuss the most common service /stations which returns information about stations or observations from a station. Below are the resources for /stations:

/stations Services Description
/metadata? Returns station metadata (name, latitude/longitude, elevation, timezone, etc.)
/nearresttime? Returns either latest observation, observation closest to a time (before or before and after)
/timeseries? Returns based on a start and end date/time
/climatology? Returns climatological data for a station over every year of available data
/statistics? Returns statistics about timeseries or climatology of data (count, min/max, standard deviation, median, or mean)
/precip? Returns accumulated precipitation for a station during a specified time frame.

There are many more types of queries you can make using the Mesonet API. You can read our full documentation http://synopticlabs.org/api/mesonet/

So to construct our API request, we begin the the root URL that tells our computer where to get the data:

https://api.mesowest.net/v2/

From here you choose the resource and service. For example if you want a time series of data values from a station, you would use the following base URL with the service /station and resource timeseries appended:

https://api.mesowest.net/v2/station/timeseries?

Note that after the resource, a question mark ? is added to the URL address. From this point on you can add all sorts of options to your query. Below is a common list of options our users request.

Parameter Description
&output= Returns data output as JSON, geoJSON, CSV, or XML
&units= Returns data in English or Metric units
&stid=
&state=
&county=
Query either a single station or by geographical region
&radius= Query stations with a radius of a Lon/Lat or stid
&start=
&end=
Time frame for data requested
&sortby=alphabet Sort the returned list alphabetically
&vars= Return on certain variables, i.e. air temperature. For a listing of all variables go to http://synopticlabs.org/api/mesonet/variables/.

Putting these components all together, we can now do the following request to get the most recent 120 minutes of temperature data from the Salt Lake City Airport (KSLC), returned in CSV format with

https://api.mesowest.net/v2/station/timeseries?&stid=kslc&recent=120&output=csv&vars=air_temp&token=YOUR-TOKEN-HERE

Note: /stations/timeseries? is the only service that can return data in a CSV format.

Returning to our pizza analogy, we can now see that building an API query involves several elements, some that remain constant (like the crust and cheese) and some that have several options to choose from (like the sauce and toppings). Our API query will always need to have the base URL string https://api.mesowest.net/v2/ and our authorization token &token=YOUR-TOKEN-HERE. With those components in place, we can then choose which resource or service will get us the data we want and further customize our request with as many parameters as we need.

Exploring further

To see how API requests can be made and include various components, we have an API Explorer that can assist you in building query URL’s to use in your web browser or computer program. To use the API Explorer, go to: http://synopticlabs.org/api/explore/. If you use your own token rather than the demotoken, then the Explorer will provide access to many of the API features.

For more information about the API, please review the following resources: