# Heat Stress Work/Rest Guidance Calculator — API > A free, public REST API that turns workplace heat conditions (WBGT, workload, > acclimatization, shift window, PPE, location) into occupational work/rest > schedules, hydration guidance, and stop-work triggers. It evaluates 168 > registered national, international, and industry heat standards at once and > returns the most-protective composite. Built for La Isla Network (LIN); > defaults to the LIN-informed RSH-s protocol. Standards are never averaged. Base URL: https://heatrules.com All responses are JSON. CORS is open (`Access-Control-Allow-Origin: *`). **Read this first if you are an AI agent:** [skill.md](https://heatrules.com/skill.md) is the complete how-to-call guide, written for you. [openapi.json](https://heatrules.com/openapi.json) is the machine-readable OpenAPI 3.1 contract for generating a typed client or tool. ## Calling rules (important — the API will 403 you otherwise) - Send a descriptive `User-Agent` header of at least 8 characters (e.g. `MyAgent/1.0`). Empty/short UAs are rejected on `/api/v1/*`. - Do NOT use a search-crawler User-Agent (googlebot, bingbot, etc.) or identify as a Cloudflare-verified bot — those are blocked on API paths. - Requests from selected proxy/VPN-hosting ASNs are rejected on API paths (`403 Access denied.`). - Rate limits: 20 requests / 10s (burst) and 120 requests / 60s (sustained) per IP. Honor `Retry-After` on HTTP 429. Limits are best-effort per Cloudflare datacenter, not a globally consistent quota, and are not flood protection. - `robots.txt` disallows `/api/v1/` for all crawlers. These docs (`/llms.txt`, `/skill.md`, `/openapi.json`) and `/health` are exempt from every check above. ## Core endpoints - [GET /health](https://heatrules.com/health): liveness check, returns `{"ok": true}`. - [GET /api/v1/standards](https://heatrules.com/api/v1/standards): all 168 standards with metadata, required/optional inputs, and jurisdictions. - `GET /api/v1/standards?country=XX`: the COUNTRY MANIFEST — only the standards that govern that country (its own rules plus every global/bloc framework), each WITH its `parameters` and `details`, plus an `inputContract` of what to collect. Add `®ion=US-TX` to keep only that state's state rules; an unknown country code is a 400. Use it to stand up your own calculator for one country; run it with `guidance/country`. - `POST /api/v1/compare`: evaluate all or selected standards; returns per-standard results, the most-protective `composite`, and `derivedOutputs` (hydration, AKI risk, productivity, shift calendar). - `POST /api/v1/standards/{standardId}/evaluate`: evaluate one standard. - `POST /api/v1/guidance/country?country=XX`: same as compare, filtered/ranked to a country. ## Weather & geo helpers - `GET /api/v1/wbgt?lat=&lon=&date=&time=`: forecast-estimated WBGT for a coordinate (Open-Meteo, NWS US fallback, MET Norway worldwide fallback). - `GET /api/v1/weather/wbgt?lat=&lon=`: same estimator, browser-app variant (no `time` alias). - `GET /api/v1/weather/wbgt-history?lat=&lon=&month=YYYY-MM`: hourly WBGT for one COMPLETED calendar month from the ERA5 archive, unsliced (array is `hours`, not `hourlyWbgt`); coordinates are rounded to 0.1° (ERA5 grid is ~0.25°). Reanalysis, not measurement. 400 on an incomplete month or one before ERA5 begins (1940-01) — never a substituted month. - `GET /api/v1/weather/wbgt-history-chart?lat=&lon=&month=YYYY-MM`: the same completed month with the four LIN standards (niosh_table, niosh_curve, acgih_tlv_action_limit, iso_7243) evaluated server-side — each hour carries `work`, schedulable work minutes for all 12 workload×acclimatization combos (0 ⇔ stop work), plus the `combos` order and `buckets` legend edges. Built for the LIN partner-host History page so it ships no formulas; same month validation and 400 semantics as wbgt-history. - `GET /api/v1/weather/wbgt-seasonal?lat=&lon=`: ECMWF SEAS5 per-month daily-max temperature statistics for a warmer/cooler-than-normal label. NOT a WBGT source — SEAS5 is daily-only and carries no hourly wind, solar or humidity. - `GET /api/v1/weather/air-quality?lat=&lon=&days=`: PM2.5-derived AQI for wildfire-smoke overlays. - `GET /api/v1/geo/search?q=` or `?zip=&country=`: geocode a place name or postal code to candidate coordinates. - `GET /api/v1/geo/country`: Cloudflare-detected country/region/coarse coordinates for the caller; with `?latitude=&longitude=` it resolves a worksite to its country and (US/CA/IN/CN) state, e.g. `subnationalCode: "US-CA"`. - `/embed/heat-rules.js`: the vended calculator (engine + `HeatRules` helper) for running a country manifest over `wbgt-history` hours in a third-party browser; see skill.md "Running the manifest in a third-party browser" and the complete sample page examples/embed/heat-rules-embed.html. - `GET /api/v1/weather/es-heat-alert?lat=&lon=`: official AEMET heat aviso (Spain only). - `GET /api/v1/weather/fr-vigilance?lat=&lon=`: official Météo-France canicule vigilance (France only). - `GET /api/v1/weather/at-heat-alert?lat=&lon=`: official GeoSphere Austria heat warning (Austria only). ## Key concepts - **WBGT** = Wet Bulb Globe Temperature (°C by default; pass `wbgtUnit: "F"` for °F). - **workload** ∈ `light | moderate | heavy | very_heavy`. - **acclimatization** ∈ `unacclimatized | partial | acclimatized | unknown | new`. - **composite** = most-protective applicable schedule (min work min/hr, max rest min/hr, stop-work override). Never an average. - **ruleType** classifies each standard: `schedule_engine`, `mixed_trigger_schedule`, and `stop_work_rule` feed the composite; `screening_limit`, `control_overlay`, `alert_overlay`, and `smoke_overlay` are advisory and are reported separately in `composite.advisoryStandards`. - Standards that lack required inputs are not guessed — they return `applicable: false` with `missingInputs`. ## Update feeds (RSS) - `/feed.xml` — every change to every standard, newest first. - `/standards//feed.xml` — one standard. - `/countries//feed.xml` — every standard tracked for one country. - Index of all feeds: `/feeds/`. - Items are derived by measuring what each engine actually outputs across a fixed scenario grid, so an item means the guidance moved — not that a file was edited. `` carries the change type (`added`, `guidance_changed`, `scope_changed`, `removed`) and, where one can be computed, the direction (`less_protective`, `more_protective`, `mixed`, `not_expressible`). - `` is content-addressed and stable across history rewrites; poll with conditional GETs and dedupe on it. ## Safety This API returns decision-support guidance, not a substitute for a qualified safety professional or a legally binding determination. Measured on-site WBGT is more trustworthy than the forecast estimate. Always surface uncertainty (`confidence`, `warnings`) to the end user.