GribStream

Calculated expressions

GribStream lets you define expressions to calculate derived columns, transformations, and boolean filters in your API queries.

Expressions use the expr language, supporting numeric, logical, and string operations.

To see calculated expressions used in a cache-friendly history-and-forecast workflow: CFS corn growth forecast

Features

Example expressions

Example request

Example of a request using expressions to add calculated columns and filter rows:

curl -X POST 'https://gribstream.com/api/v2/hrrr/timeseries' \
-H "Content-Type: application/json" \
-H "Authorization: Bearer [API_TOKEN]" \
-d '{
    "fromTime": "2024-09-10T00:00:00Z",
    "untilTime": "2024-09-10T10:00:00Z",
    "minLeadTime": "1h",
    "maxLeadTime": "50h",
    "coordinates": [{ "lat": 40.7306, "lon": -73.9352, "name": "New York City" }],
    "variables": [
    { "name": "UGRD", "level": "1000 mb", "alias": "uwind" },
    { "name": "VGRD", "level": "1000 mb", "alias": "vwind" }
    ],
    "expressions": [
    { "expression": "func.Hypot(uwind, vwind)", "alias": "wind_magnitude" },
    { "expression": "int(270 - func.Atan2(vwind, uwind) * 180 / 3.14159) % 360", "alias": "wind_direction" }
    ]
}'

Example response

forecasted_at,forecasted_time,lat,lon,name,uwind,vwind,wind_direction,wind_magnitude
2024-09-10T02:00:00Z,2024-09-10T03:00:00Z,40.7306,-73.9352,New York City,7.1213,1.7680,256,7.3375
2024-09-10T01:00:00Z,2024-09-10T02:00:00Z,40.7306,-73.9352,New York City,8.1815,1.6363,258,8.3435
2024-09-10T00:00:00Z,2024-09-10T01:00:00Z,40.7306,-73.9352,New York City,8.0572,2.9389,249,8.5765
2024-09-10T05:00:00Z,2024-09-10T06:00:00Z,40.7306,-73.9352,New York City,6.8368,0.1001,269,6.8375
2024-09-10T04:00:00Z,2024-09-10T05:00:00Z,40.7306,-73.9352,New York City,6.4087,3.0921,244,7.1157
2024-09-10T03:00:00Z,2024-09-10T04:00:00Z,40.7306,-73.9352,New York City,6.4841,2.5385,248,6.9633
2024-09-09T23:00:00Z,2024-09-10T00:00:00Z,40.7306,-73.9352,New York City,6.1795,3.9539,237,7.3362
2024-09-10T08:00:00Z,2024-09-10T09:00:00Z,40.7306,-73.9352,New York City,5.9424,-0.6889,276,5.9822
2024-09-10T06:00:00Z,2024-09-10T07:00:00Z,40.7306,-73.9352,New York City,7.3567,1.5594,258,7.5201
2024-09-10T07:00:00Z,2024-09-10T08:00:00Z,40.7306,-73.9352,New York City,6.5438,0.7486,263,6.5864

Expression Language Reference

For the full language specification, see: https://expr-lang.org/docs/language-definition

Available Functions

Function Description
func.Abs Abs(a): returns absolute value
func.Acos Acos(angle): returns arccosine of angle (in radians)
func.Acosh Acosh(value): returns inverse hyperbolic cosine
func.Asin Asin(angle): returns arcsine of angle (in radians)
func.Asinh Asinh(value): returns inverse hyperbolic sine
func.Atan Atan(angle): returns arctangent of angle (in radians)
func.Atan2 Atan2(y, x): returns arctan of y/x, accounting for quadrant
func.Atanh Atanh(value): returns inverse hyperbolic tangent
func.Cbrt Cbrt(value): returns cube root
func.Ceil Ceil(a): returns smallest integer ≥ a
func.Copysign Copysign(magnitude, sign): returns magnitude with sign of second argument
func.Cos Cos(angle): returns cosine of angle (in radians)
func.Cosh Cosh(value): returns hyperbolic cosine
func.Erf Erf(value): returns error function
func.Erfc Erfc(value): returns complementary error function
func.Exp Exp(power): returns e raised to power
func.Exp2 Exp2(power): returns 2 raised to power
func.Expm1 Expm1(power): returns e^power minus 1
func.Floor Floor(a): returns largest integer ≤ a
func.Frexp Frexp(a): decomposes a into fraction and exponent (a = fraction * 2^exponent)
func.Gamma Gamma(value): returns gamma function
func.Hypot Hypot(a, b): returns sqrt(a² + b²)
func.Ilogb Ilogb(a): returns integer logarithm base 2 of a
func.Inf Inf(sign): returns infinity (positive if sign ≥ 0, negative if sign < 0)
func.IsNaN IsNaN(a): returns true if a is NaN
func.J0 J0(value): returns Bessel function (first kind, order 0)
func.J1 J1(value): returns Bessel function (first kind, order 1)
func.Jn Jn(n, value): returns Bessel function (first kind, order n)
func.Ldexp Ldexp(fraction, exponent): returns fraction * 2^exponent
func.Lgamma Lgamma(value): returns log gamma and sign
func.Log Log(a): returns natural logarithm
func.Log10 Log10(a): returns base-10 logarithm
func.Log1p Log1p(a): returns logarithm of (1+a)
func.Log2 Log2(a): returns base-2 logarithm
func.Max Max(a, b): returns maximum of a and b
func.Min Min(a, b): returns minimum of a and b
func.Mod Mod(a, b): returns remainder of a divided by b
func.NaN NaN(): returns not-a-number value
func.Nextafter Nextafter(a, b): returns the next representable value after a towards b
func.Pow Pow(base, exponent): returns base raised to exponent
func.Pow10 Pow10(exponent): returns 10 raised to exponent
func.Remainder Remainder(a, b): returns IEEE 754-style remainder of a/b
func.Round Round(a): rounds a to the nearest integer
func.RoundToEven RoundToEven(a): rounds a to the nearest even integer
func.Signbit Signbit(a): returns true if a is negative
func.Sin Sin(angle): returns sine of angle (in radians)
func.Sinh Sinh(value): returns hyperbolic sine
func.Sqrt Sqrt(a): returns square root
func.Tan Tan(angle): returns tangent of angle (in radians)
func.Tanh Tanh(value): returns hyperbolic tangent
func.Trunc Trunc(a): returns integer part of a (truncates fractional part)
func.Y0 Y0(value): returns Bessel function (second kind, order 0)
func.Y1 Y1(value): returns Bessel function (second kind, order 1)
func.Yn Yn(n, value): returns Bessel function (second kind, order n)