# Poltava region power outage schedule (POE), JSON

URL: https://api.poe.kurs.win/latest.json

This is the planned outage schedule (ГПВ) of Poltavaoblenergo (POE, https://www.poe.pl.ua/)
for today and tomorrow, for all 12 sub-queues (1.1 ... 6.2). It is the same data that the Telegram
channel https://t.me/ravlyk_pl_gpv shows.

POE has no official API. A bot reads the POE site every 2 minutes and writes this file.
The file is free to use. There is no guarantee: if the data matters, check the POE site.

## How to use

- Read `latest.json` not more often than once a minute. It is a static file, `ETag` and
  `Last-Modified` work.
- All times are Kyiv time (`Europe/Kyiv`). Timestamps are ISO 8601 with the offset.
- To find the queue for an address, use the POE page:
  https://www.poe.pl.ua/disconnection/poshuk-vidkliuchennia-za-osobovym-rakhunkom/

## Fields

```json
{
 "updated_at": "2026-10-10T13:08:01+03:00",
 "schema": 1,
 "checked_at": "2026-10-10T13:20:00+03:00",
 "docs": "https://api.poe.kurs.win/README.md",
 "source": "https://www.poe.pl.ua/",
 "timezone": "Europe/Kyiv",
 "slot_minutes": 30,
 "legend": {"G": "light", "R": "off", "Y": "maybe (switching, up to 30 min)"},
 "gav": {"active": false, "start": null},
 "days": {
  "2026-10-10": {
   "status": "schedule",
   "poe_updated_at": "2026-10-09T17:47:00+03:00",
   "poe_version": "9 жовтня 2026 17:47",
   "n": 1,
   "volumes": [{"from": "15:00", "to": "17:00", "queues": "1.5"}],
   "queues": {
    "1.1": {
     "slots": "GGGGGGGGGGGGGGGGGGGGGGGGGGGGGGRRRYGGGGGGGGRRRYGG",
     "intervals": [
      {"from": "15:00", "to": "16:30", "type": "off"},
      {"from": "16:30", "to": "17:00", "type": "maybe"}
     ]
    }
   }
  },
  "2026-10-11": {"status": "pending"}
 }
}
```

Top level:

| Field | Meaning |
|---|---|
| `updated_at` | When the data in this file changed last time (schedule or ГАВ). |
| `checked_at` | Last successful read of the POE site. If it is older than ~10 minutes, the bot or its connection is down and the data can be old. |
| `schema` | Format version. It changes only if the format breaks. New fields can appear at any time. |
| `gav` | Emergency outages (ГАВ, аварійні відключення). `active: true` means POE announced ГАВ, and the schedule below may not work now. `start` is the start time, `"HH:MM"`. |
| `days` | Two keys: today and tomorrow, `YYYY-MM-DD`. |

One day:

| Field | Meaning |
|---|---|
| `status` | `schedule`: there is a schedule, see `queues`. `none`: POE says there will be no outages this day ("не прогнозується"). `pending`: POE has not published this day yet (usual for tomorrow until the evening). |
| `poe_updated_at` | When POE published this version of the schedule (the stamp on the POE site). |
| `poe_version` | The same stamp as POE writes it, in Ukrainian. |
| `n` | Version number of this day: 1 = first schedule, then +1 for every change. POE often changes the schedule several times a day, for today and for tomorrow. |
| `volumes` | Outage volume ("обсяг черг") by time ranges, as POE writes it. Larger number = more hours without light. `"23:59"` means end of the day. |
| `queues` | Only when `status` is `schedule`. Keys `1.1` ... `6.2`. |

One queue, two forms of the same data:

- `slots`: 48 letters, one per half hour from 00:00. Letter 0 is 00:00-00:30, letter 47 is 23:30-24:00.
  `G` = light, `R` = no light, `Y` = switching: light can come back or go off within these 30 minutes.
- `intervals`: only `R` and `Y` parts. `type` is `off` (R) or `maybe` (Y). `to` can be `"24:00"`.

Usually `R` is followed by one `Y` slot: light comes back in the first minutes of it.
If you show "hours without light", count only `off`.

## Changes

- schema 1: first version.