Developers
Mesonet API
  • Getting Started
  • Reference
  • Explorer
  • Examples
  • Pricing
  • Getting Started with the Mesonet Web Services

    How to get started

    Getting Set up

    All of the Mesonet web services use JSON as the default response format. JSON (JavaScript Object Notation) is the defacto standard of moving data across the web. There are many tools you can use to inspect JSON data, or you can just view the response right in your web browser, but we find it’s helpful to install a JSON viewing utility. Some common JSON viewers are:

    Gaining access

    When you sign up to use the Mesonet API, you will receive an API key. If you already have a key, just skip down to creating a token.

    Sign up for data access credentials

    If you do not have Synoptic data access credentials you can sign up for them here. This is a private key that is used to generate tokens for your applications. You are only assigned one key to your account, so you will want to keep this safe. Never code this key into your applications.

    Creating a token

    Once you have an API key, a token will be automatically generated for you. You are allowed to create as many additional tokens as you’d like using your API key. Tokens are what we use to authenticate your account when requesting data. If a token becomes compromised, simply delete it and create a new one. Creating tokens is easy with our our Authentication API. In your web browser copy the following URL and fill in the YOUR_API_KEY with the one you received in your email.

    When encoding URLs all parameters are separated using the ampersand (&) and their value is indicated by an equal sign (=). The first parameter is preceded by a question mark (?)

    https://api.synopticdata.com/v2/auth?apikey=YOUR_API_KEY
    

    Tip: To see which tokens are associated with an API key, just add the parameter list=1 to the request.

    At this point you should see a response that looks similar the response below. You will need to copy this token somewhere, as we are going to use it throughout the following examples.

    {
      "TOKENS": ["a6a82dddc14a46c892077bded6f5a3d6"]
    }
    

    Determining which service to use

    When deciding which Mesonet service to use the biggest questions are:

    The most services are Time Series, Latest and Nearest Time and Metadata. Each fills a certain need and are described below.

    Constructing a request

    Mesonet web services are REST APIs, meaning that each request is stateless and only represents the arguments within the request. A request is just a URL that contains the URL of the service being requested, a token and any additional parameters. Constructing a request URL is simple. Often the best tool for experimenting with these services is just using the address bar of a web browser.

    Note: For some services such as Latest and Metadata the omission of selection parameters will return data from every available station in the inventory.

    The base URL for all services is https://api.synopticdata.com/v2/. From this point you can access all the public services. Now just add the service you wish to access. This example will use the Time Series service i.e. stations/timeseries. Then add parameters to reduce the data returned to what you care to see.

    Tip You can quickly look for stations near either a known station or a lat/lon set. For example: https://api.synopticdata.com/v2/stations/metadata?token=demotoken&radius=33.704,-112.014,10&limit=10 will return the 10 closest stations to a radius of 10 miles of downtown Phoenix, Arizona.

    // Make sure you view this on a screen wide enough to not word wrap
    
                    Base URL                   Stations we want returned (comma separated)
                        |                                      |
                        ▼                                      ▼
    https://api.synopticdata.com/v2/stations/timeseries?stid=mtmet,nahu&token=YOUR_TOKEN_HERE&recent=15
                                      ▲                  ▲                ▲         ▲
                                      |                  |                |         |
                                      |                  |          token parameter and token
                        'stations/latest' API            |
                                          station ID (stid) parameter
    

    Understanding the response

    Every non CSV request to a Mesonet API will yield a response with at a minimum a SUMMARY section and status code. A Time Series request with the following URL would return a result similar to:

    https://api.synopticdata.com/v2/stations/timeseries?stid=mtmet&start=201701030830&end=201701030930&vars=air_temp,volt&token=YOUR_TOKEN_HERE
    
    {
      "UNITS": {
        "position": "ft",
        "air_temp": "Celsius",
        "elevation": "ft",
        "volt": "volts"
      },
      "QC_SUMMARY": {
        "QC_TESTS_APPLIED": ["sl_range_check"],
        "TOTAL_OBSERVATIONS_FLAGGED": 0,
        "PERCENT_OF_TOTAL_OBSERVATIONS_FLAGGED": 0
      },
      "STATION": [
        {
          "STATUS": "ACTIVE",
          "MNET_ID": "153",
          "PERIOD_OF_RECORD": {
            "start": "2012-04-26T00:00:00Z",
            "end": "2018-01-21T21:35:00Z"
          },
          "ELEVATION": "4996",
          "NAME": "U of U Mountain Met Lab",
          "RESTRICTED": false,
          "STID": "MTMET",
          "SENSOR_VARIABLES": {
            "date_time": {
              "date_time": {}
            },
            "volt": {
              "volt_set_4": {},
              "volt_set_3": {},
              "volt_set_2": {},
              "volt_set_1": {
                "position": "0"
              }
            },
            "air_temp": {
              "air_temp_set_1": {
                "position": "8"
              }
            }
          },
          "ELEV_DEM": "4993",
          "LONGITUDE": "-111.828211",
          "STATE": "UT",
          "DATA_AFFECTED": false,
          "QC_FLAGGED": false,
          "LATITUDE": "40.766573",
          "TIMEZONE": "America/Denver",
          "ID": "33898",
          "OBSERVATIONS": {
            "date_time": ["2017-01-03T08:30:00Z", "2017-01-03T08:35:00Z", "2017-01-03T08:40:00Z", "2017-01-03T08:45:00Z"],
            "volt_set_4": [13.5, 13.51, 13.61, 13.61],
            "volt_set_3": [12.26, 12.26, 12.26, 12.26],
            "volt_set_2": [14.4, 14.4, 14.4, 14.4],
            "volt_set_1": [13.54, 13.55, 13.55, 13.55],
            "air_temp_set_1": [-4.82, -4.87, -4.89, -4.89]
          }
        }
      ],
      "SUMMARY": {
        "DATA_QUERY_TIME": "8.29005241394 ms",
        "RESPONSE_CODE": 1,
        "RESPONSE_MESSAGE": "OK",
        "METADATA_RESPONSE_TIME": "0.0929832458496 ms",
        "DATA_PARSING_TIME": "0.491142272949 ms",
        "TOTAL_DATA_TIME": "8.78214836121 ms",
        "NUMBER_OF_OBJECTS": 1,
        "FUNCTION_USED": "time_data_parser"
      }
    }
    

    Here’s an explicit breakdown of the response above.

    CSV users

    Currently only the Time Series service supports CSV (Comma Separated Values) output. If you would like the CSV output, just add output=csv to the URL request. The same request above in CSV format would like like:

    # STATION: MTMET
    # STATION NAME: U of U Mountain Met Lab
    # LATITUDE: 40.766573
    # LONGITUDE: -111.828211
    # ELEVATION [ft]: 4996
    # STATE: UT
    Station_ID,Date_Time,air_temp_set_1,volt_set_1,volt_set_2,volt_set_3,volt_set_4
    ,,Celsius,volts,volts,volts,volts
    MTMET,2017-01-03T08:30:00Z,-4.82,13.54,14.4,12.26,13.5
    MTMET,2017-01-03T08:35:00Z,-4.87,13.55,14.4,12.26,13.51
    MTMET,2017-01-03T08:40:00Z,-4.89,13.55,14.4,12.26,13.61
    MTMET,2017-01-03T08:45:00Z,-4.89,13.55,14.4,12.26,13.61
    MTMET,2017-01-03T08:50:00Z,-4.92,13.55,14.4,12.26,13.49
    MTMET,2017-01-03T08:55:00Z,-4.93,13.54,14.4,12.26,13.62
    MTMET,2017-01-03T09:00:00Z,-4.94,13.55,14.4,12.26,13.51
    MTMET,2017-01-03T09:05:00Z,-4.96,13.55,14.4,12.26,13.53
    MTMET,2017-01-03T09:10:00Z,-4.97,13.55,14.4,12.26,13.62
    MTMET,2017-01-03T09:15:00Z,-4.98,13.55,14.4,12.26,13.53
    MTMET,2017-01-03T09:20:00Z,-5.01,13.54,14.4,12.26,13.5
    MTMET,2017-01-03T09:25:00Z,-4.99,13.55,14.4,12.26,13.61
    MTMET,2017-01-03T09:30:00Z,-4.97,13.55,14.4,12.26,13.51
    

    The first six lines are metadata about this station and they are noted by the comment indicator (#). Line seven and eight are the column name and unit of measure respectively.

    Fin

    We hope this tutorial has been helpful. If you made it this far, then you’ve got the basic skills to start exploring the Mesonet services and using real-time and historical data in your applications.

    Some further reading: