Precipitation

Returns derived precipitation totals or intervals for a requested time period and set of stations. This service encompasses Synoptic's Advanced Precipitation Service.

Request Format

A Precipitation request is an HTTP URL with the following form:

NONE

https://api.synopticdata.com/v2/stations/precip

Acquiring data from this web service requires certain parameters. When encoding URLs, all parameters are separated using the ampersand (&) character and their value is indicated by an equal sign (=). Below is a list of accepted parameters.

token (required), Your application’s API token. This is used to identify who is requesting API data. You are never required to use multiple tokens, but you can use as many as you need. Learn more in our tokens overview.
Any number of station selection parameters (optional). Including no station selections will return results for all stations. This can result in extremely large results for services that support it.

Station Selection Parameters

These selectors individually or combined to target the desired stations.

Exclusion Operator

Selectors noted as (excludable) may be specified with a ! preceding a value to remove/exclude from the selection from a result set. So stid=!KSLC would prevent KSLC from returning in a query. This should be used in combination with different selectors. Remember to only include any given selector once.

stid

(string, excludable), Single or comma separated list of SynopticLabs station IDs. Use a ! before any value to exclude matching stations. Example: stid=mtmet,kslc,fps. Try it Now

state

(string, excludable), Single or comma separated list of abbreviated 2 character states. If country is not included, default is United States (US). Use a ! before any value to exclude matching stations. Example: state=ut,wy,dc.

country

(string, excludable), Single or comma separated list of abbreviated 2 or 3 character countries. Use a ! before any value to exclude matching stations. Example: country=us,ca,mx.

nwszone

(string, excludable), Single or comma separated list of National Weather Service Zones. Use a ! before any value to exclude matching stations. Example: nwszone=UT003,CA041.

nwsfirezone

(string, excludable), Single or comma separated list of National Weather Service Fire Zones. Use a ! before any value to exclude matching stations. Example: nwsfirezone=LOX241

cwa

(string, excludable), Single or comma separated list of National Weather Service County Warning Areas. Use a ! before any value to exclude matching stations. Example: cwa=LOX.

gacc

(string, excludable), Single or comma separated list of Geographic Area Coordination Centers. Use a ! before any value to exclude matching stations. Example: gacc=GB.

subgacc

(string, excludable), Single or comma separated list of Sub Geographic Area Coordination Centers. Use a ! before any value to exclude matching stations. Example: subgacc=EB07.

county

(string, excludable), Single or comma separated list of counties. Use the state parameter to filter by state in the case of duplicate county names (i.e. “King”). Use a ! before any value to exclude matching stations. Example: county=king&state=wa.

vars

(string), Single or comma separated list of sensor variables found here. The request will return all stations matching at least one of the variables provided. This is useful for filtering all stations that sense only certain variables, such as wind speed, or pressure. Do not specify vars twice in a query string. Some web services use this argument to adjust what information is delivered. Example: vars=wind_speed,pressure. Try it Now

varsoperator

(string), Define how &vars is understood. or (the default) means any station with any variable in the list is used. and means a station must report every variable to be included. Example: varsoperator=and.

network

(number, string, excludable), Single or comma separated list of network IDs or short names. The ID can be found be using the Networks service and are also listed here. Use a ! before any value to exclude specific networks from a result set. Example: network=153 or network=uunet,raws.

radius

(string), A comma separated list of three values of the type [latitude,longitude,miles] or [stn_id,miles]. Coordinates are in decimal degrees. Returns all stations within radius of the point (or station, given by the station ID) and provides the DISTANCE of the station from given location with units of miles. Adding limit=n to the query will limit the number of returned stations to n stations, and will order the stations by DISTANCE. Some examples are: radius=41.5,-120.25,20, radius=wbb,10, radius=41.5,-120.25,20&limit=10.

bbox

(string), A bounding box defined by the lower left and upper right corners in decimal degrees latitude and longitude coordinates, in the form of [lonmin,latmin,lonmax,latmax]. Recall that for regions involving the western and southern hemispheres that the coordinates are negative values (e.g., 120 W is -120, 20 S is -20). Example: bbox=-120,40,-119,41.

