Planning method

Weather coverage: reading place, time, and provider limits

Weather data is always about an area, a period, a provider method, and an issue time. Turning a broad forecast into “weather at this attraction right now” discards those boundaries and creates confidence the source did not provide.

Asmaliana’s weather tool is designed to return the provider’s actual coverage and an advisory interpretation—not a venue-level sensor reading or safety guarantee.

Verified production uses the rights-cleared MET Malaysia Government Open API for a Melaka Tengah (Ds078) area forecast and official warning feed. The adapter validates the upstream schemas, records the provider’s issue/valid times, caches permitted results for five minutes, and fails closed when the provider is unavailable or a query is outside its documented horizon. Development and preview can still use the explicit synthetic demo adapter; demo output must not guide travel.

Spatial coverage

A provider value can apply to a:

• broad region;
• forecast zone;
• grid cell;
• station or observation site;
• geocoded point under a documented model.

These are not interchangeable. A registered location_id lets the adapter map a request through a reviewed configuration instead of accepting an arbitrary coordinate or URL. The response should state the provider’s actual coverage label or granularity.

If no supported mapping exists, the correct result is no_location_data. Quietly choosing an unknown “nearest” point could be misleading unless the method, distance, terrain limits, and evidence are explicitly designed and disclosed.

Temporal coverage

Three times are easy to confuse:

1. Issue time — when the provider produced the forecast or advisory.
2. Valid period — when the described condition is meant to apply.
3. Retrieval time — when Asmaliana received it.

Retrieving an old forecast now does not make it current. Cache age is also not the same as forecast validity.

A query outside the provider’s documented horizon should return out_of_forecast_range. It should not extrapolate the last available day or replace the missing live result with demo data.

Forecast, observation, and warning

These evidence types answer different questions:

• A forecast describes modelled future conditions for its stated coverage.
• An observation reports measured conditions at a stated site and time.
• A warning/advisory is a published alert from an identified authority/provider for a stated area and period.

The service should not relabel one as another. An observation at a station is not automatically a current measurement at a venue, and a regional warning should remain regional.

“No warning” is not “safe”

An empty alert list can mean many things:

• no applicable alert was published;
• the requested area does not map to the alert feed;
• the provider is unavailable or stale;
• redistribution rights exclude part of the response;
• the query is outside the supported time range.

Even a valid “no applicable alert” result addresses only that provider and query. It does not establish that travel is safe. Users should follow the relevant authoritative current service for urgent safety decisions.

Explicit result states

A useful response distinguishes:

• available: validated provider data applies to the stated coverage and period;
• out_of_forecast_range: the requested date lies outside the provider horizon;
• no_location_data: no supported spatial mapping/data exists;
• stale: data exceeds the normal freshness policy but is returned under an explicit stale-use policy;
• provider_unavailable: no usable provider result or permitted cache exists;
• restricted: a known provider field cannot be redistributed for this surface;
• schema_error: an upstream shape changed and the adapter failed closed.

These are business/evidence outcomes. The surrounding HTTP status depends on whether the request was valid and whether the operation contract can represent the unavailable state normally.

Cache behavior

Weather caching is useful only when the provider permits it and the response keeps its original issue/valid times. A cache hit should expose age and source. It must not generate a new issue time or reset evidence freshness.

When the upstream call fails:

• a valid, permitted cached value may still be useful;
• a stale value may be shown only when policy permits and the stale label is prominent;
• otherwise the result is unavailable;
• verified production never falls back to the synthetic demo adapter.

What a response should tell you

Before using an advisory, inspect:

• requested registered location;
• provider and attribution;
• actual spatial coverage/granularity;
• issue time and valid period;
• retrieval/cache age;
• units and normalisation version;
• forecast/observation/advisory type;
• applicable warning area and period;
• freshness and provider status;
• data_mode, data/adapter version, warnings, and limitations.

If those fields are absent, a friendly sentence alone cannot support a reliable decision.

Weather in an itinerary

Weather is one dimension of a plan, not a universal veto or approval. A planner may use available advisory state to flag an outdoor preference or a published warning, while still reporting:

• what was checked;
• what remained unknown;
• which candidate/place attributes were evidenced;
• whether an indoor/outdoor classification itself is reviewed;
• whether the provider period covers the planned time.

The planner should not invent weather resilience for a place or promise that an indoor stop is unaffected.

Privacy and precision

A weather query rarely needs a traveller’s exact starting coordinate. Registered coarse location IDs reduce both privacy exposure and false precision. Exact origins belong to transient route/planning inputs and are excluded from ordinary logs.

Practical checklist

• Is this demo or verified/live data?
• What exact area or grid does the value cover?
• What are the issue time and valid period?
• Is the requested date within the forecast horizon?
• Is the value a forecast, observation, or official/provider warning?
• Is cached/stale use clearly labelled and permitted?
• Does an empty alert list state its limited meaning?
• Are unavailable, restricted, and schema-error states explicit?
• Does the plan disclose unchecked weather and venue dimensions?
• For safety-critical choices, has the traveller consulted the appropriate authoritative current channel?

Coverage is part of the weather fact. Removing it does not simplify the answer; it changes the claim.