> ## Documentation Index
> Fetch the complete documentation index at: https://api-docs.iklim.co/llms.txt
> Use this file to discover all available pages before exploring further.
# Forecast Notification
> Multi-day weather forecast alarm payloads with per-metric violation details and district-level location context.
The alarm evaluates daily forecast data for up to 14 days ahead, so you can prepare before adverse conditions arrive.
Every payload carries precise coordinates alongside city and district identifiers, making geo-routing effortless.
Only metrics that actually breach your configured thresholds appear in `violations` — no noise, no guesswork.
```json theme={null}
{
"id": "a1b2c3d4-0000-4e5f-9876-000000000001",
"registrationId": "f7587d9e-2481-4b4c-818d-c8d1946851b7",
"recipientId": "customer-user-001",
"notificationTime": "2025-09-14T04:00:15.123",
"latitude": 39.9334,
"longitude": 32.8597,
"cityId": 6,
"city": "Ankara",
"districtId": 557,
"district": "Çankaya",
"distance": 1243.58,
"violations": [
{
"metric": "PRECIPITATION",
"unit": "mm",
"forecasts": [
{ "time": "2025-09-14T00:00:00Z", "value": 12.4 },
{ "time": "2025-09-15T00:00:00Z", "value": 18.1 }
]
},
{
"metric": "SNOWFALL",
"unit": "cm",
"forecasts": [
{ "time": "2025-09-14T00:00:00Z", "value": 8.5 }
]
},
{
"metric": "WIND_GUSTS_MAX",
"unit": "km/h",
"forecasts": [
{ "time": "2025-09-14T00:00:00Z", "value": 75.2 },
{ "time": "2025-09-15T00:00:00Z", "value": 82.0 }
]
},
{
"metric": "TEMPERATURE_MIN",
"unit": "°C",
"forecasts": [
{ "time": "2025-09-14T00:00:00Z", "value": -3.5 },
{ "time": "2025-09-15T00:00:00Z", "value": -5.1 }
]
},
{
"metric": "TEMPERATURE_MAX",
"unit": "°C",
"forecasts": [
{ "time": "2025-09-14T00:00:00Z", "value": 38.5 },
{ "time": "2025-09-15T00:00:00Z", "value": 40.1 }
]
}
]
}
```
| Field | Type | Description |
| ------------------ | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id` | string | Unique UUID generated for this specific alarm event delivery. |
| `registrationId` | string | UUID of the alarm registration that produced this delivery. |
| `recipientId` | string | Caller-supplied identifier that ties the notification back to your internal customer/asset record (no need to use human-readable values — hashed/anonymous IDs are fine for GDPR compliance); keep it unique per monitoring point because only one registration per `recipientId` is allowed for the same location, letting you route the alert without storing our `registrationId`. |
| `notificationTime` | string | ISO-8601 date-time (UTC) of when the alarm notification was dispatched (e.g. `2025-09-14T04:00:15.123`). |
| `latitude` | number | WGS84 latitude of the monitoring point. **`ADMINISTRATIVE`**: centroid of the registered district. **`POINT`**: the exact latitude supplied when the alarm was registered. |
| `longitude` | number | WGS84 longitude of the monitoring point. **`ADMINISTRATIVE`**: centroid of the registered district. **`POINT`**: the exact longitude supplied when the alarm was registered. |
| `cityId` | number | Numeric identifier of the city (province). **`ADMINISTRATIVE`**: the city ID supplied at registration. **`POINT`**: the city ID of the district whose forecast covers the registered coordinate. |
| `city` | string | Human-readable city name. Populated for `ADMINISTRATIVE` registrations; `null` for `POINT` registrations. |
| `districtId` | number | Numeric identifier of the district. **`ADMINISTRATIVE`**: the district ID supplied at registration. **`POINT`**: the district ID of the district whose forecast covers the registered coordinate. |
| `district` | string | Human-readable district name. Populated for `ADMINISTRATIVE` registrations; `null` for `POINT` registrations. |
| `distance` | number | Meters between the registered monitoring point and the district centroid used for forecast evaluation. For `ADMINISTRATIVE` registrations this value is effectively zero; for `POINT` registrations it reflects how far the registered coordinate is from the nearest district centroid. |
| `violations` | array | One entry per metric that breached the configured threshold; a single alarm can bundle multiple metrics simultaneously. |
#### `Metric` catalog — alarm-relevant values
| Value | Unit | Meaning |
| ----------------- | ---- | -------------------------------------------------------------------------- |
| `PRECIPITATION` | mm | Total precipitation (rain + mixed) accumulated over the forecast interval. |
| `SNOWFALL` | cm | Snowfall depth accumulated over the forecast interval. |
| `WIND_GUSTS_MAX` | km/h | Daily maximum wind gust speed. |
| `TEMPERATURE_MIN` | °C | Daily minimum air temperature; triggers cold-snap alarms. |
| `TEMPERATURE_MAX` | °C | Daily maximum air temperature; triggers heat-wave alarms. |
#### `MetricForecasts` object
| Field | Type | Description |
| ------------------------ | ------ | ------------------------------------------------------------------------------------------------- |
| `violations[].metric` | enum | Metric identifier that exceeded the configured threshold (see catalog above). |
| `violations[].unit` | string | SI unit string for the metric values in this group (e.g. `mm`, `cm`, `km/h`, `°C`). |
| `violations[].forecasts` | array | Ordered list of forecast time slots during which the metric is predicted to breach the threshold. |
#### `Forecast` object
| Field | Type | Description |
| ------------------- | ------ | ---------------------------------------------------------------------------- |
| `forecasts[].time` | string | ISO-8601 timestamp (UTC) of the forecast time slot. |
| `forecasts[].value` | number | Forecast value for the metric in the units specified by `violations[].unit`. |
Use `registrationId` or `recipientId` to look up which of your assets or customers this alarm concerns — pair it with `city` / `district` for a quick human-readable summary.
Iterate over `violations` and map each `metric` to your internal risk policies. A single alarm can bundle multiple metrics (e.g. simultaneous heavy rain and strong gusts), so evaluate each entry independently.
Use `forecasts[].time` to schedule time-boxed actions — for example, send a heads-up notification at T-3h before the first threshold breach, and escalate if `value` keeps climbing across consecutive slots.