Weather Reports

Track weather conditions during your visitors' sessions and correlate weather with behaviour. The plugin adds 11 new visit dimensions (temperature, humidity, pressure, wind, …) populated from WeatherAPI; each one ships with its own report, segment, API method and goal/conversion metrics.

• Reports

  

• Visitor log

  

• Weather tag

  

• Weather tag config

  

• Weather unit configuration

  

1- Install the plugin from the marketplace or via GitHub

Install this plugin from the Marketplace as super user or download the plugin and install it on your server from FTP in the /plugins folder.

Upon activation, this plugin will automatically update the structure of your database's log_visit and log_conversion tables by adding 11 new columns prefixed weather_ for the new dimensions.

2 - Save your WeatherAPI key in Matomo (recommended)

This plugin retrieves weather data from WeatherAPI. Generate your own API key (the free plan is up to 1 million calls per month), then save it as super user in Administration → General settings → WeatherReports.

Matomo then calls WeatherAPI itself through a small public endpoint, so the key never appears in your website code:

GET {matomoUrl}/index.php?module=WeatherReports&action=getWeather&lang=en
→ {"current": {"temp_c": 13.2, "condition": {"text": "Overcast", "code": 1009}, ...}}

Responses are cached for 30 minutes per location. WeatherAPI receives the coordinates found by Matomo geolocation (rounded to about 10 km) when a GeoIP city database is configured, otherwise the visitor IP without its last byte.

3 - Configure the units of the website

In Administration → Websites → Weather, choose the website with the site selector and set the Temperature (°C/°F), Precipitation (mm/in), Pressure (mb/inHg), Visibility (km/mi) and Wind speed (km/h/mph) units (admin access to the website needed). Values are stored and displayed in these units: the tracking code sends metric values and Matomo converts them when tracking. Reports show the unit in the column title and the visitor log next to each value.

Changing the units later does not convert the data tracked before the change.

4 - Fetch data on your website

The weather is fetched once per hour per browser session (cached in sessionStorage) and added to the tracking requests of every page, so a new visit started in the same browser session gets it too.

4 - 1 With Matomo Tag Manager (Recommended)

Use the Weather custom Tag in Matomo Tag Manager (in the Openmost section), fire it on every page view and publish a new container version.

• WeatherAPI key: leave it empty to use the key saved in Matomo (recommended). When set, the browser calls WeatherAPI directly with this key, visible in the container.
• Matomo URL: prefilled with the URL of your Matomo, used when the tag has no API key.
• Language: language of the condition text sent to Matomo. Reports and the visitor log display conditions in the language of each Matomo user whatever the language tracked.

Upgrading from a previous version of the plugin? The published container is a static JS file built at publish time, so improvements to the bundled tag template only take effect once you republish your container. Until then the previous tag keeps working as before.

