# ThermoCast

> ThermoCast is a public HTTP service that serves machine-learned thermospheric
> mass-density predictions (kg/m^3) at altitudes between 250 km and 600 km — the
> regime occupied by most low-Earth-orbit satellites. It is intended for
> satellite-drag, orbit-determination, and space-weather workflows. The current
> model returns point predictions only; it does not emit per-prediction
> uncertainty.

Operated by Trillium Technologies (https://trillium.tech).

## Primary resources

- [Interactive visualizer](https://thermocast.spaceml.org/): 3D globe browser for density fields.
- [API docs (Swagger UI)](https://thermocast.spaceml.org/api/docs): human-readable API reference.
- [API docs (ReDoc)](https://thermocast.spaceml.org/api/redoc): alternative API reference.
- [OpenAPI specification](https://thermocast.spaceml.org/api/openapi.json): machine-readable spec. **Agents: start here.**
- [Long-form agent docs](https://thermocast.spaceml.org/llms-full.txt): conceptual documentation, conventions, glossary, and worked examples in a single fetch.
- [Model metadata](https://thermocast.spaceml.org/api/about): currently loaded model version, training date, supported altitude range, and valid datetime range.

## API endpoints

All forecast endpoints accept an optional ISO-8601 `date_time` query parameter.
If omitted, a fixed default date is used (see `/about` for the valid range).
Every response carries `X-Model-Version`, `X-Model-Train-Date`, and
`X-Thermocast-Version` headers so callers can pin the exact model that
produced a response.

- `GET /api/surface?altitude={250|300|350|400|450|500|550|600}&date_time=...` — 100x100 lat/lon grid of mass density at one altitude.
- `GET /api/surface/all?date_time=...` — density grids at every supported altitude in one call. Prefer this over eight `/surface` calls.
- `GET /api/altitude?latitude=...&longitude=...&date_time=...` — vertical density profile at one location.
- `GET /api/density?latitude=...&longitude=...&altitude=...&date_time=...` — single-point prediction. Prefer the batch endpoints unless you genuinely need one point.
- `GET /api/geomag?date_time=...` — Kp, Dst, and F10.7 indices (hourly) used as model drivers.
- `GET /api/about` — model and coverage metadata.

## Conventions

- Density values are mass density in kg/m^3 (not number density, not log-density).
- Returned `latitude`/`longitude` arrays are flattened row-major (longitude varies fastest) and align element-wise with flattened density grids.
- Altitudes are in kilometres; locations are in degrees.
- Timestamps are treated as UTC.
- Forecast endpoints are cached for 120s server-side (300s for `/geomag`); `Cache-Control` headers reflect this.

## When this tool is and isn't the right call

- **Use ThermoCast when** a workflow needs thermospheric mass density along a satellite trajectory, for atmospheric-drag modelling, or for visualising density structure at LEO altitudes.
- **Do not use ThermoCast for** altitudes below 250 km or above 600 km, uncertainty-quantified forecasts, or datetimes outside the range reported by `/about`.