outage-data-ua

What the repository collects

outage-data-ua is a public repository and set of tools for automatically collecting, parsing, visualizing as HTML, and auto generating PNG images of planned and emergency electricity outage schedules in Ukraine. The README says the project gets data from the open web pages of suppliers and stores it in JSON as is in the data folder. From there the data is shown in a fixed HTML template and converted into PNG images that are saved under images per region. The purpose is to make outage schedules easy to read and share. The README states the data comes from open supplier pages, so the repository is a mirror and renderer rather than the original source. Storing the raw JSON means the exact supplier values are preserved. The HTML view gives a human readable schedule, and the PNG export gives a shareable image. The README frames the project as public infrastructure for a problem that affects daily life, and it keeps the processing pipeline simple. Fetch, store as JSON, render to HTML, export to PNG. The tools are written in JavaScript according to the project metadata. The README calls the project public infrastructure, which frames the repository as a shared utility for a daily problem rather than as a private script owned and run by one operator alone.

The JSON data format

The README describes the data format in detail. Each region is stored in a file named data per region dot json. A region object has a regionId such as kyiv, a regionAffiliation such as the city of Kyiv, a lastUpdated timestamp, a fact block, a preset block, and a lastUpdateStatus block. The preset block holds planned outages for the week for each group, stored as is without normalizing the structure. The fact block holds actual or emergency outages for today and tomorrow for each group, also stored as is. Both fact and preset contain an updateFact field and an update field giving the date and time the information is valid for, usually in dd.MM.yyyy HH:mm in the Europe or Kyiv time zone, which the parser does not reformat. A meta block is minimal, holding only schemaVersion and contentHash, where the hash covers the fact and preset content. The README says the current template for the structure lives in templates or json or data.json. On a parse error the parser updates only lastUpdateStatus, for example setting status to error and code 422, without erasing the previous fact and preset values. Storing values as is means the parser does not normalize supplier formats, so the raw JSON keeps the original structure that the source pages used for each region and each outage group.

Images and rendering

The README explains that generated PNG images are stored under the images folder, organized by region. The full path pattern is images per region, then a file such as gpv-x-x dot png. This means each region gets its own subdirectory and the generated graphics live there. The PNGs are produced from the same JSON that feeds the HTML view, so the image and the web view stay consistent. The README says the data is displayed in a fixed HTML template before conversion, which implies a stable layout rather than a per region design. Because the source JSON is kept as is, the rendering step can be rerun if the template changes. The repository therefore separates concerns. Collection writes JSON, rendering reads JSON and emits both HTML and PNG. The README documents the storage locations, data per region dot json for raw data and images per region for output, so a user knowing the region id can find both the source and the picture directly without extra tooling or a database to query. Keeping the source JSON separate from the rendered PNG lets the picture be regenerated if the template changes, without losing the original supplier data that sits in the data folder.

Editorial conclusion

outage-data-ua is written in JavaScript and stores each region's data as JSON in the data folder. The README documents the JSON structure and the PNG export path under images per region.