Bounding Box Thinning

A new feature allows you to use the API to thin the returned station set within a bounding box by providing some additional arguments. These arguments only take effect when the bbox parameter is used:

height

(number) the height of the map viewport in pixels

width

(number) the width of the map viewport in pixels

spacing

(number) the preferred number of pixels a station on the map should consume

networkimportance

(numbers, comma-separated) a list of comma separated network IDs that will be considered in the order provided. When there is a collision of stations within the defined “spacing” area, any station matching the list of preferred networks will be shown over any other.

status

(string), A value of either active or inactive returns only stations that are currently set as active in the archive. By default, omitting this parameter will return all stations. Example: status=active.

complete

(1, 0 [default]), A value of 1 or 0. When set to 1 an extended list of metadata attributes for each returned station is provided. This result is useful for exploring the zones and regions in which a station resides. Example: complete=1.

fields

(string), Case-insensitive comma-separated list of metadata attributes to include in the output response. Default is to include all attributes. Only works with attributes defined in the default metadata set (e.g. attributes shown via complete=1 cannot be selected). Example: fields=stid,name.

Either start and end or recent (one is required but not both)
start & end, Defines the start and end time of the request with the form of YYYYmmddHHMM. Where YYYY is year, mm is month, dd is day, HH is hour, and MM is minutes. The start parameter must be used with the end parameter. For example: start=201306011800&end=201306021215.

All times are requested in UTC, but may be returned in either UTC or local time format for each station. See the obtimezone parameter.

recent, Indicates the number of minutes to return, previous to the current time. For example: recent=120 will return the last two hours of observations.

Optional Parameters

pmode (totals, intervals, last), defines the interval mode to calculate precipitation. If omitted the default is totals, however the returned JSON formatting will be significantly different. (See JSON Format examples below)
- pmode=totals, Returns totals for the start and end dates.
- pmode=intervals, Returns accumulated precipitation for intervals provided in the additional interval argument. Valid keywords for interval are hour, day, week, month, year, or non-zero integer in hours. Integers must be a factor or multiple of 24 (1,2,3,4,6,8,12,24,48,72,etc). Default value is day if interval is not provided. Partial intervals at the end of a requested range are still returned. Note that all keywords or integers provided to interval will use UTC time zone to define the start and end of each interval. However, each interval respects the requested start hour such that intervals can be offset for a local time zone.
- pmode=last, Returns accumulated precipitation intervals based on end date. The additional accum_hours argument accepts a comma separated list of hours, starting from end and moving back through time. If accum_hours is omitted the default is 1. If a start value is given, it is ignored. If end is omitted, the default is “now”. Each interval always ends on the end date.
obtimezone (UTC [default], local), Indicates if the time zone of the response is in UTC or the local time zone of the station. Sets the time zone applied to the observation output (input times associated with start and end are always UTC). Example: obtimezone=local
showemptystations (0 [default], 1), Indicates if stations with no observations will be returned. Setting to 1 will return any station meeting the defined time period, variables, and geographic or network parameters, even if there are no observation data available.
units (metric [default], english, [custom format]), Defines the unit of measure for returned data. For standard measurements used by many in North America english will fill most needs. There is also the ability to support custom unit configurations. This is achieved by accessing the variable group such as “temp” and setting the desired unit using a pipe (|) character. The following list describes the available units for each variable group.
- precip (mm, cm, in), Precipitation: Millimeters, centimeters, inches.
interval_window, defines a time window (hours) to allow returned intervals that are less than and/or greater than the requested interval. This parameter is useful for stations that may not report at regular frequency, resulting in variable interval durations between reports. Only applicable with pmode=intervals requests, and can be passed as a single argument or as two comma-separated args that define windows specific to shorter and longer allowed intervals. For example, interval_window=0 returns interval data that only match requested interval. interval_window=0,1 returns intervals at requested interval, but will return intervals up to duration of interval + 1 hour in the case that duration of interval is not available. Default value is interval_window=0.5,0.5, which returns interval data between interval - 0.5 hours and interval + 0.5 hours if interval data at the requested interval are not available.
all_reports (0 [default], 1), Indicates if reports from all available precipitation variables should be returned. Some networks (such as ASOS/AWOS) can report precipitation in multiple forms (e.g. precip_accum_one_hour and precip_accum_six_hour). By default, the precipitation service will use the single most representative and consistently reporting variable to calculate derived precipitation.

