Sign inRegisterCheck connection

How to Document a WAP Weather Endpoint

How to document a WAP weather endpoint: MIME types, character encoding, and a dated test-handset matrix, not project history or live serving.

Back to Cumulus weather software guides

A WAP weather endpoint is a constrained observation product: a few labeled quantities that a phone from the late 1990s or early 2000s could parse. Documenting it is not the same job as telling the story of why the project existed, and it is not the same job as serving a deck today. This page is the reference card for the endpoint contract: MIME types, character encoding, and a written test-handset matrix. Project history belongs on /projects/wap. Serving belongs on /wap.php.

Historical context

Wireless Application Protocol browsers did not fail HTML by accident. They failed it because memory, markup, and radio budgets were small. Operators who already published Cumulus realtime.txt to a host added a PHP (or static) URL that emitted Wireless Markup Language or later XHTML Mobile Profile. The historical TNET site kept both a project page and this reference address so that another author could implement a compatible deck without reverse-engineering headers.

WAP 1.x decks used WML. WAP 2.0 user agents expected XHTML Mobile Profile. A reference that says only “mobile page” does not tell a tester which parser will run. This card exists to force that distinction onto paper.

TNET Weather does not operate a WAP gateway and does not rehost historical decks as live phone software.

MIME types: the first line of the contract

The endpoint’s Content-Type is part of the observation product. A correct body with the wrong type is a failed experiment on many handsets.

WML 1.x (textual). IANA registers text/vnd.wap.wml for Wireless Markup Language. Optional parameters include charset and level (WML version, for example level=1.1). Binary compiled WML used application/vnd.wap.wmlc. A PHP script that emits XML-looking WML but labels it text/html will be parsed as HTML by desktop browsers and may be refused by a WML user agent.

WAP 2 / XHTML Mobile Profile. The Open Mobile Alliance / WAP Forum type for XHTML Mobile Profile is application/vnd.wap.xhtml+xml. Conforming user agents must accept that type; they should also accept application/xhtml+xml, and they may accept text/html. Desktop browsers of the period often did the reverse: they understood text/html and offered to download application/vnd.wap.xhtml+xml. Document which type the endpoint sends, and whether it varies on Accept.

What the card must record

| Item | Why it is required | |---|---| | Media type actually sent | Handset parsers key off the type, not the .wml extension | | Whether type is static or negotiated | Accept handling is a compatibility switch | | Related types not sent | e.g. “WML only; no XHTML-MP” | | Content-Type charset parameter | See encoding, below |

Do not document a file extension as if it were a MIME type. Gateways and some phones ignored extensions once HTTP headers were present.

WMLScript, if ever used, is a different type (text/vnd.wap.wmlscript). A weather observation deck does not need it; if a historical script included it, the card should say so as a dependency, not as a default.

Character encoding: two declarations, one encoding

WML is an XML vocabulary. Character encoding is taken from the HTTP charset parameter and from the XML declaration. They must name the same encoding. A deck that sends Content-Type: text/vnd.wap.wml; charset=UTF-8 with <?xml version="1.0" encoding="ISO-8859-1"?> is unspecified behavior for a strict parser and mojibake for a loose one.

Document:

  • The single encoding of the response body (UTF-8, ISO-8859-1, or another named set).
  • Degree, superscript, and unit glyphs. Many WML 1 browsers had poor Unicode coverage. A reference that requires °C will fail on a handset that only has ASCII. The honest fallback is the same token Cumulus already puts in realtime.txt field 15: C or F.
  • Decimal separators. Cumulus realtime.txt is generated with a full stop as the decimal mark for script consumers, regardless of Windows locale. Do not localize commas in the WAP deck unless you document that the deck is no longer a lossless view of the packet.
  • Byte-order marks. A UTF-8 BOM in front of WML has broken picky parsers. The card should forbid a BOM unless a listed handset requires it (almost none did).

If the station name contains characters outside the documented encoding, the card must say whether they are transliterated or replaced. An observation that loses the station identity has failed the same completeness test as a text bulletin without a location.

Test-handset matrix: write the lab book

“Works on phones” is not a test. A WAP reference lists user-agent classes and the markup each class received. You do not need a museum of devices. You need a matrix that another person can repeat.

Minimum columns:

  1. Class — WML 1.1 browser; Openwave-class; Nokia WML; WAP 2 XHTML-MP; desktop used as a negative control.
  2. Accept header (or “not recorded”).
  3. Markup sent — WML 1.x deck versus XHTML-MP versus text/html fallback.
  4. Encoding verified — temperature unit visible, no replacement glyphs.
  5. Viewport constraint — cards/decks versus a single screen; whether images were omitted on purpose.
  6. Date of test.

Named models (for example a Nokia Series 60 XHTML-MP browser) belong in the matrix only if they were actually tested. Inventing a device list is worse than writing “class-level tests only.” Emulators (Openwave, Nokia Mobile Internet Toolkit, later Opera Mini) should be labeled as emulators. An emulator pass is not an over-the-air pass.

Observation content still has to be complete. A WAP deck is a low-bandwidth bulletin. It needs station identity, a timestamp with timezone or offset, temperature with unit, and at least one of wind, rain (with period), or pressure with unit. Derived indices, if present, must be labeled. Forecast sentences, if present, must be separate from the observation. That is the same contract as a text bulletin; the MIME type does not relax it.

Do not test by viewing source in a desktop browser alone. Desktop text/html rendering of WML is not evidence that a WAE user agent accepted text/vnd.wap.wml.

Inputs and freshness (endpoint card, not a server how-to)

Record the source file (usually Cumulus realtime.txt), the flavour, and the field map date from the Cumulus Wiki. Record what the deck does when the file is stale: a WML card that says “stale,” not a cached temperature with no mark. Timeout definitions live on the checkserver reference; this card only states that the WAP output must expose the same freshness rule.

License the PHP as found. Do not paste WML dumps that include other people’s station names as if they were current weather.

Practical checklist

  1. State WML 1.x, XHTML-MP, or both, with exact Content-Type values.
  2. State one encoding, HTTP charset, and XML declaration in agreement.
  3. Prefer ASCII unit tokens when the handset class lacks degree glyphs.
  4. Keep a dated handset/emulator matrix; do not invent models.
  5. Require a complete observation sentence in a few cards, not a menu of unlabeled numbers.
  6. Point history readers to /projects/wap and serving notes to /wap.php.
  7. Cite vendor field maps; do not fork them.

Modern relevance

Native apps replaced WAE browsers. The documentation pattern did not: any constrained endpoint (SMS, Apple Watch complication, emergency text service) still needs a media type, an encoding, and a device matrix. Responsive HTML is not a substitute for that card if the client is not an HTML engine.

TNET research bridge

A WAP deck is a small observation record. TNET’s public grouping of observed, modelled, and derived information is how the service works. The Cumulus hub indexes related project pages. Freshness and source identity for research records are covered in data sources, quality controls, and methodology.

Sources