4 - 2 OR with Matomo classic code (only if you don't use Matomo Tag Manager)

Add the following snippet on every page, after the Matomo tracking code. Replace https://matomo.example.com/ with the URL of your Matomo.

<!-- Openmost WeatherReports code for Matomo -->
<script>
    (async function () {
        const matomoUrl = "https://matomo.example.com/";
        const lang = "en"; // language of the condition text, see https://www.weatherapi.com/docs/
        const cacheKey = "matomoWeather";
        const cacheTtl = 60 * 60 * 1000; // one weather lookup per hour per browser session

        const send = (weather) => {
            window._paq = window._paq || [];
            window._paq.push(["WeatherReports.setWeather",
                weather.cloud,                               // Cloud
                weather.condition && weather.condition.text, // Condition
                weather.feelslike_c,                         // Felt temperature
                weather.humidity,                            // Humidity
                weather.precip_mm,                           // Precipitation
                weather.pressure_mb,                         // Pressure
                weather.temp_c,                              // Temperature
                weather.uv,                                  // UV
                weather.vis_km,                              // Visibility
                weather.wind_dir,                            // Wind direction (compass)
                weather.wind_kph,                            // Wind speed
                "metric"                                     // Matomo converts to the units of the website
            ]);
        };

        try {
            const cached = JSON.parse(sessionStorage.getItem(cacheKey) || "null");
            if (cached && cached.current && Date.now() - cached.time < cacheTtl) {
                send(cached.current);
                return;
            }
        } catch (_) { /* storage disabled */ }

        try {
            const response = await fetch(
                `${matomoUrl}index.php?module=WeatherReports&action=getWeather&lang=${encodeURIComponent(lang)}`,
                { credentials: "omit" }
            );
            if (!response.ok) return;
            const data = await response.json();
            const weather = data && data.current;
            if (!weather) return;

            send(weather);

            try {
                sessionStorage.setItem(cacheKey, JSON.stringify({ time: Date.now(), current: weather }));
            } catch (_) { /* storage full or disabled */ }
        } catch (_) { /* swallow network errors */ }
    })();
</script>
<!-- End Openmost WeatherReports code for Matomo -->

To call WeatherAPI directly instead (the key is then visible in your website code), replace the fetched URL with https://api.weatherapi.com/v1/current.json?key=YOUR_KEY&q=auto:ip&aqi=no&lang=....

The last setWeather argument tells the unit system of the values: "metric" or "imperial" (feelslike_f, precip_in, pressure_in, temp_f, vis_miles, wind_mph). Without it, values are stored as sent, as snippets of previous plugin versions do.

Values are sent with the page view when the weather is known before it, otherwise with a ping request attached to the current visit.

Optional: resolve the visitor IP via Matomo

The plugin also exposes a small public endpoint that returns the visitor IP as Matomo resolves it (honouring proxy_client_headers from your config.ini.php). It can be called from any origin:

GET {matomoUrl}/index.php?module=WeatherReports&action=getUserIp
→ {"ip": "203.0.113.5"}

5 - Enjoy new reports and features

You will find the different reports in the Weather section of the Matomo Visitors menu. These reports support Matomo's automatic archiving CRON for better performance (recommended).

The visitor log and visitor profile show a weather card for each visit with weather data.

Dimensions, segments and API methods:

| Dimension name   | Type   | Segment name           | API method                        | Tracking HTTP API parameter |
|------------------|--------|------------------------|-----------------------------------|-----------------------------|
| Condition        | string | weatherCondition       | WeatherReports.getCondition       | weather_condition           |
| Cloud            | int    | weatherCloud           | WeatherReports.getCloud           | weather_cloud               |
| Temperature      | float  | weatherTemperature     | WeatherReports.getTemperature     | weather_temperature         |
| Felt temperature | float  | weatherFeltTemperature | WeatherReports.getFeltTemperature | weather_felt_temperature    |
| Pressure         | float  | weatherPressure        | WeatherReports.getPressure        | weather_pressure            |
| Precipitation    | float  | weatherPrecipitation   | WeatherReports.getPrecipitation   | weather_precipitation       |
| Humidity         | int    | weatherHumidity        | WeatherReports.getHumidity        | weather_humidity            |
| Uv               | float  | weatherUv              | WeatherReports.getUv              | weather_uv                  |
| Visibility       | float  | weatherVisibility      | WeatherReports.getVisibility      | weather_visibility          |
| Wind direction   | string | weatherWindDirection   | WeatherReports.getWindDirection   | weather_wind_direction      |
| Wind speed       | float  | weatherWindSpeed       | WeatherReports.getWindSpeed       | weather_wind_speed          |

Tracking HTTP API: add weather_units=metric or weather_units=imperial to have the values converted to the units of the website.

The segment of a condition compares with the text as tracked (in the language of the tag). Condition report rows link to a segment matching every text merged in the row.

Privacy note

Through the Matomo endpoint, WeatherAPI receives rounded coordinates or the visitor IP without its last byte. When the tag calls WeatherAPI directly, WeatherAPI receives the visitor IP. Make sure your privacy policy mentions it. The plugin does not call any third-party IP-geolocation service.

Example WeatherAPI response

{
  "last_updated": "2026-05-06 20:00",
  "temp_c": 13.2, "temp_f": 55.8,
  "is_day": 1,
  "condition": { "text": "Overcast", "code": 1009 },
  "wind_mph": 6, "wind_kph": 9.7, "wind_degree": 346, "wind_dir": "NNW",
  "pressure_mb": 1011, "pressure_in": 29.85,
  "precip_mm": 0.08, "precip_in": 0,
  "humidity": 67, "cloud": 100,
  "feelslike_c": 12.5, "feelslike_f": 54.5,
  "vis_km": 10, "vis_miles": 6,
  "uv": 0
}

How do I install this plugin?

This plugin is available in the official Matomo Marketplace. Install it the same way as any other plugin:

• Go to the administration panel.
• Open Marketplace → Plugins.
• Search for WeatherReports, then install and activate.
• Follow the setup documentation to save your WeatherAPI key and wire up the data collection.

Which Matomo versions are supported?

Version 6.x of the plugin requires Matomo 6, PHP 8.1+ and MySQL 8.0+ or MariaDB 10.6+. Use the 5.x versions of the plugin on Matomo 5.

Do I need to do anything after updating the plugin?

No. Updates of the 6.x versions need no database migration: existing data, settings, Tag Manager tags and tracking codes keep working. Republish your Tag Manager container to benefit from the latest Weather tag.

Where do I save my WeatherAPI key?

In Administration → General settings → WeatherReports (super user). Leave the API key of the Weather tag empty: the tag then gets the weather through Matomo and the key is never visible in your website code. A tag with its own API key keeps calling WeatherAPI directly.

Can I use a weather API other than WeatherAPI?

Yes. The plugin only cares about the values pushed via _paq.push(['WeatherReports.setWeather', …]). Any source that fits that contract works. We recommend WeatherAPI because it has a free 1M-call tier and we test against its payload. Condition translations only apply to WeatherAPI condition texts.

How many WeatherAPI calls does it use?

At most one per browser session per hour: the weather is cached in sessionStorage and reused on the following pages. Through the Matomo endpoint, responses are also cached 30 minutes per location, so nearby visitors share the same call.

Why are conditions displayed in my language and not in the language of the tag?

Condition texts are matched against the official WeatherAPI list of conditions in 40 languages and displayed in the language of each Matomo user. The same condition tracked in several languages (for example after changing the tag language) is merged in one row. Texts that are not WeatherAPI conditions are displayed as tracked.

Do the reports support goals and conversions?

Yes, every weather report supports goal metrics and ecommerce conversions. When you select a goal in the report's metric switcher, you get conversion rate, conversions and revenue broken down by the weather dimension. Weather is also persisted on log_conversion, so historical conversions remain pinned to the weather they were tracked under.

Do I need to republish my Matomo Tag Manager container after a plugin update?

To use the new version of the Weather tag, yes. Matomo Tag Manager bakes the tag template into the published container JS file at publish time, so the previous tag keeps serving (and working) until you publish a new version.

Is the plugin active for all Matomo users on my instance?

Yes. Once you activate it, every user with access to the visitor reports can see Weather reports and segments.

Where are the per-site unit settings?

On the Administration → Websites → Weather page, for each website you have admin access to (they were in the website edit form before 6.2.0, saved units are kept). Set Temperature (°C/°F), Precipitation (mm/in), Pressure (mb/inHg), Visibility (km/mi) and Wind speed (km/h/mph). The Weather tag sends metric values and Matomo converts them to these units when tracking. Reports show the unit in the column title and the visitor log next to each value. Data tracked before a unit change is not converted.

How do I run the test suite?

./vendor/bin/phpunit -c plugins/WeatherReports/phpunit.xml --testsuite "WeatherReports Unit"
TZ=UTC npx vitest run plugins/WeatherReports

How can I contribute to this plugin?

Open an issue or pull request on github.com/openmost/WeatherReports. Any contribution is welcome: bug reports, translations, doc improvements, or features.

How long will this plugin be maintained?

As long as possible. We use it on our own Matomo instances, so issues and fixes are typically addressed quickly.