Note: If a station has moved >5 km during the requested time range, precipitation for the most recent location will be returned.

The following example requests precipitation from from stid=wbb for all of January 2017 in terms of day intervals.

CODE

https://api.synopticdata.com/v2/stations/precip?stid=wbb&start=201701010000&end=201702010000&pmode=intervals&interval=day&token=YOUR_TOKEN_HERE

Response Format Parameters

timeformat, Defines a time format that all time stamps in the data response to be formatted to. By default the API will return time values in ISO 8601 format. This behavior can be changed by passing a string with a valid strftime expression. Below are some common examples.
- timeformat=%m/%d/%Y at %H:%M would yield “06/22/2017 at 17:06”
- timeformat=%b%20%d%20%Y%20-%20%H:%M would yield “Jun 22 2017 - 17:06”
- timeformat=%s returns Unix/POSIX time in terms of seconds (this parameter cannot be used with obtimezone). This is a special function in addition to the supported strftime arguments.
output (json [default], xml), Indicates the response format of the request. It’s recommended to use the JSON format which there are well supported parsing libraries in all major languages.

Request Response

JSON Format

The Precipitation service will return its results in a single organized and self describing JSON object. At a minimum, every request will return a JSON object with a "SUMMARY" field.

An example JSON response would be:

JSON

{
  "UNITS": {
    "precipitation": "Millimeters"
  },
  "STATION": [
    {
      "STATUS": "ACTIVE",
      "MNET_ID": "153",
      "PERIOD_OF_RECORD": {
        "start": "1997-01-01T00:00:00Z",
        "end": "2018-01-10T12:00:00Z"
      },
      "ELEVATION": "4806",
      "NAME": "U of U William Browning Building",
      "RESTRICTED": false,
      "STID": "WBB",
      "ELEV_DEM": "4738",
      "LONGITUDE": "-111.84755",
      "STATE": "UT",
      "LATITUDE": "40.76623",
      "TIMEZONE": "America/Denver",
      "ID": "1",
      "OBSERVATIONS": {
        "precipitation": [
          {
            "count": 12,
            "first_report": "2017-01-31T23:00:00Z",
            "interval": 1,
            "report_type": "precip_accum_five_minute",
            "last_report": "2017-01-31T23:55:00Z",
            "total": 0
          }
        ]
      }
    }
  ],
  "SUMMARY": {
    "DATA_QUERY_TIME": 169.8219776154,
    "RESPONSE_CODE": 1,
    "RESPONSE_MESSAGE": "OK",
    "NUMBER_OF_OBJECTS": 1
  }
}

If pmode is omitted, the OBSERVATIONS block will be of this form (to comply with legacy output formats):

JSON


  "OBSERVATIONS": {
    "ob_start_time_1": "2017-01-31T23:00:00Z",
    "total_precip_value_1": 0,
    "ob_end_time_1": "2017-01-31T23:55:00Z",
    "count_1": 12
  },

SUMMARY[]
- NUMBER_OF_OBJECTS, (always returned) is a integer value of the number of stations returned.
- RESPONSE_CODE, (always returned) is a numerical code indicating the status of the request.
  - “1” = “OK”
  - “2” = “Zero Results”
  - “200” = “Authentication failure”
  - “400” = “Violates a rule of the API”
- RESPONSE_MESSAGE, (always returned) is a string explaining the RESPONSE_CODE.
- RESPONSE_TIME, (always returned) server time to process the request.
STATION[]
- OBSERVATIONS[], contains all the observational data.