Quickstart guide: expressions, filters, and time-travel queries

On May 26, 2025, we published a practical Quickstart Guide that walks through real GribStream API usage from token creation to advanced filtering. This post is the map for what to read first and how to choose the right query pattern.

The guide is intentionally API-first. It is for teams that already know the weather question they need to answer and want to turn that question into a reproducible request: a forecast time series for a site, a historical "what did we know then?" query, a model-run comparison, or a derived value such as wind speed, freezing risk, or solar input.

What it covers

• Tokens and auth: how to create a token and send it in requests.
• Response formats: CSV, JSON, and NDJSON for pipelines.
• Named locations and aliases: cleaner outputs for multi-point queries.
• Time-travel (as-of): evaluate models as they existed at a given moment.
• timesList: request sparse timestamps without full ranges.
• Expressions and filters: compute derived fields and return only rows that match a condition.

Why it is useful

The Quickstart is designed to be copy/paste friendly so you can go from first call to production query quickly, and it links directly to deeper references when you need them.

The most important early decision is endpoint choice:

• Use /timeseries when the application wants one best value per valid time, usually with the shortest acceptable lead time.
• Use /runs when the application needs to compare model cycles, inspect forecast drift, or keep every run/horizon pair.
• Use asOf with /timeseries for backtests and historical decisions, so the query only sees forecasts that were available at the time.
• Use forecastedFrom and forecastedUntil with /runs when the question is about model initialization times rather than valid times.

That distinction prevents a common data-leakage mistake. If a backtest asks "what would we have forecast at 2026-04-01 12:00 UTC?" it should use asOf and let GribStream choose the best forecast known at that moment. If the question is "how did the 00z and 06z runs differ?" it should use /runs.

Expressions and filters in practice

Expressions let a request return application-ready fields instead of raw model components. For example, a wind workflow can request UGRD and VGRD, compute scalar wind speed in the response, then filter to rows above an operational threshold. That same pattern powers several GribStream demos:

• the forecast model accuracy dashboard, which compares forecast values against URMA;
• the airport runway performance demo, which computes wind components and density-altitude terms from forecast variables;
• the solar panel generation dashboard, which turns radiation and temperature forecasts into estimated PV output.

The point is not that every application should copy those demos. It is that the same API primitives work for small point queries, dashboards, and offline pipelines: select exact variables, name the outputs, add expressions, filter when needed, and choose the response format that matches the consumer.

Where to go next

After the quickstart, use the documentation for request schema details, OpenAPI for generated clients and contract checks, and the expressions guide for expression syntax. For model-specific selectors, start from the model page rather than guessing parameter names. For example, GFS, HRRR, NBM, AIFS Oper, and DAFS GTG expose different inventories because they are different upstream products.

If you are using an AI coding tool or an internal agent, the GribStream MCP post is the companion read. It shows how to let the tool discover datasets and selectors instead of hard-coding them from memory.

Links

• Quickstart
• Expressions guide
• Documentation
• OpenAPI
• GribStream MCP for AI weather analysis