Methodology

How the score is built, and what it cannot tell you

GreenShield keeps three things separate: measurements returned by an API, numbers GreenShield computes from them, and prose an AI model writes about both. Everything on this page is the middle category, spelled out in full.

1. The pipeline

GS CALC

STEP 1
Location search or map click resolves to coordinates via Open-Meteo Geocoding or OSM Nominatim.
STEP 2
Forecast and air-quality endpoints are called in parallel for those coordinates.
STEP 3
Each hazard component is converted to 0–100 through a published piecewise-linear curve.
STEP 4
Components are combined with fixed weights into the composite Environmental Risk Score.
STEP 5
Rule-based actions are derived from the sub-scores; AI text is optional and additive.

2. Sub-scores, weights and breakpoints

Composite score = Σ (sub-score × weight), clamped to 0–100 and rounded. Weights sum to 1.00. Every curve is piecewise-linear between the anchor points listed — values below the first anchor score 0, values above the last score 100.

Heat risk

weight 32%

piecewise(max(current apparent temperature, apparent max of next 3 forecast days), heat breakpoints)

Anchor points · °C apparent

24 → 030 → 2535 → 5040 → 7546 → 100

Apparent temperature already folds in humidity and wind, so it tracks physiological load better than dry-bulb air temperature.

Air quality risk

weight 30%

max(piecewise(PM2.5), piecewise(PM10), piecewise(ozone)) — worst pollutant governs

Anchor points · µg/m³ PM2.5 (PM10 and ozone use their own curves)

0 → 015 → 2535 → 5055 → 75110 → 100

Breakpoints are anchored to WHO 2021 guideline values: 15 µg/m³ PM2.5 and 45 µg/m³ PM10 map to 25/100.

Rainfall / flood risk

weight 18%

max(piecewise(heaviest single forecast day), piecewise(7-day forecast total))

Anchor points · mm in one day (weekly totals use a separate curve)

0 → 010 → 2025 → 4550 → 70100 → 100

This is a rainfall-intensity proxy, not a hydrological flood model — it knows nothing about terrain, drainage or river state.

Humidity stress

weight 10%

piecewise(deviation outside the 30–60 % comfort band) × heat factor (1.0 at ≥28 °C, 0.6 at ≥20 °C, else 0.35)

Anchor points · percentage points outside the comfort band

0 → 010 → 2525 → 6040 → 100

Humid heat suppresses sweat evaporation, so the same humidity scores far higher on a hot day than a cold one.

UV exposure

weight 10%

piecewise(max(current UV index, UV max of next 3 forecast days))

Anchor points · WHO UV index

0 → 03 → 206 → 458 → 6511 → 100

The WHO UV scale is already a risk scale; the curve simply rescales it to 0–100.

3. Severity bands

0–19

Low

20–39

Moderate

40–59

Elevated

60–79

High

80–100

Severe

4. Data sources

Source	Provides	Cadence	Credentials
Open-Meteo Forecast API	Current temperature, apparent temperature, humidity, precipitation, wind, UV index, weather code, 7-day daily and 48-hour hourly forecasts	Hourly model output, refreshed by GreenShield every 5 minutes on demand	No API key
Open-Meteo Air Quality API	PM2.5, PM10, ozone, NO2, SO2, CO, European AQI, US AQI, 48-hour hourly particulate trace	Hourly CAMS model output at ~11 km resolution	No API key
Open-Meteo Historical Weather API (ERA5)	Daily mean/max temperature and precipitation for the last 20 complete years	Reanalysis, lags roughly 5 days; cached 24 hours	No API key
Open-Meteo Geocoding API	Place-name search and coordinates, with admin area, country and population	On each search keystroke, debounced	No API key
OpenStreetMap Nominatim	Reverse geocoding for points picked directly on the map	On map click	No API key
OpenStreetMap tiles via Leaflet	Base map imagery	On demand	No API key
Google Gemini API	Chat answers and AI-authored intervention lists, generated only from the GreenShield data brief	On explicit user action	Server-side API key, never exposed to the browser

5. Limitations

Air-quality values are modelled on an ~11 km grid, not measured at street level. A nearby highway, kiln or construction site can push local exposure far above what is shown.
The rainfall component measures precipitation intensity only. It is not a flood model: it has no terrain, drainage capacity, soil saturation or river-stage input.
Weights were chosen for a general urban-resident risk profile. A farmer, an asthma patient and a logistics planner would each weight these hazards differently.
Forecast skill degrades with lead time; days 4–7 of the outlook are indicative rather than reliable.
The historical trend uses a single ERA5 grid cell, which smooths local microclimate and urban heat-island effects.
When every live request fails, GreenShield switches to a clearly labelled archived demo snapshot rather than showing blank panels or invented values.
AI text is an interpretation layer. It is instructed to cite only numbers present in the data brief and to state when a value is missing, but it is not a substitute for professional advice.

6. Attribution

Weather, air-quality, historical and geocoding data by Open-Meteo (CC BY 4.0). Map data and tiles © OpenStreetMap contributors (ODbL). Reverse geocoding by OpenStreetMap Nominatim. GreenShield scoring model v1 — built for Hack the Habitat 2026.