Sign inRegisterCheck connection

Cumulus XML as a Structured Export of Current Conditions

Cumulus XML exports current observations as named elements with units. It is not a live feed, and it is not the same contract as web tags or realtime.txt.

Back to Cumulus weather software guides

A Cumulus station can publish the same observation three different ways: as HTML built from web tags, as a one-line realtime.txt packet, or as an XML document whose elements name the quantities. The historical path /cumulus-xml.php sat on that third contract. This article is about the XML export as a structured snapshot of current conditions—what the elements mean, how the schema was versioned, and why treating the file as a live feed is a category error.

It is not a parser cookbook. Safe ingest of an untrusted station XML file is the subject of parsing station XML. It is not a file-format migrator; unit and date conversion between Weather Display–era and Cumulus files belongs on convert1.

Historical context

Steve Loft’s Cumulus software generated web pages by substituting web tags such as <#temp> inside template files. Community authors then asked for a machine-readable dump of those same tags so a PHP page, a gauge, or another station tool could read values without scraping HTML. The Cumulus Wiki XML webtags page documents one such extra template (cumulusxml.tpl, last community update January 2010): Cumulus processes the template, replaces tags with current values, and uploads the resulting XML.

The historical TNET Cumulus host kept /cumulus-xml.php in that cluster. The original interactive helper is not rehosted. The URL now explains the data object those pages were trying to publish.

Cumulus MX still processes extra template files, including XML, when an operator ticks Process on an extra web file (Cumulus Wiki: Webtags; last checked 13 August 2026). The community 2010 “full webtag dump” is one historical schema, not a vendor-guaranteed standard that every MX build still emits unchanged.

Three publication contracts

A scientifically usable Cumulus site is a chain of files. Mixing their jobs produces silent unit errors.

Web tags

A web tag is a placeholder in a template. After processing, <#temp> is gone and a number remains. The webtag documentation is the authority for names, modifiers such as rc=y (force a decimal point), and the fact that an unknown tag becomes an error string rather than a blank. A processed HTML page is a snapshot of layout plus values at process time. It is an excellent climate page. It is a poor API: a consumer has to scrape presentation markup.

realtime.txt

realtime.txt is an optional, frequently rebuilt, single-line, space-separated packet of current values plus unit tokens. The Cumulus Wiki realtime.txt page states the properties that matter here: generation is off by default; the file is meant to be re-created often; decimal points are script-friendly even when the PC locale uses commas; field counts grew across versions; the file is not a climate archive. Bandwidth notes in the same article exist because cadence is a quality-control choice.

That packet is compact and cheap to upload. It is also positional. Field 3 is outside temperature only if the producer and the consumer share the same field list. A parser that assumes Weather Display ClientRaw indexes will mislabel every column.

XML export

XML names the quantities. In the documented community dump, a typical item looks like a small record: a name attribute (temp, press, wspeed), a value, a unit, and a human description, grouped under section elements such as timetags. The example on the wiki declares encoding="ISO-8859-1" and a comment of the form Cumulus WebTag XML Data file - version 1.6. Those two facts—encoding and a version token in a comment—are part of the contract. A consumer that assumes UTF-8, or that ignores the version comment, is guessing.

XML is larger than realtime.txt. The wiki’s bandwidth warning for realtime XML uploads (on the order of tens of kilobytes per file, disastrous if FTP’d every few seconds on a capped link) is the reason this format is a structured export, not a heartbeat.

Elements, not a feed

RSS is a syndication dialect with channels, items, and pubDate. Cumulus XML, in the form documented for webtag dumps, is a current-conditions document: one weatherdata root, many named items, no item history. Overwriting the file does not append an observation series. If you need a time series, you must archive copies yourself and label that archive as derived, not as the Cumulus dayfile.

Call the file what it is:

  • Observed (or software-derived from observed) values at process time: temperature, humidity, pressure, rain, wind.
  • Derived station-software fields: wind chill, heat index, Zambretti-style forecast numbers. Those are not National Weather Service products.
  • Metadata: units, Cumulus version/build if present, date and time tags.

Do not call it a live feed because the URL ends in .xml or because a template was ticked “Realtime.” Realtime in Cumulus means “rebuild this extra file on the realtime timer.” It does not mean a push stream, and it does not mean the hardware sampled at that interval. Fine Offset / EasyWeather-class stations update on the order of tens of seconds; a faster XML rebuild mostly re-publishes the last logger packet (realtime.txt notes).

Schema and versioning

A named-element dump still needs a version. Community XML templates carried a version in an HTML comment. Field lists for realtime.txt grew from early Cumulus 1 through 1.9.4 and then again in MX (feels-like, weekly rain, and later tags). The same growth applies to any XML that dumps “all current webtags.” A parser written against the 2010 dump will not automatically understand tags MX added later, and it may see empty unit elements on time fields that were never dimensioned.

Practical versioning rules:

  1. Record the template version comment, the Cumulus version/build tags, and the date you last inspected the file.
  2. Treat missing elements as missing, not as zero. Zero rain can be real; zero humidity is not.
  3. Read the unit child (or the dedicated unit tags in realtime.txt) for every quantity. Do not infer Fahrenheit from a US domain name.
  4. Do not assume the XML encoding. Honor the XML declaration; if you control the template, prefer UTF-8 and say so in both the declaration and the HTTP charset.
  5. If two stations use different extra-file templates, they do not share a schema even if both files are called cumulus.xml.

There was never a single W3C schema for “Cumulus weather.” The W3C XML 1.0 specification defines well-formedness. Scientific usability is a separate, local contract: which names, which units, which clock.

What a consumer should demand

Before an XML export is used as evidence—on a mesomap, in a comparison with an official METAR, or in later research—require:

  • a documented element list and units;
  • an observation time with an unambiguous timezone or offset;
  • station identity and, preferably, latitude and longitude;
  • a distinction between observed values and software-derived phrases;
  • a freshness rule (file age versus the station’s upload interval).

Those are the provenance questions TNET states for public weather records on data sources, quality controls, and methodology. The XML file is one source, not an official aerodrome report. The Cumulus hub indexes the rest of the project family.

Practical checklist

  1. Identify whether the file is a processed extra template, a homemade dump, or HTML with an .xml suffix. The suffix is not the schema.
  2. Confirm Cumulus actually processed it: leftover <#temp> tokens mean FTP without Process.
  3. Compare one temperature, one pressure, and one rain value against the station’s HTML page and, if present, realtime.txt. Disagreement is a unit or field-map bug, not a weather event.
  4. Check encoding, version comment, and clock. A file that is well-formed XML can still be hours old.
  5. Do not enable DTD or external-entity processing when reading a station file you did not write. That is a parser issue, covered on parse_xml.php.

Modern relevance

MX operators often publish JSON extra files instead of a giant webtag XML dump. The job did not change: name the quantities, units, and valid time, and do not treat a rebuilt file as a stream. How TNET distinguishes observed, modelled, and derived information is conceptual on how the service works. That page does not document Cumulus templates.

Sources