Jak zbudowaliśmy pipeline danych dla polskiego rynku energii

Architektura systemu

Projekt składa się z czterech warstw, przez które przechodzi każdy rekord danych:

Każdy scraper dziedziczy po wspólnej klasie bazowej BaseScraper, która obsługuje retry z wykładniczym backoffem, rate limiting (2 sekundy między żądaniami), parsowanie cen z polskiego formatu tekstowego ("1 234,56 zł/MWh") i tworzenie ustandaryzowanych rekordów. Poszczególne moduły implementują tylko logikę specyficzną dla danego źródła.

Źródła danych

Siedem błędów, które znaleźliśmy w pierwszej wersji

Pierwsza wersja scrapera działała — ale dane, które produkowała, nadawały się do kosza. Dopiero analiza wyników przez analityka danych ujawniła szereg problemów, z których każdy mógłby dyskredytować wyniki kalkulatorów:

1. Ceny 10 000× za wysokie

GUS BDL API zwracał wartości energii w jednostkach PLN/MWh, ale metadane API opisywały je jako PLN/kWh. Wynik: rekord pokazywał 652 PLN/kWh zamiast 0,652 PLN/kWh. Naprawiliśmy to auto-korektą w normalizatorze — jeśli cena energii elektrycznej w PLN/kWh przekracza 10,0, wartość jest automatycznie dzielona przez 1000 i oznaczana flagą AUTO_KONWERSJA.

2. Mutable default dict — klasyczna pułapka Pythona

Definicja schematu na poziomie modułu zawierała {"dodatkowe": {}}. Wywołanie dict(schema) tworzyło płytką kopię — wszystkie rekordy współdzieliły ten sam obiekt dodatkowe. Efekt: metadane z ostatniego scrapowanego rekordu (ceny oleju opałowego) pojawiały się w polach wszystkich kategorii. Rozwiązanie: funkcja _make_fresh_record() tworząca nowy {} przy każdym wywołaniu.

3. Data pobrania jako data obowiązywania

Pole data_wazosc było ustawiane na bieżącą datę scrapowania. Wynik: dane z 2023 Q4 wyglądały jak aktualne dane z lutego 2026. Rozdzieliliśmy pola: data_wazosc pochodzi teraz z roku/kwartału ze źródła (lub jest null gdy nieznana), a scraped_at przechowuje timestamp pobrania.

4. Tylko mazowieckie

GUS BDL API paginuje wyniki, a oryginalna implementacja pobierała tylko pierwszą stronę. Wynik: 1 województwo zamiast 16. Naprawka: pętla while True iterująca po parametrze page aż do totalPages, z prawidłowymi 12-cyfrowymi kodami NUTS2.

5–7. Fałszywa deduplikacja, błędne mapowanie pól, brakująca walidacja

Trzy dodatkowe błędy: hash deduplicator nie uwzględniał regionu w kluczu (dwa województwa z identyczną ceną były scalane w jeden rekord), pole region GUS (singular) nie było mapowane na listę regiony (plural) używaną przez inne scrapers, oraz brak jakiegokolwiek wykrywania wartości odstających.

Statystyczna walidacja — po co IQR?

Po naprawieniu błędów strukturalnych dodaliśmy walidację statystyczną opartą na metodzie Tukey'a. Dla każdej kategorii danych i jednostki miary obliczamy kwartyle Q1 i Q3, rozstęp ćwiartkowy IQR = Q3 − Q1, i oznaczamy jako outlier każdy rekord poza przedziałem [Q1 − 1,5·IQR, Q3 + 1,5·IQR].

To nie usuwa podejrzanych rekordów — oznacza je flagą, żeby analityk (lub kalkulator) mógł je zignorować lub potraktować z uwagą. Statystyki IQR (mediana, Q1, Q3, granice) są zapisywane w polu dodatkowe.iqr_stats każdego rekordu, co ułatwia debugowanie.

System flag jakości danych

Snapshot ID — śledzenie sesji eksportu

Każde uruchomienie scrapera generuje nowy UUID4 (snapshot_id), który jest przypisywany do wszystkich rekordów wyprodukowanych w tej sesji. Dzięki temu można:

powiązać konkretny raport z konkretnym zestawem danych, wykryć czy dwa pliki JSON były wygenerowane w tym samym uruchomieniu, oraz odtworzyć historię zmian cen między kolejnymi snapshottami — bez potrzeby przechowywania dat w nazwach plików.

Od danych surowych do kalkulatora ROI

Zebrane dane zasilają bezpośrednio kalkulatory inwestycyjne na ecoaudyt.app. Konkretnie:

Kalkulator pompy ciepła vs ogrzewanie gazowe

Zamiast używać ogólnopolskiej średniej ceny energii, kalkulator automatycznie dobiera lokalną cenę dla województwa użytkownika na podstawie pola regiony i kodu OSD. Różnica między warmińsko-mazurskim (0,644 PLN/kWh) a mazowieckim (0,712 PLN/kWh) wynosi 10,5% — co przy 15-letniej inwestycji zmienia czas zwrotu nawet o 1–2 lata.

Analiza wrażliwości

Kalkulator używa aktualnych danych PSCMI1 do porównania kosztów ogrzewania węglowego z pompą ciepła. Gdy cena węgla wynosi 383 PLN/t (dane Q3 2024), a nadchodząca reforma EU ETS2 wprowadzi opłaty CO₂ dla gospodarstw domowych — automatycznie uwzględniamy to w analizie scenariuszowej.

Raport analityczny

Raz na tydzień system generuje pełny raport PDF/DOCX z trendami cen dla wszystkich 16 województw, aktualnym miksem energetycznym OZE i rekomendacjami dla audytorów. Raport jest dostępny na platformie dla użytkowników ecoaudyt.app.

Dlaczego udostępniamy to open source?

Moglibyśmy traktować scraper jako tajemnicę handlową. Postanowiliśmy inaczej — i to z kilku powodów.

Po pierwsze, bariera wejścia w tym projekcie nie leży w scraperze. GUS BDL, URE i TGE to publiczne API dostępne dla każdego. Każdy kompetentny deweloper mógłby zbudować podobne narzędzie w kilka tygodni. Nasza przewaga to to, co robimy z danymi dalej — modele ROI, ux audytów, skalowanie leadów.

Po drugie, otwartość buduje zaufanie. Jeśli pokazujemy skąd pochodzą dane, jak je walidujemy i jakie ograniczenia mają — audytorzy i ich klienci mogą ocenić jakość samodzielnie. To ważniejsze niż iluzja ekskluzywności.

Po trzecie, liczymy na to, że ktoś znajdzie błąd który przeoczyliśmy, albo doda obsługę źródła którego nie mamy. Open source to darmowy code review.

Co dalej?

Scraper v1.2 to solidna podstawa, ale mamy już listę ulepszeń na kolejne wersje. Priorytetem jest integracja z bazą danych (PostgreSQL) dla przechowywania historii cen — bo sam JSON/CSV nie jest dobrym formatem dla trendów długoterminowych. Planujemy też API REST jako warstwę pomiędzy scraperem a kalkulatorami, co pozwoli na zapytania w stylu: "daj mi aktualną cenę energii dla województwa śląskiego, taryfa G11".

Jeśli budujesz coś podobnego lub chcesz zintegrować nasze dane z własnym projektem — napisz do nas. Dane energetyczne powinny być dostępne dla każdego, kto chce podejmować lepsze decyzje o efektywności energetycznej.