get started!
SynopticLabs APIs Guides

Get Started with Our APIs

Welcome to the SynopticLabs APIs!

With the SynopticLabs APIs, you can quickly, easily, and flexibly integrate the data collected by MesoWest and SynopticLabs over the past 18+ years into your own work and applications.

After you have read this guide, we suggest you visit the API product list to access the specific guides and information about each of our APIs. Use the signup form to obtain your own API key.

Before you start

Our APIs are designed for software-minded users, if you are not comfortable using code to get the data you need, you might want to use some of our web portals to view and download our data. You are also welcome to contact us at help@mesowest.org and we can help you get started with our APIs.

MesoWest Download pages

What are the APIs?

Our APIs are REST-ful (learn more about that here) web services that give data in response to requests sent to specific resources, with specific argument parameters. A resource is what looks like the directory structure of a normal web page. /stations/metadata is one resource in Mesonet API for example.

Arguments are given to an API resource using query string parameters like this resource?&parameter=.... Our APIs just sit and wait for users to ask for information, and then they act quickly to gather and package that information in the format the user requested.

Since the APIs output only data, they are ideal for computer program or application. Instead of a webpage which has both information and styles, APIs do not style the data. Our APIs provide an absolute minimum amount of information required to understand and use the data returned.

How to "request" data

The most direct way to request data is by typing a URL into your web browser's navigation bar. In fact, for all of our APIs, if you type the API base URL (e.g. http://api.mesowest.org/v2), append a resource (e.g. /something/something_else,) and appropriate query string parameters into your browser's URL bar, then we will return data to your browser. For testing, using that simple approach is a great way to see what an API returns for different inputs. When using the API for your projects, this requset URL can simply be used in your code.

This is called a GET request, and it is the only HTTP protocol (form of request) our APIs support (as opposed to POST or HEAD etc.). You should use computer software to make the HTTP requests from our API, and we will deliver data to you corresponding to the parameters you passed. To help you do that, we have prepared code examples as part of the tutorials in a diverse set of programming languages.

Where are our APIs?

