node-red-contrib-atmospore 0.1.0

package/README.md

@@ -0,0 +1,129 @@
+# node-red-contrib-atmospore
+
+<p align="center">
+  <a href="https://buymeacoffee.com/airdavid">
+    <img src="https://www.buymeacoffee.com/assets/img/custom_images/orange_img.png" alt="Buy Me A Coffee" height="41">
+  </a>
+</p>
+
+<p align="center"><em>Built and maintained independently. If this saves you time, a coffee keeps it alive.</em></p>
+
+---
+
+Node-RED nodes for the [Atmospore Pollen Forecast API](https://atmospore.com) — point forecasts, area averages, and top species rankings. Trigger automations based on forecasted pollen levels.
+
+## Nodes
+
+| Node | Description |
+|------|-------------|
+| **atmospore-config** | Shared API key and default coordinates |
+| **atmospore-pollen** | Interpolated point forecast for a coordinate |
+| **atmospore-pollen-area** | Area averages (min/max/avg) within a radius |
+| **atmospore-pollen-top** | Top species ranked by severity over a date range |
+| **atmospore-species** | Metadata for all 21 supported species |
+
+## Setup
+
+### 1. Get an API key
+
+Sign up at [atmospore.com](https://atmospore.com) and copy your API key from account settings.
+
+### 2. Add the config node
+
+Add an **atmospore-config** node, enter your API key, and set a default latitude and longitude. Use **Test API key** to verify before saving.
+
+### 3. Add nodes to your flow
+
+All nodes are triggered by any input message. Override coordinates, date, or forecast window at runtime via `msg` properties.
+
+## Node reference
+
+### atmospore-pollen
+
+Interpolated pollen forecast at a specific coordinate. Returns one entry per day.
+
+**Inputs**
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `payload` | any | Triggers a fetch |
+| `lat` / `lon` _(optional)_ | number | Override config node coordinates |
+| `dt` _(optional)_ | string | Start date `YYYY-MM-DD`. Defaults to today |
+| `forecastDays` _(optional)_ | number | Days to forecast (1–14) |
+| `species` _(optional)_ | string | `all`, `tree`, `grass`, `weed`, or comma-separated species |
+
+**Output** — `msg.payload.data[]`, one entry per day:
+```json
+{
+  "date": "2026-06-28",
+  "overall_risk": "high",
+  "species": {
+    "pinaceae": { "value": 124.6, "risk_level": "high",     "display_name": "Pine family",   "category": "tree"  },
+    "timothy":  { "value": 40.8,  "risk_level": "high",     "display_name": "Timothy Grass", "category": "grass" },
+    "poa":      { "value": 29.1,  "risk_level": "high",     "display_name": "Bluegrass",     "category": "grass" },
+    "urtica":   { "value": 31.6,  "risk_level": "moderate", "display_name": "Nettle",        "category": "weed"  },
+    "birch":    { "value": 0,     "risk_level": "low",      "display_name": "Birch",         "category": "tree"  }
+  }
+}
+```
+
+### atmospore-pollen-area
+
+Area-average pollen levels within a configurable radius. Each species includes `avg`, `min`, `max`, and `risk_level`.
+
+Same inputs as **atmospore-pollen**, plus:
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `radius` _(optional)_ | number | Search radius in meters (max 50 000, default 25 000) |
+
+### atmospore-pollen-top
+
+Top contributing species over a date range, ranked by severity. Good for a daily summary node.
+
+**Output** — `msg.payload.data[]`, ranked by severity:
+```json
+[
+  { "species": "birch", "display_name": "Birch", "category": "tree", "avg": 98, "max": 142, "risk_level": "high" },
+  { "species": "alder", "display_name": "Alder", "category": "tree", "avg": 14, "max": 22,  "risk_level": "low"  }
+]
+```
+
+### atmospore-species
+
+Returns metadata for all 25 supported species — display names, multilingual names (English, Swedish, Norwegian), categories, and risk thresholds. No authentication required. Trigger once at startup and cache the result.
+
+## Example: close the windows when birch pollen is high
+
+Wire up: **inject (every morning) → atmospore-pollen → function → your smart home node**
+
+```javascript
+const today = msg.payload.data[0];
+const birch = today?.species?.birch;
+
+if (!birch) return null; // species not in response
+
+if (birch.risk_level === 'high' || birch.risk_level === 'very high') {
+    msg.payload = { action: 'close_windows', reason: `Birch pollen: ${birch.risk_level}` };
+    return msg;
+}
+return null; // no action needed
+```
+
+## Requirements
+
+- Node.js 14 or later
+- Node-RED 2.0 or later
+- Atmospore API key
+
+## License
+
+MIT
+
+---
+
+## Support this project
+
+**[☕ Buy me a coffee](https://buymeacoffee.com/airdavid)**
+
+Bug reports and pull requests welcome on [GitHub](https://github.com/devdavidkarlsson/node-red-contrib-atmospore).

package/lib/atmospore-api.js

@@ -0,0 +1,67 @@
+'use strict';
+
+const fetch = require('node-fetch');
+
+const BASE_URL = 'https://pollenapi.com';
+const REQUEST_TIMEOUT_MS = 15000;
+
+function today() {
+    return new Date().toISOString().slice(0, 10);
+}
+
+class AtmosporeAPI {
+    constructor(apiKey) {
+        this.apiKey = apiKey;
+    }
+
+    async _fetch(path, auth = true) {
+        const headers = auth ? { 'x-api-key': this.apiKey } : {};
+        const response = await fetch(`${BASE_URL}${path}`, {
+            timeout: REQUEST_TIMEOUT_MS,
+            headers,
+        });
+
+        if (!response.ok) {
+            const text = await response.text();
+            throw new Error(`API error (${response.status}): ${text}`);
+        }
+
+        return response.json();
+    }
+
+    async getPollen({ lat, lon, dt, forecastDays = 1, species = 'all' } = {}) {
+        const params = new URLSearchParams({
+            lat, lon,
+            dt: dt || today(),
+            forecast_days: forecastDays,
+            species,
+        });
+        return this._fetch(`/v1/pollen?${params}`);
+    }
+
+    async getPollenArea({ lat, lon, dt, forecastDays = 1, species = 'all', radius = 25000 } = {}) {
+        const params = new URLSearchParams({
+            lat, lon,
+            dt: dt || today(),
+            forecast_days: forecastDays,
+            species,
+            radius,
+        });
+        return this._fetch(`/v1/pollen-area?${params}`);
+    }
+
+    async getPollenTop({ lat, lon, dt, forecastDays = 1 } = {}) {
+        const params = new URLSearchParams({
+            lat, lon,
+            dt: dt || today(),
+            forecast_days: forecastDays,
+        });
+        return this._fetch(`/v1/pollen-top?${params}`);
+    }
+
+    async getSpecies() {
+        return this._fetch('/v1/species', false);
+    }
+}
+
+module.exports = AtmosporeAPI;

package/nodes/atmospore-config.html

@@ -0,0 +1,87 @@
+<script type="text/javascript">
+    RED.nodes.registerType('atmospore-config', {
+        category: 'config',
+        defaults: {
+            name: { value: '' },
+            defaultLat: { value: '' },
+            defaultLon: { value: '' },
+        },
+        credentials: {
+            apiKey: { type: 'password' },
+        },
+        label: function() { return this.name || 'Atmospore'; },
+        oneditprepare: function() {
+            var configNodeId = this.id;
+            $('#atmospore-test-btn').on('click', function() {
+                var btn = $(this);
+                var status = $('#atmospore-test-status');
+                var tokens = RED.settings.get('auth-tokens');
+                var authHeader = tokens ? { 'Authorization': 'Bearer ' + tokens.access_token } : {};
+
+                btn.prop('disabled', true);
+                status.css('color', '#aaa').text('Testing...');
+
+                function handleResult(result) {
+                    status.css('color', result.ok ? '#009900' : '#c00')
+                          .text(result.ok ? '✓ API key valid.' : '✗ ' + result.error);
+                    btn.prop('disabled', false);
+                }
+
+                var apiKey = $('#node-config-input-apiKey').val();
+                var isPlaceholder = !apiKey || apiKey === '__CREDENTIAL_PLACEHOLDER__';
+
+                if (isPlaceholder && configNodeId) {
+                    // Existing deployed node — secret is not in the browser
+                    $.ajax({
+                        url: '/atmospore/test-node?configId=' + encodeURIComponent(configNodeId),
+                        type: 'GET', headers: authHeader,
+                        success: handleResult,
+                        error: function(xhr) { status.css('color','#c00').text('✗ Request failed: ' + xhr.status); btn.prop('disabled', false); }
+                    });
+                } else if (!isPlaceholder) {
+                    // New node or user has typed a new key — test raw credentials
+                    $.ajax({
+                        url: '/atmospore/test-key', method: 'POST',
+                        contentType: 'application/json', headers: authHeader,
+                        data: JSON.stringify({ apiKey: apiKey }),
+                        success: handleResult,
+                        error: function(xhr) { status.css('color','#c00').text('✗ Request failed: ' + xhr.status); btn.prop('disabled', false); }
+                    });
+                } else {
+                    status.css('color','#c00').text('Enter an API key first.');
+                    btn.prop('disabled', false);
+                }
+            });
+        },
+    });
+</script>
+
+<script type="text/html" data-template-name="atmospore-config">
+    <div class="form-row">
+        <label for="node-config-input-name"><i class="fa fa-tag"></i> Name</label>
+        <input type="text" id="node-config-input-name" placeholder="Atmospore">
+    </div>
+    <div class="form-row">
+        <label for="node-config-input-apiKey"><i class="fa fa-key"></i> API Key</label>
+        <input type="password" id="node-config-input-apiKey" placeholder="API key from atmospore.com">
+    </div>
+    <div class="form-row">
+        <label></label>
+        <button type="button" id="atmospore-test-btn" class="red-ui-button">Test API key</button>
+        <span id="atmospore-test-status" style="margin-left:10px;font-size:0.9em"></span>
+    </div>
+    <div class="form-row">
+        <label for="node-config-input-defaultLat"><i class="fa fa-map-marker"></i> Latitude</label>
+        <input type="number" id="node-config-input-defaultLat" placeholder="e.g. 59.9139" step="any" style="width:70%">
+    </div>
+    <div class="form-row">
+        <label for="node-config-input-defaultLon"><i class="fa fa-map-marker"></i> Longitude</label>
+        <input type="number" id="node-config-input-defaultLon" placeholder="e.g. 10.7522" step="any" style="width:70%">
+    </div>
+</script>
+
+<script type="text/html" data-help-name="atmospore-config">
+    <p>Configuration node for the Atmospore Pollen Forecast API.</p>
+    <p>Get your API key from <a href="https://atmospore.com" target="_blank">atmospore.com</a> account settings.</p>
+    <p><strong>Default Lat/Lon</strong> is used by all pollen nodes unless overridden by <code>msg.lat</code> / <code>msg.lon</code> at runtime.</p>
+</script>

package/nodes/atmospore-config.js

@@ -0,0 +1,51 @@
+'use strict';
+
+const AtmosporeAPI = require('../lib/atmospore-api');
+
+module.exports = function(RED) {
+    // Test the API key without needing a deployed node
+    RED.httpAdmin.post('/atmospore/test-key', RED.auth.needsPermission('flows.write'), async (req, res) => {
+        const { apiKey } = req.body;
+        if (!apiKey) return res.json({ ok: false, error: 'API key is required' });
+        const api = new AtmosporeAPI(apiKey);
+        try {
+            // /v1/species requires no auth — use /v1/pollen with a dummy call to test the key
+            // Instead, just validate by calling species (no auth) won't test the key.
+            // Use a minimal pollen call to verify auth.
+            await api.getPollen({ lat: 59.9, lon: 10.7, forecastDays: 1 });
+            res.json({ ok: true });
+        } catch (err) {
+            res.json({ ok: false, error: err.message });
+        }
+    });
+
+    // Test via deployed node (key not in browser for existing nodes)
+    RED.httpAdmin.get('/atmospore/test-node', RED.auth.needsPermission('flows.read'), async (req, res) => {
+        const configNode = RED.nodes.getNode(req.query.configId);
+        if (!configNode || !configNode.api) {
+            return res.json({ ok: false, error: 'Config node not found or has no API key' });
+        }
+        try {
+            await configNode.api.getPollen({ lat: 59.9, lon: 10.7, forecastDays: 1 });
+            res.json({ ok: true });
+        } catch (err) {
+            res.json({ ok: false, error: err.message });
+        }
+    });
+
+    function AtmosporeConfigNode(config) {
+        RED.nodes.createNode(this, config);
+        this.name = config.name;
+        this.defaultLat = config.defaultLat;
+        this.defaultLon = config.defaultLon;
+
+        const apiKey = this.credentials.apiKey;
+        this.api = apiKey ? new AtmosporeAPI(apiKey) : null;
+    }
+
+    RED.nodes.registerType('atmospore-config', AtmosporeConfigNode, {
+        credentials: {
+            apiKey: { type: 'password' },
+        },
+    });
+};

package/nodes/atmospore-pollen-area.html

@@ -0,0 +1,64 @@
+<script type="text/javascript">
+    RED.nodes.registerType('atmospore-pollen-area', {
+        category: 'Atmospore',
+        color: '#7fb069',
+        defaults: {
+            name: { value: '' },
+            configNode: { value: '', type: 'atmospore-config', required: true },
+            forecastDays: { value: 1 },
+            species: { value: 'all' },
+            radius: { value: 25000 },
+        },
+        inputs: 1,
+        outputs: 1,
+        icon: 'font-awesome/fa-map-o',
+        label: function() { return this.name || 'pollen area'; },
+        paletteLabel: 'pollen area',
+    });
+</script>
+
+<script type="text/html" data-template-name="atmospore-pollen-area">
+    <div class="form-row">
+        <label for="node-input-name"><i class="fa fa-tag"></i> Name</label>
+        <input type="text" id="node-input-name" placeholder="Name">
+    </div>
+    <div class="form-row">
+        <label for="node-input-configNode"><i class="fa fa-cog"></i> Config</label>
+        <input type="text" id="node-input-configNode">
+    </div>
+    <div class="form-row">
+        <label for="node-input-forecastDays"><i class="fa fa-calendar"></i> Days</label>
+        <input type="number" id="node-input-forecastDays" min="1" max="14" style="width:60px"> <span style="color:#aaa">(1–14)</span>
+    </div>
+    <div class="form-row">
+        <label for="node-input-species"><i class="fa fa-filter"></i> Species</label>
+        <select id="node-input-species" style="width:70%">
+            <option value="all">All</option>
+            <option value="tree">Trees only</option>
+            <option value="grass">Grass only</option>
+            <option value="weed">Weeds only</option>
+        </select>
+    </div>
+    <div class="form-row">
+        <label for="node-input-radius"><i class="fa fa-circle-o"></i> Radius</label>
+        <input type="number" id="node-input-radius" min="1" max="50000" style="width:80px"> <span style="color:#aaa">meters (max 50 000)</span>
+    </div>
+</script>
+
+<script type="text/html" data-help-name="atmospore-pollen-area">
+    <p>Average, minimum, and maximum pollen levels across a configurable radius. Good for regional risk assessment.</p>
+    <h3>Inputs</h3>
+    <dl class="message-properties">
+        <dt>payload <span class="property-type">any</span></dt><dd>Triggers a fetch.</dd>
+        <dt class="optional">lat / lon <span class="property-type">number</span></dt><dd>Override coordinates.</dd>
+        <dt class="optional">dt <span class="property-type">string</span></dt><dd>Start date (YYYY-MM-DD). Defaults to today.</dd>
+        <dt class="optional">forecastDays <span class="property-type">number</span></dt><dd>Number of days (1–14).</dd>
+        <dt class="optional">radius <span class="property-type">number</span></dt><dd>Search radius in meters (max 50 000).</dd>
+        <dt class="optional">species <span class="property-type">string</span></dt><dd><code>all</code>, <code>tree</code>, <code>grass</code>, <code>weed</code>, or comma-separated species.</dd>
+    </dl>
+    <h3>Outputs</h3>
+    <dl class="message-properties">
+        <dt>payload <span class="property-type">object</span></dt>
+        <dd><code>data[]</code> — one entry per day. Each species has <code>avg</code>, <code>min</code>, <code>max</code>, and <code>risk_level</code>.</dd>
+    </dl>
+</script>

package/nodes/atmospore-pollen-area.js

@@ -0,0 +1,44 @@
+'use strict';
+
+module.exports = function(RED) {
+    function AtmosporePollenAreaNode(config) {
+        RED.nodes.createNode(this, config);
+        const node = this;
+        node.configNode = RED.nodes.getNode(config.configNode);
+        node.forecastDays = config.forecastDays || 1;
+        node.species = config.species || 'all';
+        node.radius = config.radius || 25000;
+
+        if (!node.configNode || !node.configNode.api) {
+            node.error('No valid Atmospore config node');
+            node.status({ fill: 'red', shape: 'ring', text: 'no config' });
+            return;
+        }
+
+        node.on('input', async function(msg, send, done) {
+            const lat = msg.lat || node.configNode.defaultLat;
+            const lon = msg.lon || node.configNode.defaultLon;
+            if (!lat || !lon) { done(new Error('Latitude and longitude are required (set in config node or msg.lat / msg.lon)')); return; }
+
+            try {
+                node.status({ fill: 'blue', shape: 'dot', text: 'fetching...' });
+                const data = await node.configNode.api.getPollenArea({
+                    lat, lon,
+                    dt: msg.dt,
+                    forecastDays: msg.forecastDays || node.forecastDays,
+                    species: msg.species || node.species,
+                    radius: msg.radius || node.radius,
+                });
+                msg.payload = data;
+                node.status({ fill: 'green', shape: 'dot', text: 'ok' });
+                send(msg);
+                done();
+            } catch (err) {
+                node.status({ fill: 'red', shape: 'ring', text: err.message });
+                done(err);
+            }
+        });
+    }
+
+    RED.nodes.registerType('atmospore-pollen-area', AtmosporePollenAreaNode);
+};

package/nodes/atmospore-pollen-top.html

@@ -0,0 +1,48 @@
+<script type="text/javascript">
+    RED.nodes.registerType('atmospore-pollen-top', {
+        category: 'Atmospore',
+        color: '#7fb069',
+        defaults: {
+            name: { value: '' },
+            configNode: { value: '', type: 'atmospore-config', required: true },
+            forecastDays: { value: 7 },
+        },
+        inputs: 1,
+        outputs: 1,
+        icon: 'font-awesome/fa-sort-amount-desc',
+        label: function() { return this.name || 'top pollen species'; },
+        paletteLabel: 'top species',
+    });
+</script>
+
+<script type="text/html" data-template-name="atmospore-pollen-top">
+    <div class="form-row">
+        <label for="node-input-name"><i class="fa fa-tag"></i> Name</label>
+        <input type="text" id="node-input-name" placeholder="Name">
+    </div>
+    <div class="form-row">
+        <label for="node-input-configNode"><i class="fa fa-cog"></i> Config</label>
+        <input type="text" id="node-input-configNode">
+    </div>
+    <div class="form-row">
+        <label for="node-input-forecastDays"><i class="fa fa-calendar"></i> Days</label>
+        <input type="number" id="node-input-forecastDays" min="1" max="14" style="width:60px"> <span style="color:#aaa">(1–14)</span>
+    </div>
+</script>
+
+<script type="text/html" data-help-name="atmospore-pollen-top">
+    <p>Top contributing pollen species for a date range, ranked by severity.</p>
+    <h3>Inputs</h3>
+    <dl class="message-properties">
+        <dt>payload <span class="property-type">any</span></dt><dd>Triggers a fetch.</dd>
+        <dt class="optional">lat / lon <span class="property-type">number</span></dt><dd>Override coordinates.</dd>
+        <dt class="optional">dt <span class="property-type">string</span></dt><dd>Start date (YYYY-MM-DD). Defaults to today.</dd>
+        <dt class="optional">forecastDays <span class="property-type">number</span></dt><dd>Number of days to aggregate over (1–14).</dd>
+    </dl>
+    <h3>Outputs</h3>
+    <dl class="message-properties">
+        <dt>payload <span class="property-type">object</span></dt>
+        <dd><code>data[]</code> — species ranked by severity, each with <code>species</code>, <code>display_name</code>, <code>category</code>, <code>avg</code>, <code>max</code>, and <code>risk_level</code>.</dd>
+    </dl>
+    <p>Example: <code>msg.payload.data[0].display_name</code> → the worst species over the period.</p>
+</script>

package/nodes/atmospore-pollen-top.js

@@ -0,0 +1,40 @@
+'use strict';
+
+module.exports = function(RED) {
+    function AtmosporePollenTopNode(config) {
+        RED.nodes.createNode(this, config);
+        const node = this;
+        node.configNode = RED.nodes.getNode(config.configNode);
+        node.forecastDays = config.forecastDays || 7;
+
+        if (!node.configNode || !node.configNode.api) {
+            node.error('No valid Atmospore config node');
+            node.status({ fill: 'red', shape: 'ring', text: 'no config' });
+            return;
+        }
+
+        node.on('input', async function(msg, send, done) {
+            const lat = msg.lat || node.configNode.defaultLat;
+            const lon = msg.lon || node.configNode.defaultLon;
+            if (!lat || !lon) { done(new Error('Latitude and longitude are required (set in config node or msg.lat / msg.lon)')); return; }
+
+            try {
+                node.status({ fill: 'blue', shape: 'dot', text: 'fetching...' });
+                const data = await node.configNode.api.getPollenTop({
+                    lat, lon,
+                    dt: msg.dt,
+                    forecastDays: msg.forecastDays || node.forecastDays,
+                });
+                msg.payload = data;
+                node.status({ fill: 'green', shape: 'dot', text: 'ok' });
+                send(msg);
+                done();
+            } catch (err) {
+                node.status({ fill: 'red', shape: 'ring', text: err.message });
+                done(err);
+            }
+        });
+    }
+
+    RED.nodes.registerType('atmospore-pollen-top', AtmosporePollenTopNode);
+};

package/nodes/atmospore-pollen.html

@@ -0,0 +1,59 @@
+<script type="text/javascript">
+    RED.nodes.registerType('atmospore-pollen', {
+        category: 'Atmospore',
+        color: '#7fb069',
+        defaults: {
+            name: { value: '' },
+            configNode: { value: '', type: 'atmospore-config', required: true },
+            forecastDays: { value: 1 },
+            species: { value: 'all' },
+        },
+        inputs: 1,
+        outputs: 1,
+        icon: 'font-awesome/fa-leaf',
+        label: function() { return this.name || 'pollen forecast'; },
+        paletteLabel: 'pollen forecast',
+    });
+</script>
+
+<script type="text/html" data-template-name="atmospore-pollen">
+    <div class="form-row">
+        <label for="node-input-name"><i class="fa fa-tag"></i> Name</label>
+        <input type="text" id="node-input-name" placeholder="Name">
+    </div>
+    <div class="form-row">
+        <label for="node-input-configNode"><i class="fa fa-cog"></i> Config</label>
+        <input type="text" id="node-input-configNode">
+    </div>
+    <div class="form-row">
+        <label for="node-input-forecastDays"><i class="fa fa-calendar"></i> Days</label>
+        <input type="number" id="node-input-forecastDays" min="1" max="14" style="width:60px"> <span style="color:#aaa">(1–14, overridable via msg.forecastDays)</span>
+    </div>
+    <div class="form-row">
+        <label for="node-input-species"><i class="fa fa-filter"></i> Species</label>
+        <select id="node-input-species" style="width:70%">
+            <option value="all">All</option>
+            <option value="tree">Trees only</option>
+            <option value="grass">Grass only</option>
+            <option value="weed">Weeds only</option>
+        </select>
+    </div>
+</script>
+
+<script type="text/html" data-help-name="atmospore-pollen">
+    <p>Interpolated pollen forecast at a specific coordinate.</p>
+    <h3>Inputs</h3>
+    <dl class="message-properties">
+        <dt>payload <span class="property-type">any</span></dt><dd>Triggers a fetch.</dd>
+        <dt class="optional">lat / lon <span class="property-type">number</span></dt><dd>Override the config node's default coordinates.</dd>
+        <dt class="optional">dt <span class="property-type">string</span></dt><dd>Start date (YYYY-MM-DD). Defaults to today.</dd>
+        <dt class="optional">forecastDays <span class="property-type">number</span></dt><dd>Number of days (1–14).</dd>
+        <dt class="optional">species <span class="property-type">string</span></dt><dd><code>all</code>, <code>tree</code>, <code>grass</code>, <code>weed</code>, or a comma-separated species list.</dd>
+    </dl>
+    <h3>Outputs</h3>
+    <dl class="message-properties">
+        <dt>payload <span class="property-type">object</span></dt>
+        <dd><code>data[]</code> — one entry per day with <code>date</code>, <code>overall_risk</code>, and a <code>species</code> object keyed by species name.</dd>
+    </dl>
+    <p>Example: <code>msg.payload.data[0].species.birch.risk_level</code> → <code>"high"</code></p>
+</script>

package/nodes/atmospore-pollen.js

@@ -0,0 +1,42 @@
+'use strict';
+
+module.exports = function(RED) {
+    function AtmosporePollenNode(config) {
+        RED.nodes.createNode(this, config);
+        const node = this;
+        node.configNode = RED.nodes.getNode(config.configNode);
+        node.forecastDays = config.forecastDays || 1;
+        node.species = config.species || 'all';
+
+        if (!node.configNode || !node.configNode.api) {
+            node.error('No valid Atmospore config node');
+            node.status({ fill: 'red', shape: 'ring', text: 'no config' });
+            return;
+        }
+
+        node.on('input', async function(msg, send, done) {
+            const lat = msg.lat || node.configNode.defaultLat;
+            const lon = msg.lon || node.configNode.defaultLon;
+            if (!lat || !lon) { done(new Error('Latitude and longitude are required (set in config node or msg.lat / msg.lon)')); return; }
+
+            try {
+                node.status({ fill: 'blue', shape: 'dot', text: 'fetching...' });
+                const data = await node.configNode.api.getPollen({
+                    lat, lon,
+                    dt: msg.dt,
+                    forecastDays: msg.forecastDays || node.forecastDays,
+                    species: msg.species || node.species,
+                });
+                msg.payload = data;
+                node.status({ fill: 'green', shape: 'dot', text: 'ok' });
+                send(msg);
+                done();
+            } catch (err) {
+                node.status({ fill: 'red', shape: 'ring', text: err.message });
+                done(err);
+            }
+        });
+    }
+
+    RED.nodes.registerType('atmospore-pollen', AtmosporePollenNode);
+};

package/nodes/atmospore-species.html

@@ -0,0 +1,35 @@
+<script type="text/javascript">
+    RED.nodes.registerType('atmospore-species', {
+        category: 'Atmospore',
+        color: '#7fb069',
+        defaults: {
+            name: { value: '' },
+            configNode: { value: '', type: 'atmospore-config', required: true },
+        },
+        inputs: 1,
+        outputs: 1,
+        icon: 'font-awesome/fa-list',
+        label: function() { return this.name || 'species metadata'; },
+        paletteLabel: 'species metadata',
+    });
+</script>
+
+<script type="text/html" data-template-name="atmospore-species">
+    <div class="form-row">
+        <label for="node-input-name"><i class="fa fa-tag"></i> Name</label>
+        <input type="text" id="node-input-name" placeholder="Name">
+    </div>
+    <div class="form-row">
+        <label for="node-input-configNode"><i class="fa fa-cog"></i> Config</label>
+        <input type="text" id="node-input-configNode">
+    </div>
+</script>
+
+<script type="text/html" data-help-name="atmospore-species">
+    <p>Fetches metadata for all 25 supported pollen species — display names, multilingual names, categories, and risk thresholds. No authentication required. Cache this response and refresh infrequently.</p>
+    <h3>Outputs</h3>
+    <dl class="message-properties">
+        <dt>payload <span class="property-type">object</span></dt>
+        <dd><code>data</code> — object keyed by species identifier, each with <code>display_name</code>, <code>category</code>, <code>names</code> (multilingual), and <code>risk_thresholds</code>.</dd>
+    </dl>
+</script>

package/nodes/atmospore-species.js

@@ -0,0 +1,31 @@
+'use strict';
+
+module.exports = function(RED) {
+    function AtmosporeSpeciesNode(config) {
+        RED.nodes.createNode(this, config);
+        const node = this;
+        node.configNode = RED.nodes.getNode(config.configNode);
+
+        if (!node.configNode || !node.configNode.api) {
+            node.error('No valid Atmospore config node');
+            node.status({ fill: 'red', shape: 'ring', text: 'no config' });
+            return;
+        }
+
+        node.on('input', async function(msg, send, done) {
+            try {
+                node.status({ fill: 'blue', shape: 'dot', text: 'fetching...' });
+                const data = await node.configNode.api.getSpecies();
+                msg.payload = data;
+                node.status({ fill: 'green', shape: 'dot', text: 'ok' });
+                send(msg);
+                done();
+            } catch (err) {
+                node.status({ fill: 'red', shape: 'ring', text: err.message });
+                done(err);
+            }
+        });
+    }
+
+    RED.nodes.registerType('atmospore-species', AtmosporeSpeciesNode);
+};

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "node-red-contrib-atmospore",
+  "version": "0.1.0",
+  "description": "Node-RED nodes for the Atmospore Pollen Forecast API — point forecasts, area averages, top species",
+  "keywords": [
+    "node-red",
+    "atmospore",
+    "pollen",
+    "forecast",
+    "allergy",
+    "air quality"
+  ],
+  "author": "David Karlsson",
+  "license": "MIT",
+  "engines": {
+    "node": ">=14.0.0"
+  },
+  "node-red": {
+    "version": ">=2.0.0",
+    "nodes": {
+      "atmospore-config": "nodes/atmospore-config.js",
+      "atmospore-pollen": "nodes/atmospore-pollen.js",
+      "atmospore-pollen-area": "nodes/atmospore-pollen-area.js",
+      "atmospore-pollen-top": "nodes/atmospore-pollen-top.js",
+      "atmospore-species": "nodes/atmospore-species.js"
+    }
+  },
+  "dependencies": {
+    "node-fetch": "^2.7.0"
+  }
+}