Updated for the Timeline Weather API. This guide replaces the legacy “current conditions” article and shows how to retrieve the live weather for any location using a single, modern endpoint.
Many apps need the latest weather right now—dashboards, alerts, mobile widgets, and more. With the Timeline Weather API, you can request a live snapshot for any location using the same endpoint you already use for forecasts and historical data.
This guide shows how to request current conditions, control units, read the response, and fetch the data in JSON or CSV format.
Why use Timeline for current conditions?
- One endpoint for past, present, and forecast data
- Returns a consistent schema that includes currentConditions, hours, and days
- Flexible output (JSON or CSV) and easy unit control (us, metric, uk)
- Works with addresses, latitude/longitude, and postal codes
Quick start
Current conditions are included when you set include=current or use the default include when requesting JSON or FLATJSON format. You can combine this with hourly or daily data if you want extra context (include=current,hours or include=current,hours,days). In JSON, the live snapshot appears in the currentConditions object. In CSV, a single row is added to the output.
A typical Timeline request that includes currentConditions looks like:
JSON
https://weather.visualcrossing.com/VisualCrossingWebServices/rest/services/timeline/London?include=current&unitGroup=metric&key=YOUR_API_KEY&contentType=jsonCSV
https://weather.visualcrossing.com/VisualCrossingWebServices/rest/services/timeline/London?include=current&unitGroup=metric&key=YOUR_API_KEY&contentType=csvResponse format
The top-level JSON payload includes metadata about the location and a currentConditions object that summarizes the latest observed/nowcast values.
Common fields include
The currentConditions object typically includes:
- datetime: ISO local timestamp for the observation
- temp, feelslike, humidity, dew
- windspeed, winddir, windgust
- precip, preciptype, snow
- pressure, visibility, cloudcover
- solarradiation, solarenergy (if available)
- conditions: human‑readable summary (for example, “Partially cloudy”)
- icon: symbolic condition name suitable for icons (for example, “partly-cloudy-day”)
Tip: In CSV output, use include=current to get a single record representing the current conditions along with optional hourly/daily rows if requested.
Location formats
You can specify the location in several ways:
- Address or place name /timeline/Seattle,WA,USA
- Latitude,longitude /timeline/47.6062,-122.3321
- US ZIP code /timeline/98101
Examples
- Simple current conditions for a city (US units) /timeline/Chicago,IL,USA?include=current&unitGroup=us
- Exact coordinates, metric units, JSON /timeline/40.7128,-74.0060?include=current&unitGroup=metric&contentType=json
- Include hourly context for today plus the current snapshot /timeline/Austin,today?include=current,hours&unitGroup=us
- CSV suitable for spreadsheets (current only) /timeline/Paris?include=current&contentType=csv
Controlling units
Add unitGroup to format temperatures, wind, precipitation, and pressures: • us (default in many examples) • metric • uk
Example /timeline/Dublin?include=current&unitGroup=uk
CSV vs JSON
JSON is best for apps—use currentConditions for the live snapshot and hours/days for timelines. • CSV is ideal for spreadsheets—include=current returns a row you can chart or join with other data.
Minute‑level detail (optional) If you need finer‑than‑hour detail near “now,” add minutes to include to return minute‑level data nested under each hour (JSON only): /timeline/San%20Francisco,today?include=current,hours,minutes&unitGroup=us&contentType=json Note: For CSV, when requesting sub‑hourly data you typically request minutes alone.
Multiple locations in one call (optional) If you need current conditions for many places at once (reducing request overhead), use the Multiple Timeline endpoint designed for batches.
Low‑latency option (optional) For ultra‑fast responses in a near‑term window (about three days back to 15 days forward), consider the Timeline LLX endpoint. It uses the same schema and query style as Timeline.
Error handling and tips
- Always include your key parameter.
- If you pass an ambiguous place name, the service geocodes to its best match; use coordinates for precision.
- If you don’t see currentConditions, add include=current and ensure your date range includes today/now.
How accurate is the current data?
Timeline uses recent station, radar and satellite observations. In well-instrumented areas, this often reflects the current state within the last few minutes. In remote areas with fewer stations, the accuracy depends on the availability and recency of local observations.