Probabilistic Hourly Forecast

Overview

HTTP Headers and Data Lifetime - Caching and Expiration

For details on appropriate header values as well as caching and expiration definitions, please see The Weather Company Data | API Common Usage Guide.

Note:

Due to throttling, there are limitations to the use of this API. The following errors may be returned. If an API call results in one or more of these errors, it is recommended that several minutes be allowed to pass before re-attempting the call:

1. Error 401 - Request rates exceeded
2. Error 403 - Request rates exceeded
3. Error 509 - Bandwidth limit exceeded

Valid Parameter Definitions

Parameter: discretePdfs

The full, discrete PDF (Probability Distribution Function). Describes the likelihood of the full set of possible outcomes at user-defined discretization. Defined in statistical terms, the PDF is a function that describes the relative likelihood of a random variable to take on a value in any of a set of distinct possible outcomes. In the context of the Probabilistic Forecast the “random variable” is the parameter we’re requesting a forecast for (e.g. temperature or qpf), and from a product standpoint the PDF output would answer the question of “what percentage of the ensemble member forecasts of the requested variable (e.g. temperature, qpf, etc) fall within a certain output range or bin for that variable”.

For instance, if a request was made for the PDF of qpf with the input arguments of [.01, .05, .25], it would be asking for the (approximate) percentage of the ensemble member forecasts that fall in the range -infinity to .01, .01 to .05, .05 to .25 and .25 to +infinity. The values (percentages) returned by the Probabilistic API always sum to 100 as the PDF encompasses all possible forecast outcomes from the ensemble.

There are two ways to specify the discretization of the output PDF. All have a similar foundation of a semicolon separated list of parameters, for which to return the discrete PDF. Further decoration of the parameter name implicitly selects the method by which the PDF is discretized:

1. Decorating with a single decimal facilitates the specification of a constant bin width, in parameter appropriate units, consistent with units specified in the request. Number of bins and sequence of bin sizes are chosen appropriately based on the parameter range and specified bin size. There is no default bin size.
   • Format: param0:binSize0; param1:binSize1
   • Example: ...<product>?discretePdfs=temperature:0.5;qpf:0.5

1. Decorating with 2 or more colon separated decimal values or 1 or more triplets defined below, facilitates specification of each bin edge explicitly. The edge values must be provided in the units specified in the request. A triplet is in the form of lowerBound, increment, upperBound where the elements of the triplet are separated by a comma. The sequence of edge specifications is piecewise continuous.
   • Format: param0:e0:e1:…en; param1: e0:e1:…em
   • Example: ...<product>?discretePdfs=temperature:22.0:23.0:24.0.;qpf:0.01:0.5:1.0:4.0

1. Decorating with “fine”, “medium” or “coarse” facilitates specification of predefined bin ranges, which range from narrow (fine) to wide (coarse) in precision. The bin ranges are provided below. In the case of temperature, number of bins and sequence of bin sizes are chosen appropriately based on the parameter range and specified bin size.The predefined bin ranges are translated into purely numeric bin ranges as described in #1 and #2 in this section using the discretePdfs predefined bin ranges.

• Format: param0:predefined0; param1:predefined1
• Example: ...<product>?discretePdfs=temperature:coarse;qpf:fine

- Minimum Bin Width:

• ceiling: 50 ft or 25 m
• temperature: 0.1deg F or C
• temperatureDewPoint: 0.1deg F or C
• qpf: 0.005in/hr or 0.125mm/hr
• relativeHumidity: 1%
• Visibility: 0.06 statute mi or 0.1 km
• windSpeed: 0.1 m/s or 0.25 mph
• windGust: 0.1 m/s or 0.25 mph
• windDirection: 5 degrees
• qpfSnow: 0.1cm or 0.025 inches
• The maximum number of edges supported is 103 if bins are explicitly defined by the caller by means of edge values.

temperature Predefined Bin Ranges

temperatureDewPoint Predefined Bin Ranges

qpf Predefined Bin Ranges

Wind Speed Predefined Bin Ranges

windDirection Predefined Bin Ranges

relativeHumidity Predefined Bin Ranges

qpfSnow Predefined Bin Ranges

ceiling Predefined Bin Ranges

visibility Predefined Bin Ranges

windGust Predefined Bin Ranges

Parameter: Percentiles

Percentiles of the distribution. Some users find value in requesting information about percentiles of the distribution. A percentile is a measure used in statistics indicating the value below which a given percentage of observations (or forecasts) in a group of observations (forecasts) fall. For instance, the 30th percentile is the value below which 30% of forecasts fall. In the context of Probabilistic temperature forecasts, the 30th percentile temperature forecast is (approximately) the value in the Probabilistic ensemble in which the 30% of the forecasted temperatures are cooler.

1. When specifying a percentiles parameter value, a semicolon separated list of parameters is used for which to return percentile values, along with a colon separated list of desired percentile points (percent) for each. There are no defaults for the percentile point percentages so they must be specified.
   • Format: param0:p0:p1:..pn; param1:p0:p1:..pm
   • Example: ...<product>?percentiles=temperature:5.0:50.0:95.0;qpf:5.0:50.0:95.0

1. Decorating with “fine”, “medium” or “coarse” facilitates specification of predefined percentile ranges, which range from narrow (fine) to wide (coarse) in precision. The percentile ranges are provided below. The predefined percentile ranges are translated into purely numeric ranges..

