{ "components": { "schemas": { "AggregateFeatureProperties": { "allOf": [ { "$ref": "#/components/schemas/FeaturePropertiesBase" }, { "properties": { "arrheniusThermalTime": { "description": "Species-agnostic, base-free site index: Boltzmann-Arrhenius thermal time accumulated to the instant, in reference-temperature-equivalent days (a day at referenceTempC contributes 1.0). Each day uses the 2-point rate mean of Tmin and Tmax. Unlike a GDD base, referenceTempC is only a normalising constant, so values at different references are interconvertible.\n", "properties": { "activationEnergyEv": { "description": "Activation energy (eV), MTE value 0.65.", "type": "number" }, "days": { "description": "Number of days summed.", "type": "integer" }, "method": { "type": "string" }, "referenceTempC": { "description": "Normalisation reference temperature (°C), fixed at 20.", "type": "number" }, "value": { "description": "Accumulated index (referenceTempC-equivalent days).", "type": "number" } }, "type": "object" }, "growingDegreeDays": { "description": "Growing-degree-days accumulated from the start of the growing year to the instant (average method, floor 0, no upper cutoff). base5 and base10 are ALWAYS computed so a client cannot introduce inconsistency by silently changing the base over time; a per-request gddBase is added under custom.\n", "properties": { "base10": { "description": "GDD at base 10 °C (°C·d).", "type": "number" }, "base5": { "description": "GDD at base 5 °C (°C·d).", "type": "number" }, "custom": { "description": "GDD at the per-request gddBase (present only when gddBase is given).", "properties": { "baseCelsius": { "type": "number" }, "value": { "type": "number" } }, "type": "object" }, "days": { "description": "Number of days summed.", "type": "integer" }, "method": { "description": "GDD computation method.", "type": "string" }, "since": { "description": "Accumulation start date (YYYY-MM-DD): 1 Jan (northern) or 1 Jul (southern hemisphere).", "type": "string" } }, "type": "object" }, "kind": { "enum": [ "aggregate" ], "type": "string" }, "precipitation": { "description": "Precipitation sums (mm) ending at the instant.", "properties": { "last120h": { "description": "Sum over the preceding 5 days (mm).", "type": "number" }, "last24h": { "description": "Sum over the preceding 24 h (mm).", "type": "number" }, "last72h": { "description": "Sum over the preceding 72 h (mm).", "type": "number" } }, "type": "object" }, "temperatureDay": { "description": "The fund day's (UTC-day) temperature extrema in °C.", "properties": { "max": { "type": "number" }, "mean": { "type": "number" }, "min": { "type": "number" } }, "type": "object" } }, "required": [ "kind" ], "type": "object" } ], "description": "Properties of a weather-aggregate feature (kind \"aggregate\"), computed by tempus from an Open-Meteo archive range: antecedent precipitation sums, the fund day's temperature extrema, growing-degree-days, and an Arrhenius thermal-time site index accumulated up to the instant. Needs past data — a future instant makes the provider report a non-retryable error.\n" }, "BilingualLabel": { "description": "A label available in German and English.", "properties": { "de": { "description": "German label.", "type": "string" }, "en": { "description": "English label.", "type": "string" } }, "type": "object" }, "BioclimFeatureProperties": { "allOf": [ { "$ref": "#/components/schemas/FeaturePropertiesBase" }, { "properties": { "altitudinalBelt": { "description": "Climate-derived altitudinal belt (Höhenstufe) with the classic names (kollin … alpin … nival), isotherm-defined (treeline 6.4 °C, Paulsen \u0026 Körner 2014) and Central-Europe-calibrated so the names are directly comparable to FHL/Hegi belt statements — valid across all of Europe and globally. No elevation input; temperature encodes altitude.\n", "properties": { "adjacentBelt": { "description": "Nearer neighbouring belt (present only when borderline).", "properties": { "de": { "type": "string" }, "en": { "type": "string" } }, "type": "object" }, "basis": { "description": "Method, e.g. 'thermoclimatic isotherm, Central-Europe-calibrated'.", "type": "string" }, "belt": { "description": "Bilingual classic belt name.", "properties": { "de": { "type": "string" }, "en": { "type": "string" } }, "type": "object" }, "borderline": { "description": "True when within 0.5 °C of a belt boundary.", "type": "boolean" }, "indicators": { "description": "Deciding indicators (°C) — auditable basis for the belt.", "properties": { "biotemperatureC": { "description": "Holdridge biotemperature (mean of monthly means clamped to [0,30]).", "type": "number" }, "matC": { "description": "Annual mean temperature.", "type": "number" }, "warmestMonthC": { "type": "number" }, "warmestQuarterC": { "type": "number" } }, "type": "object" }, "source": { "description": "Citation for the belt/thermotype computation.", "type": "string" }, "thermotype": { "description": "Rivas-Martínez thermotype (formal, cross-Europe): horizon from positive temperature Tp × macrobioclimate suffix, e.g. orotemperate vs oromediterranean.\n", "properties": { "code": { "type": "string" }, "de": { "type": "string" }, "en": { "type": "string" } }, "type": "object" } }, "type": "object" }, "bio": { "description": "The 19 bioclimatic variables bio1…bio19 (WorldClim definitions). Temperatures °C, precipitation mm; bio3 isothermality (%), bio4 temperature seasonality (std×100), bio15 precipitation seasonality (coefficient of variation, %).\n", "type": "object" }, "kind": { "enum": [ "bioclim" ], "type": "string" }, "koppen": { "description": "Köppen-Geiger classification (Beck et al. 2018), computed from ERA5. coldestMonthMeanC is the value that decides the C/D boundary (0 °C). borderline flags that the point is within ~1.5 °C of a main-class temperature boundary, so a different dataset (e.g. a station-based Köppen raster) could yield the adjacent class — the classic reason a Cfb here can read as Dfb elsewhere.\n", "properties": { "adjacent": { "description": "The neighbouring main class (present only when borderline).", "properties": { "code": { "type": "string" }, "de": { "type": "string" }, "en": { "type": "string" } }, "type": "object" }, "borderline": { "description": "True when within ~1.5 °C of a Köppen main-class boundary.", "type": "boolean" }, "code": { "description": "Köppen-Geiger code, e.g. Cfb.", "type": "string" }, "coldestMonthMeanC": { "description": "Mean temperature of the coldest month (°C).", "type": "number" }, "de": { "description": "German description.", "type": "string" }, "en": { "description": "English description.", "type": "string" } }, "type": "object" }, "referencePeriod": { "description": "Reference period used, 'YYYY-YYYY' (e.g. '1991-2020').", "type": "string" } }, "required": [ "kind" ], "type": "object" } ], "description": "Properties of a bioclim feature (kind \"bioclim\"): the 19 WorldClim bioclimatic variables and the Köppen-Geiger class, computed by tempus from ERA5 monthly climate normals. Values are time-independent for a location and reference period; the period is chosen contemporaneously to the datetime's year (or via refPeriod), so historical records get period-appropriate values. Cached per coordinate + period.\n" }, "DewPointFeatureProperties": { "allOf": [ { "$ref": "#/components/schemas/FeaturePropertiesBase" }, { "properties": { "comfort": { "allOf": [ { "$ref": "#/components/schemas/BilingualLabel" } ], "description": "Bilingual (DE + EN) human-comfort classification of the dew point (e.g. \"sehr angenehm\" / \"very comfortable\"). Based on the standard meteorological dew-point comfort scale.\n" }, "comfortSource": { "description": "Source citation for the comfort classification, referencing the standard meteorological dew-point comfort scale.\n", "type": "string" }, "comfortSourceURL": { "description": "Canonical URL for the dew-point comfort scale, so a client can link the citation instead of only displaying it. Present whenever comfortSource is.\n", "format": "uri", "type": "string" }, "dewPoint2m": { "description": "Dew point at 2 m height in °C (rounded to 0.1 °C).", "type": "number" }, "kind": { "enum": [ "dewpoint" ], "type": "string" } }, "required": [ "kind" ], "type": "object" } ], "description": "Properties of a dew-point feature (kind \"dewpoint\") derived from the weather feature using the Magnus-Tetens formula. Includes the computed dew point, its unit, derivation metadata, and a bilingual comfort classification with source attribution.\n" }, "Error": { "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "type": "object" }, "Feature": { "properties": { "geometry": { "description": "GeoJSON geometry of the feature; always a Point for the current providers, carrying the coordinate the provider resolved the query to (which may differ from the requested one, e.g. a grid cell).\n", "type": "object" }, "license": { "$ref": "#/components/schemas/License" }, "properties": { "description": "The feature's properties. Which schema applies is decided by the kind property: the discriminator below maps each kind to the schema that documents it.\n", "discriminator": { "mapping": { "aggregate": "#/components/schemas/AggregateFeatureProperties", "bioclim": "#/components/schemas/BioclimFeatureProperties", "dewpoint": "#/components/schemas/DewPointFeatureProperties", "moon": "#/components/schemas/MoonFeatureProperties", "sun": "#/components/schemas/SunFeatureProperties", "weather": "#/components/schemas/WeatherFeatureProperties" }, "propertyName": "kind" }, "oneOf": [ { "$ref": "#/components/schemas/WeatherFeatureProperties" }, { "$ref": "#/components/schemas/DewPointFeatureProperties" }, { "$ref": "#/components/schemas/SunFeatureProperties" }, { "$ref": "#/components/schemas/MoonFeatureProperties" }, { "$ref": "#/components/schemas/AggregateFeatureProperties" }, { "$ref": "#/components/schemas/BioclimFeatureProperties" } ] }, "type": { "type": "string" } }, "type": "object" }, "FeaturePropertiesBase": { "description": "Properties every feature carries, whatever its kind. The concrete schema is selected by kind (see Feature.properties).\n", "properties": { "kind": { "description": "The feature's kind; the discriminator that selects the concrete property schema.\n", "type": "string" }, "observedAt": { "description": "The instant the feature describes (RFC3339, UTC). Absent on the bioclim feature, which describes a climate normal period and reports referencePeriod instead.\n", "format": "date-time", "type": "string" }, "provider": { "description": "Identifier of the provider or deriver that produced the feature (e.g. \"open-meteo\", \"dewpoint\", \"sun\").\n", "type": "string" }, "units": { "additionalProperties": { "type": "string" }, "description": "Unit per numeric property of this feature, keyed by property name (e.g. {\"temperature2m\": \"°C\", \"windSpeed10m\": \"km/h\"}).\n", "type": "object" } }, "required": [ "kind" ], "type": "object" }, "License": { "properties": { "attribution": { "type": "string" }, "name": { "type": "string" }, "url": { "type": "string" } }, "required": [ "name", "url", "attribution" ], "type": "object" }, "MoonFeatureProperties": { "allOf": [ { "$ref": "#/components/schemas/FeaturePropertiesBase" }, { "properties": { "ageDays": { "description": "Moon age since the last new moon (days).", "type": "number" }, "azimuthDeg": { "description": "Moon azimuth, degrees clockwise from true north.", "type": "number" }, "distanceKm": { "description": "Earth–moon centre distance (km).", "type": "number" }, "elevationDeg": { "description": "Moon elevation above the horizon (degrees, geocentric).", "type": "number" }, "illuminationPct": { "description": "Illuminated fraction of the moon's disc (percent).", "type": "number" }, "kind": { "enum": [ "moon" ], "type": "string" }, "moonrise": { "description": "Moonrise (RFC3339 UTC), or null when the moon does not rise that day.", "nullable": true, "type": "string" }, "moonset": { "description": "Moonset (RFC3339 UTC), or null when the moon does not set that day.", "nullable": true, "type": "string" }, "phase": { "allOf": [ { "$ref": "#/components/schemas/BilingualLabel" } ], "description": "Bilingual phase name (Neumond … abnehmende Sichel / New Moon … Waning Crescent).\n" }, "phaseAngleDeg": { "description": "Phase angle (degrees; 0 = full, 180 = new).", "type": "number" } }, "required": [ "kind" ], "type": "object" } ], "description": "Properties of a moon feature (kind \"moon\"), computed from the coordinate and instant via Meeus's lunar theory (geocentric approximation). Available for any date. Angles in degrees, azimuth clockwise from true north. Rise/set times are RFC3339 UTC, or null when no crossing occurs.\n" }, "ProviderInfo": { "properties": { "id": { "type": "string" }, "kind": { "type": "string" }, "license": { "$ref": "#/components/schemas/License" } }, "type": "object" }, "ProviderStatus": { "properties": { "cached": { "type": "boolean" }, "error": { "type": "string" }, "id": { "type": "string" }, "kind": { "type": "string" }, "retryAfter": { "description": "Go duration string indicating how long to wait before retrying (e.g. \"30s\", \"2h0m0s\")", "type": "string" }, "retryable": { "type": "boolean" }, "status": { "enum": [ "ok", "unavailable", "error" ], "type": "string" } }, "type": "object" }, "QueryResult": { "description": "Feature collection with per-provider status. The features[] array may include a weather feature (kind \"weather\") with WMO code descriptions (weatherCodeDescription DE/EN, weatherCodeSource) and a derived feature with kind \"dewpoint\" containing a dewPoint2m property (°C, Magnus-Tetens formula) plus a comfort classification (comfort DE/EN, comfortSource). It also includes a sun feature (kind \"sun\") and a moon feature (kind \"moon\"), computed for any date; see SunFeatureProperties and MoonFeatureProperties. It also includes a weather-aggregate feature (kind \"aggregate\"; see AggregateFeatureProperties) with antecedent precipitation, day temperature extrema and growing-degree-days, and a bioclim feature (kind \"bioclim\"; see BioclimFeatureProperties) with the 19 WorldClim variables, the Köppen-Geiger class and the climate-derived altitudinal belt (Höhenstufe) + Rivas-Martínez thermotype. The providers[] array may include entries with ids \"sun\", \"moon\", \"dewpoint\", \"aggregate\" and \"bioclim\" reflecting their status; for future instants the \"open-meteo\" weather and \"aggregate\" providers report a non-retryable error while sun and moon remain \"ok\".\n", "properties": { "features": { "items": { "$ref": "#/components/schemas/Feature" }, "type": "array" }, "providers": { "items": { "$ref": "#/components/schemas/ProviderStatus" }, "type": "array" }, "query": { "type": "object" } }, "type": "object" }, "SunFeatureProperties": { "allOf": [ { "$ref": "#/components/schemas/FeaturePropertiesBase" }, { "properties": { "azimuthDeg": { "description": "Sun azimuth, degrees clockwise from true north.", "type": "number" }, "dayLengthMinutes": { "description": "Length of daylight (minutes) between sunrise and sunset.", "type": "number" }, "elevationDeg": { "description": "Sun elevation above the horizon (degrees).", "type": "number" }, "kind": { "enum": [ "sun" ], "type": "string" }, "lightPhase": { "allOf": [ { "$ref": "#/components/schemas/BilingualLabel" } ], "description": "Bilingual light-regime label: day, civil / nautical / astronomical twilight, or night.\n" }, "solarNoon": { "description": "Solar noon (RFC3339 UTC).", "nullable": true, "type": "string" }, "solarNoonElevationDeg": { "description": "Sun elevation at solar noon (degrees).", "type": "number" }, "sunrise": { "description": "Sunrise (RFC3339 UTC) for the day, or null (polar day/night).", "nullable": true, "type": "string" }, "sunset": { "description": "Sunset (RFC3339 UTC) for the day, or null (polar day/night).", "nullable": true, "type": "string" }, "twilight": { "description": "Civil (−6°), nautical (−12°) and astronomical (−18°) twilight, each with a dawn and dusk time (RFC3339 UTC or null).\n", "properties": { "astronomical": { "type": "object" }, "civil": { "type": "object" }, "nautical": { "type": "object" } }, "type": "object" }, "zenithDeg": { "description": "Solar zenith angle (90 − elevation), degrees.", "type": "number" } }, "required": [ "kind" ], "type": "object" } ], "description": "Properties of a sun feature (kind \"sun\"), computed from the coordinate and instant via the NOAA solar approximation. Available for any date (past or future). All angles are in degrees; azimuth is measured clockwise from true north. Event times are RFC3339 UTC, or null when the event does not occur that day (polar day/night at the given threshold).\n" }, "WeatherFeatureProperties": { "allOf": [ { "$ref": "#/components/schemas/FeaturePropertiesBase" }, { "properties": { "isDay": { "description": "Whether it is daytime at the queried location and instant. Computed from the sun's elevation angle (NOAA Spencer approximation); true when the sun is above −0.833° (refraction + solar radius threshold). Not sourced from the weather provider.\n", "type": "boolean" }, "isDaySource": { "description": "Citation for the isDay computation: \"Tag/Nacht aus Sonnenstand berechnet (NOAA-Näherung), tempus\".\n", "type": "string" }, "kind": { "enum": [ "weather" ], "type": "string" }, "weatherCode": { "description": "WMO weather-interpretation code (Code Table 4677, Open-Meteo subset).\n", "type": "integer" }, "weatherCodeDescription": { "allOf": [ { "$ref": "#/components/schemas/BilingualLabel" } ], "description": "Bilingual (DE + EN) human-readable description of the WMO weather code; present when the code is a known WMO Code Table 4677 value.\n" }, "weatherCodeSource": { "description": "Source citation for the weatherCodeDescription, referencing \"WMO Code Table 4677 (WW – present weather); weather-interpretation codes as used by Open-Meteo\".\n", "type": "string" }, "weatherCodeSourceURL": { "description": "Canonical URL for the weather-code table, so a client can link the citation instead of only displaying it. Present whenever weatherCodeSource is.\n", "format": "uri", "type": "string" }, "windBeaufort": { "description": "Beaufort wind force (0–12) derived from windSpeed10m using the published km/h class bounds (0: \u003c1, 1: 1–5, 2: 6–11, 3: 12–19, 4: 20–28, 5: 29–38, 6: 39–49, 7: 50–61, 8: 62–74, 9: 75–88, 10: 89–102, 11: 103–117, 12: ≥118). Absent when windSpeed10m is missing, not finite, or reported without a unit or in an unrecognised one.\n", "maximum": 12, "minimum": 0, "type": "integer" }, "windBeaufortDescription": { "allOf": [ { "$ref": "#/components/schemas/BilingualLabel" } ], "description": "Bilingual (DE + EN) name of the Beaufort force (e.g. \"frische Brise\" / \"Fresh breeze\"); present whenever windBeaufort is present.\n" }, "windBeaufortSource": { "description": "Source citation for windBeaufort, referencing \"Beaufort-Skala (WMO), abgeleitet aus der Windgeschwindigkeit in 10 m, tempus\".\n", "type": "string" }, "windBeaufortSourceURL": { "description": "Canonical URL for the Beaufort scale, so a client can link the citation instead of only displaying it. Present whenever windBeaufortSource is.\n", "format": "uri", "type": "string" } }, "required": [ "kind" ], "type": "object" } ], "description": "Properties of a weather feature (kind \"weather\") returned by the Open-Meteo provider. In addition to numeric measurements such as temperature2m, relativeHumidity2m, precipitation, windSpeed10m, cloudCover, and weatherCode, the feature carries isDay (computed from the sun's elevation angle via the NOAA approximation, not from the weather provider — Open-Meteo's archive is_day is unreliable for historical dates), isDaySource (citation for the solar computation), a bilingual human-readable explanation of the WMO weather code and its source citation, plus the Beaufort wind force derived from windSpeed10m.\n" } } }, "info": { "description": "Coordinate + time feature queries with per-feature attribution.", "title": "tempus API", "version": "0.1.0" }, "openapi": "3.0.3", "paths": { "/providers": { "get": { "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "providers": { "items": { "$ref": "#/components/schemas/ProviderInfo" }, "type": "array" } }, "type": "object" } } }, "description": "Provider list" } }, "summary": "List available providers and their attribution" } }, "/query": { "get": { "parameters": [ { "in": "query", "name": "lat", "required": true, "schema": { "type": "number" } }, { "in": "query", "name": "lon", "required": true, "schema": { "type": "number" } }, { "description": "RFC3339 or YYYY-MM-DDTHH:MM[:SS]; no offset =\u003e UTC. Future instants are allowed: astronomy providers (sun/moon) compute for any date, while providers that cannot serve the future (weather) report a non-retryable error status in the envelope.", "in": "query", "name": "datetime", "required": true, "schema": { "type": "string" } }, { "description": "comma-separated provider ids", "in": "query", "name": "providers", "required": false, "schema": { "type": "string" } }, { "description": "Optional base temperature (°C, [-50,50]) for the aggregate provider's growing-degree-day accumulation. Omit to use the server default (10 °C).", "in": "query", "name": "gddBase", "required": false, "schema": { "type": "number" } }, { "description": "Optional reference period 'YYYY-YYYY' (start ≥ 1940) for the bioclim provider. Omit to auto-select the contemporaneous 30-year WMO normal (the period containing the datetime's year, or 1991-2020 for later years).", "in": "query", "name": "refPeriod", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueryResult" } } }, "description": "Feature collection with per-provider status" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Invalid request" } }, "summary": "Query cached feature providers for a coordinate and time" } } }, "servers": [ { "url": "/api/v1" } ] }