SynopticLabs is developing a number of APIs for different purposes. At the moment, only one API is publicly exposed and documented; that API is Mesonet API. A research version of Mesonet API is available through MesoWest & SynopticLabs and the production version of that API for customers needing an enterprise level of service is available from SynopticData (http://synopticdata.com)

Mesonet API

Mesonet API serves GET requests for the observation data from networks of in-situ tower mounted sensors. Data are available from the entire period of record at MesoWest/SynopticLabs through the present. The current operating version of Mesonet API is v2. All resources for Mesonet API can be requested from this address:

http://api.mesowest.net/v2

To learn all of the resources available from Mesonet API, please read the reference manual.

Authenticating your requests

We use a simple token authentication when you request data from any of our APIs. This means that one of the arguments you pass to the API must be a string of characters and numbers which is an API token you have created or been given. Here's a quick example of a query using an API token.

GET http://api.mesowest.org/v2/variables?&token=<your token>

Learn more about authenticating with tokens in the Authentication & tokens guide. For testing, feel free to start with the demotoken. Use our simple signup form to obtain an API key that allows you to access the full functionality of our APIs.

Parameters & Arguments

API resources use parameters to provide you with the data in the manner you prefer. While some APIs contain parameters within the resource path (or URL), most are passed as named arguments on the end of the URL string, known as query string parameters (QSPs). For example:

http://api.mesowest.net/v2/networks?token=sometokenstringvalue&sortby=alphabet

In this example, there are two arguments: token which is for authentication, and sortby which changes the output of the API resource. QSPs are separated by ampersands (&), and you begin the set of parameters with a ?. This is why we sometimes list a resource name ending in a question mark, as it is required before parameters can be passed.

Passing multiple arguments

You can specify any number of QSPs (there is a limit on the length of an API request enforced by some web browsers, so keep that in mind if you are building a web app), but you should only specify a single argument once. If you specify the same argument multiple times, the last time it is specified will (usually) be the value used, but this behavior is intentionally inconsistent, and should not be used. Here is an example of what not to do:

GET http://api.mesowest.net/v2/stations/metadata?token=...&stid=KJFK&stid=KLGA

Specifying multiple values for a single argument

Instead of including the same argument multiple times, many inputs support comma-separated input values. Though this behavior is controlled by the design of the specific API, comma-separated values with or without spaces are usually valid inputs for arguments that can accept them.

An example argument (related to the example above) would be asking for multiple station IDs. The supported way to do this is

GET http://api.mesowest.net/v2/stations/metadata?token=...&stid=KJFK,KLGA

Mandatory arguments

A number of resources have arguments that are mandatory. Without these arguments the API will not be able to understand your request. One example of this is the &token= argument for any API which uses tokens in query strings for authentication. You cannot receive data without authenticating, so this argument must be present.

Another example would be the /stations/timeseries resource on Mesonet API. This resource requires at least one input (beyond authentication) to know what period to use when selecting the timeseries of values. If you request /stations/timeseries without specifiying the start and stop times in some way, it cannot process your request.

Responses

Because our APIs are all built around the principle of delivering data to users, we support a diverse collection of output formats and protocols. Most of our APIs, and all of our non-data resources (such as /auth) return data in the popular JSON data type.

JSON

JSON is a broadly-readable, flexible and powerful data type that returns data in strings as lists and dictionary type data structures. Each API and each resource has its own JSON structure, which is described in detail in the API's documentation. Review the descriptions and reference documents for each API to learn about the JSON structure for that API.

GeoJSON

Like JSON, a number of our services support the GeoJSON format, which produces output that can be immediately interpreted by a number of GIS applications. Because it is a stricter format, there is a limit on the amount of data we can include in a GeoJSON request, so the format is only offered for a limited number of data requests.

XML

Some services also offer XML output, which is another popular and broadly readable data format. Our XML output for most services is a direct match of the JSON structure, as the two have a similar approach to collections of values.

CSV

Though popular, we only serve CSV data from a very limited set of API resources. CSV data, while incredibly easy to use, lacks the ability to pass nested object type data. We are working to expand the number of CSV output formats we support, but at the moment support is very limited.

CSV is an ideal format for serving very large amounts of data. As a result, the Mesonet API timeseries service requires CSV output format for requests resulting in more than 100,000 station-hours of data response. For example, that limit would be reached by requesting more than 11.4 years of data from one station or 5.7 years of data from two stations.

Response & Code Examples

Since the output varies from one API to another, we supply output and example codes within the documentation for each respective API. Just look at the API's home page or reference documentation to get to it.

Limits and throttling

In order to keep our APIs operating efficiently for all users, we limit responses to one concurrent request at a time. You can make a request while another request is being handled, but it will wait to be addressed until the previous one is completed. If there are more than 10 requests waiting to be handled, we will immediately reject new queries until earlier ones have been processed.

When you start experimenting with the API, we allow you to use our global demotoken API token, however, the demotoken is restricted to satisfy only very limited requests, so please obtain your own token right away.

Timeouts

Sometimes if a request takes too long, our network will timeout before we are able to return your data. No data request through our APIs should result in a timeout, but if you have numerous requests queued, some of the later requests may time out because of network protocol standards, and the time it takes to handle the requests ahead of that one.

Timeouts may also be caused by disruptions in either your network or ours. These instances will produce clear timeout errors, and while we do monitor these incidents, we encourage users to contact us in the event of repeated network timeouts.

Errors

We return errors to users when they make invalid requests, make requests that cause the API to misbehave, or the API encounters an unexpected problem when handling a valid request. We attempt to respond to all errors with both HTTP response codes and JSON outputs. Users who are seeing errors returned from their API requests should review the error documentation for the API web service they are using.

Some errors may occur in ways we never anticipated, and as a result may return only an HTTP 5xx error. In these cases, we request that users report these un-gracefully handled errors back to the API developers via our contact address at help@mesowest.org.

Downtime

The SynopticLabs APIs are constantly being improved and there is always a chance that some features might be temporarily broken during development. If outages of any type are an issue to your applications, we encourage you to use the SynopticData APIs that are developed to meet that level of service. Contact Synoptic for information about accessing that API.

Support

We are able to provide a reasonable amount of assistance to users of our API services. Before contacting us at help@mesowest.org, we request that you familiarize yourself with our documentation and descriptions related to common errors for the resource you are using. More complex queries about usage of the API services and environmental data can also be address by SynopticData staff.

The Future

As a research and development environment, the APIs available from SynopticLabs are regularly receiving updates and improvements. Many of these either improve reliability or make existing services more useful. We strive to notify our users via social media and opt-in emails of big and small updates to the functionality of our APIs.

In the future we are going to be adding the following API resources or services:

And many more that we aren't quite ready to share with the world!

What's next?

Now that you've made it through the get started guide, get started using our APIs by