• Format: param0:predefined0;param1:predefined1
• Example: ...<product>?percentiles=temperature:coarse;qpf:fine

The maximum number of percentiles supported is 100.

Percentiles Predefined Bin Ranges

Parameter: Probabilities

Subset probabilities of the PDF distribution. Some users do not require the entire PDF, which describes the likelihood of the full set of possible outcomes at user-defined discretization. These users may only require information about what portion of the ensemble forecasts that fall in some small range of the full distribution. For instance, they may want to know the percentage of qpf forecasts that fall between some lower bound and upper bound, e.g. qpf between 0.05 and 0.10” per hour, or temperature above 90 deg F.

When specifying probabilities, use a semicolon separated list of parameters for which to return probability distribution integrations defined by a colon separated list of integral limit sets (form of <lb,ub> where lb is lower bound and ub is an upper bound and they are comma separated) following each parameter name:

lb_i: The lower bound of the integration required to form a probability where the integration is for lb_i < parameter value <=ub_i. Must be a decimal value, inf, or –inf. Default is -inf.

ub_i: The upper bound of the integration required to form a probability where the integration is for lb_i < parameter value <=ub_i. Must be a decimal value, inf, or –inf. Default is inf.

Although lower and upper bounds can be excluded to imply +/-inf defaults, the comma itself must be included.

Units of bounds much match that of parameter, consistent with the units request parameter.

• Format: param0:lb0,ub0:lb1,ub1:…lbN,ubN;param1:lb0,ub0:lb1,ub1,…lbM,ubM
• Example: …<product>?probabilities=temperature:,0:0.0,10:10,;qpf:2.0,5.0

Parameter: Prototypes

A quantity of prototype forecasts can be requested for specified parameters. The response will include the requested quantity of individually unique, but statistically representative hourly forecasts for the specified parameter. Each of the individual forecasts returned are statistically viable and as a collection they retain the characteristics of the underlying probability distribution for the parameter at each forecast hour. The underlying probability distribution function is represented with higher resolution the larger the requested quantity of forecasts, A user may utilize a collection of prototype forecasts to provide multiple variable inputs to a downstream model to obtain a meaningful distribution of outcomes from that model.

1. When specifying an prototype request, a semicolon separated list of parameters is used, each with a colon separated integer that specifies the quantity of forecasts being requested. There are no defaults for the quantity so it must be specified for each parameter. The quantity across parameters may vary although in many use cases a consistent quantity is likely.

• Format: param0:n;param1:m
• Example: ...<product>?prototypes=temperature:25;qpf:25

This example requests 25 temperature and 25 qpf hourly forecasts.

The maximum number of prototypes supported is 100.

Data Elements & Definitions

JSON Sample

// Response Collapsed for Presentation Purposes

{ 
    "metadata": {
        "procTime":1555432667,"resource":"pfp","version":"2","units":"m","spatialApp":1,"serviceTime":0.15704954,"initTime":1555430400,
        "latitude":43.3700,"longitude":-71.0300,"elevation":140.00,"landuse":1.00,"expires":"Tue Apr 16 16:39:47 2019",
        "hostname":"pfp-prod-01-compute-000-us-east-1","requestId":674590000179262,"user_specified_n_output_hours":241
    },
    "forecasts1Hour": {
        "fcstValid": [ 1555430400, 1555434000, 1555437600, 1555441200, 1555444800, 1555448400, 1555452000, 1555455600,...],
        "discretePdfs": [
            {
                "parameter": "windGust",
                "binEdges": [ [1.5,5.5,10.7,17.1,24.4,32.6,42.0,49.0,57.7], [1.5,5.5,10.7,17.1,24.4,32.6,42.0,49.0,57.7],...],
                "binValues": [ [0.00,0.00,0.00,32.61,63.16,4.23,0.00,0.00,0.00,0.00], [0.00,0.00,0.00,32.60,64.40,3.01,0.00,0.00,0.00,0.00],...]
            }
        ],
        "probabilities": [
            {
                "parameter": "qpf",
                "lb": 0.100,
                "ub": 3.403e+38,
                "probability": [ 7.943, 7.266, 7.087, 7.271, 8.014, 8.376, 8.714, 8.725,...]
            }
        ],
        "percentiles": [
            {
                "parameter": "ceiling",
                "numPoints": 3,
                "percentilePoints": [ 10.00, 50.00, 90.00 ],
                "percentileValues": [ [ 1371, 1749, 25400 ], [ 1816, 25400, 25400 ], [ 1816, 25400, 25400 ],...]
            },
            {
                "parameter": "visibility",
                "numPoints": 3,
                "percentilePoints": [
                    10.00,
                    50.00,
                    90.00
                ],
                "percentileValues": [ [ 1.98, 7.22, 16.10 ], [ 5.80, 16.10, 16.10 ], [ 16.10, 16.10, 16.10 ],...]
            }
        ],
        "prototypes": [
            {
                "parameter": "windSpeed",
                "forecast": [ [ 9.8, 9.5, 9.8, 9.7, 8.5, 7.8, 6.8, 5.3, 3.8, 3.2, 2.8, 2.5,...],
                              [ 8.8, 8.7, 9.0, 8.9, 9.1, 8.5, 7.5, 5.8, 4.4, 3.9, 3.4, 3.2,...] ]
            }
        ]
    }
}