# 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 93
> 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 93 standards with metadata, required/optional inputs, and jurisdictions.
- `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).
- `GET /api/v1/weather/wbgt?lat=&lon=`: same estimator, browser-app variant (no `time` alias).
- `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.
- `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`.

## 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.