API GUS w pracy analityka: praktyczne zastosowania

API GUS w pracy analityka: po co i kiedy warto je wykorzystać

Portal API GUS pod adresem api.stat.gov.pl udostępnia produkty statystyki publicznej jako interfejsy programistyczne. W komunikacie z 5 grudnia 2018 r. Urząd Statystyczny w Olsztynie poinformował, że witryna prowadzi do produktów statystyki publicznej i umożliwia automatyczne pobieranie danych z zasobów TERYT, REGON i BDL.

Samo API opisano tam jako mechanizm automatyzujący komunikację między systemami i pozwalający budować nowe rozwiązania programowe na bazie tych danych. Dla analityka oznacza to jedno: dane trafiają wprost do skryptu, bazy lub narzędzia BI, bez ręcznego kopiowania do arkusza.

Zakres portalu jest dziś szerszy niż w momencie startu. Obok API REGON, API TERYT i API BDL działają: API SDP (Składnica Danych Publikacyjnych), API DBW (Dziedzinowe Bazy Wiedzy), API SMUP (System Monitorowania Usług Publicznych), API STRATEG, API SDG oraz API TranStat. Każde odpowiada na inny typ pytania analitycznego.

REGON i TERYT to dane identyfikacyjne i rejestrowe. BDL i DBW — statystyczne. SDP obejmuje pełny zakres informacyjny statystyki publicznej. SMUP, STRATEG, SDG i TranStat to źródła wyspecjalizowane pod konkretny obszar monitoringu.

Korzystanie z API BDL i pozostałych produktów jest bezpłatne, a zasoby udostępniane są w dwóch wersjach językowych: polskiej i angielskiej. Wymogiem technicznym jest podstawowa znajomość formatów XML oraz JSON.

Liczba wywołań danych z konkretnego adresu IP podlega limitom ilościowym; kto potrzebuje większych, może się zarejestrować i uzyskać osobisty klucz API. API GUS ma sens tam, gdzie te same dane trzeba pobierać cyklicznie albo wpiąć je w powtarzalny proces — przy jednorazowym, małym zapytaniu wygodniejszy bywa interfejs webowy.

REGON i TERYT: identyfikacja podmiotów i terytorium w codziennej analizie

API REGON to usługa sieciowa BIR1 (Baza Internetowa REGON 1), udostępniająca dane z rejestru REGON — bieżąco aktualizowanego zbioru informacji o podmiotach gospodarki narodowej, prowadzonego w systemie informatycznym jako centralna baza danych. Interfejs pozwala przeszukiwać zasoby rejestru według trzech kryteriów: identyfikatora REGON, identyfikatora NIP oraz identyfikatora KRS. Wyniki można pobierać i wyświetlać bezpośrednio w systemach teleinformatycznych odbiorcy.

Usługa i dane są udostępniane bezpłatnie. Zgodnie z art. 44 ustawy o statystyce publicznej mogą z niej korzystać uprawnione organy administracji rządowej i jednostek samorządu terytorialnego oraz inne instytucje rządowe. Usługa jest dostępna również dla podmiotów komercyjnych. Powstała w ramach projektu System Informacyjny Statystyki Publicznej 2 (SISP-2).

W praktyce REGON służy przede wszystkim do wzbogacania własnych baz. Mając listę kontrahentów z numerami NIP, można odpytać usługę po identyfikatorze NIP i uzupełnić rekordy o dane rejestrowe; w drugą stronę — po numerze REGON lub KRS — potwierdzić tożsamość podmiotu i jego powiązania identyfikacyjne. Dostęp nie jest jednak natychmiastowy.

Aby uzyskać klucz do środowiska produkcyjnego, podmiot komercyjny (lub niekomercyjny wnioskujący o dane ogólnodostępne, z wyłączeniem danych niejawnych) wysyła na adres [email protected] wiadomość z pełną nazwą podmiotu, jego numerem REGON, imieniem i nazwiskiem oraz adresem e-mail i telefonem osoby do kontaktu. W wiadomości podaje też adresy IP, z których będą komunikowały się systemy, oraz przybliżoną liczbę użytkowników końcowych korzystających jednocześnie z usługi.

Podmioty administracji publicznej wnioskujące o dostęp w zakresie poszerzonym o niektóre dane niejawne, udostępniane wyłącznie organom administracji publicznej, składają wniosek zawierający m.in. dane adresowe instytucji i opis sposobu wykorzystania. GUS zapewnia wsparcie techniczne zarówno na etapie integracji, jak i dalszej eksploatacji usługi.

API TERYT operuje na rejestrze TERYT, który zawiera bieżące oraz archiwalne informacje o podziale terytorialnym kraju: jednostki terytorialne (województwa, powiaty, gminy), miejscowości i ulice. Skala zbioru jest duża — dane identyfikacyjne o ponad 100 tys. miejscowości i ponad 250 tys. ulic — co czyni go naturalnym narzędziem do normalizacji adresów i przypisywania rekordów do jednostek terytorialnych.

Najwięcej dają REGON i TERYT w połączeniu i przy pracy na danych historycznych. Rekordy podmiotów mapuje się na kody jednostek terytorialnych. Powstaje spójny klucz łączący dane rejestrowe ze statystyką lokalną. Pozwala budować zestawienia przestrzenne — np. liczbę i strukturę podmiotów według gminy czy powiatu. TERYT udostępnia też informacje archiwalne. W analizie długich okresów nie trzeba więc opierać się wyłącznie na aktualnym podziale administracyjnym.

BDL: lokalne i regionalne wskaźniki bez ręcznego przeszukiwania Banku Danych Lokalnych

Bank Danych Lokalnych to — jak opisuje go GUS — największa w Polsce baza danych o gospodarce, społeczeństwie i środowisku, oferująca tysiące cech statystycznych pogrupowanych tematycznie. Pierwsze dane pochodzą z 1995 roku, a zasoby statystyk rocznych i krótkookresowych są na bieżąco uzupełniane i aktualizowane.

Dane i wskaźniki opisują miejscowości statystyczne, gminy, powiaty, województwa i Polskę, a także jednostki zgodne z nomenklaturą NUTS: podregiony, regiony i makroregiony. Zakres danych udostępnianych przez API i przez aplikację internetową BDL jest taki sam — różni się jedynie organizacja i prezentacja informacji, co wynika z przyczyn technologicznych i ergonomicznych.

Dane udostępniane są poprzez REST-owe API w formacie XML oraz JSON, a aplikacja API pozwala przeglądać i pobierać do dalszego przetwarzania pełny zakres danych znajdujących się w Banku. Podstawowy zasób to dane liczbowe zapisane jako trójka: liczba rzeczywista, identyfikator atrybutu i identyfikator roku — dla konkretnej zmiennej albo dla jednej jednostki.

Do tego dochodzą opisy ułatwiające interpretację. Agregaty to poziomy agregowania, np. gminy miejskie lub miejsko-wiejskie. Atrybuty opisują specyficzne sytuacje w danych, np. „wartość mniejsza niż przyjęty format prezentacji”. Jednostki miary przypisane są do zmiennych, np. „tysiąc litrów”. Poziom obowiązywania danych: 0 oznacza poziom Polski, 1 — makroregionów, 2 — województw, 3 — regionów, 4 — podregionów, 5 — powiatów, a 6 — gmin.

Typowy scenariusz analityczny to benchmarking gmin lub powiatów: pobranie tej samej zmiennej dla wielu jednostek w kilku latach i zestawienie wyników w jednej tabeli, zamiast ręcznego przeszukiwania serwisu. Przykładowe żądanie podane w dokumentacji ma postać GET bdl.stat.gov.pl, a klucz API przekazuje się w nagłówku HTTP o nazwie X-ClientId. Pobrane szeregi można wykorzystać w dashboardzie regionalnym albo jako warstwę kontekstową do własnych danych operacyjnych.

SDP: pełny zakres danych i metadanych, gdy liczy się kompletność przekroju

Składnica Danych Publikacyjnych daje dostęp do pełnego zakresu informacyjnego statystyki publicznej: danych oraz metadanych w spójnym standardzie struktur danych. To odróżnia ją od źródeł tematycznych — jeśli celem jest jednorodny opis danych i ich metadanych, a nie pojedynczy wskaźnik, SDP jest właściwym punktem wyjścia.

Dane w API SDP zorganizowane są w dwóch układach: według zmiennych publikacyjnych i według wskaźników. Podział przekłada się na sposób pracy.

Sekcja zmiennych publikacyjnych służy do pobierania szerokiego zakresu informacji w pełnych przekrojach i różnych typach informacji. Sekcja wskaźników daje szybką informację o podstawowych danych na poziomach ogółem.

Analityk dokumentujący metodykę powinien sięgać właśnie tutaj — metadane w spójnym standardzie pozwalają opisać w raporcie, co dokładnie oznacza dana zmienna i w jakim przekroju została pobrana.

Dostęp wymaga uwzględnienia limitów i klucza. Anonimowy użytkownik może wykonać do 5 żądań na sekundę, 100 żądań na 15 minut, 1000 żądań na 12 godzin i 10 000 żądań na 7 dni. Zarejestrowany użytkownik ma limity odpowiednio 10 żądań na sekundę, 500 na 15 minut, 5000 na 12 godzin i 50 000 na 7 dni.

Klucz API uzyskuje się po zarejestrowaniu lub zalogowaniu na stronie systemu, a następnie wprowadza na stronie API SDP i zatwierdza przyciskiem „Autoryzuj”. Podczas rejestracji trzeba podać poprawny adres e-mail, ponieważ na ten adres wysyłany jest klucz klienta API — przy błędnym adresie korzystanie z wygenerowanego klucza nie będzie możliwe. Zgłoszenia dotyczące działania interfejsu przyjmowane są pod adresem [email protected].

DBW, SMUP, STRATEG i SDG: wyspecjalizowane źródła do monitoringu i ewaluacji

Dziedzinowe Bazy Wiedzy (DBW) to platforma danych statystycznych umożliwiająca dostęp do bogatego zestawu na bieżąco aktualizowanych informacji z różnych obszarów życia społeczno-gospodarczego i środowiska. Dane prezentowane są w długich szeregach czasowych oraz w maksymalnie pełnych przekrojach klasyfikacyjnych i nomenklaturowych.

Samo API DBW ma zapewniać powszechny, otwarty i wygodny dostęp do danych i metadanych ze zmodernizowanych i uzupełnionych zakresowo baz. To źródło wybiera się wtedy, gdy kluczowa jest ciągłość szeregu i szczegółowość przekroju, a nie pojedynczy, bieżący odczyt.

System Monitorowania Usług Publicznych dostarcza informacji niezbędnych do kompleksowej oceny usług świadczonych na poziomie lokalnym. Zawiera gotowe zestawy wskaźników dotyczących usług publicznych w gminach i powiatach. Nie trzeba konstruować wskaźników z danych surowych — wystarczy pobrać gotowy zestaw dla wybranej jednostki.

System STRATEG wspiera proces monitorowania rozwoju oraz ocenę efektów działań podejmowanych w ramach polityki spójności. Prezentuje wskaźniki służące do pomiaru celów zapisanych w dokumentach strategicznych i programowych Polski oraz Unii Europejskiej.

Platforma SDG służy do monitorowania celów zrównoważonego rozwoju wyznaczonych przez Agendę 2030. Zawiera dane dla Polski dostępne spośród wskaźników międzynarodowych ONZ oraz umożliwiające pomiar krajowych priorytetów zrównoważonego rozwoju.

Dobór źródła wynika wprost z pytania analitycznego. Wieloletni, nieprzerwany szereg i pełny przekrój klasyfikacyjny — sięgasz do DBW. Ocena jakości usług na poziomie gminy lub powiatu — właściwym źródłem jest SMUP z gotowymi zestawami wskaźników. Efekty polityki spójności i realizacja celów zapisanych w dokumentach strategicznych — STRATEG. Raportowanie celów zrównoważonego rozwoju w układzie zgodnym z Agendą 2030 — SDG.

TranStat: eksperymentalne dane transportowe w analizach mobilności i emisji

TranStat opisany jest jako inteligentny system produkcji statystyk transportu drogowego i morskiego z wykorzystaniem wielkich wolumenów danych, służący kształtowaniu polityki transportowej kraju. Dane dostępne przez API obejmują eksperymentalne statystyki natężenia ruchu, wolumenu pracy przewozowej oraz wielkości emisji zanieczyszczeń generowanych przez środki transportu drogowego i morskiego.

Status danych eksperymentalnych to informacja użytkowa, a nie formalność: takie statystyki bywają oparte na nowych źródłach i mogą podlegać zmianom metodyki. Dlatego przy ich wykorzystaniu warto w raporcie wskazać źródło i wyraźnie oznaczyć charakter danych.

Zastosowania układają się w trzy grupy: analizy transportowe i ruchowe, analizy środowiskowe oparte na wielkości emisji oraz wsparcie polityki mobilności — ocena natężenia ruchu i pracy przewozowej w kontekście planowanych działań.

Limity, klucze API i formaty danych: co zaplanować w pipeline analitycznym

Formaty XML i JSON, limity liczby żądań oraz sposób przekazywania klucza API omówiono przy poszczególnych usługach. Tutaj skupmy się na tym, co z nich wynika dla projektu pipeline'u. Pobieranie danych programuje się jak zwykłe żądania HTTP, a odpowiedź parsuje się do ramki danych lub zapisuje w bazie. Już na etapie projektowania trzeba zaplanować rozłożenie żądań w czasie, aby nie przekroczyć progów obowiązujących dla danego API.

W praktyce to kilka decyzji technicznych. Rozłóż żądania w czasie tak, aby nie przekroczyć progu na sekundę ani na 15 minut. Grupuj pobrania tak, by jeden zestaw zmiennych dla wielu jednostek nie generował tysięcy osobnych wywołań. Zapisuj surowe odpowiedzi lokalnie, aby ponowne przeanalizowanie danych nie wymagało kolejnych żądań. Korzystaj z klucza API i trybu zarejestrowanego wszędzie tam, gdzie skala pobrania przekracza limity anonimowe.

Limity żądań API GUS – porównanie anonimowego i zarejestrowanego użytkownika

Przykładowe scenariusze analityczne łączące kilka API GUS

Analiza lokalnego rynku. Punktem wyjścia jest własna lista podmiotów z numerami NIP, KRS lub REGON. Krok pierwszy: odpytanie API REGON po tych identyfikatorach i uzupełnienie rekordów danymi rejestrowymi. Krok drugi: pobranie z API TERYT identyfikatorów jednostek terytorialnych — województw, powiatów i gmin — oraz danych o miejscowościach i ulicach.

To pozwala znormalizować adresy i przypisać każdy podmiot do właściwego terytorium. Krok trzeci: sięgnięcie do API BDL po wskaźniki dla tych samych gmin lub powiatów, z zachowaniem zgodności poziomu obowiązywania danych (poziom 5 dla powiatów, 6 dla gmin). Wynik to jedna tabela łącząca charakterystykę podmiotów, ich położenie i kontekst statystyczny jednostki — podstawa do rankingu gmin czy analizy koncentracji branż.

Długie szeregi czasowe. Po API SDP sięgasz, gdy potrzebujesz szerokiego przekroju zmiennych publikacyjnych; po API DBW — gdy liczy się ciągłość i szczegółowość przekroju. Oba źródła można łączyć w jednym zestawieniu, uzupełniają się wzajemnie. Przy pobieraniu warto zapisywać surowe odpowiedzi i identyfikatory zmiennych, aby móc odtworzyć układ tabeli po aktualizacji danych.

Monitoring usług publicznych. Połączenie API SMUP i API STRATEG obsługuje dwa poziomy tego samego pytania: lokalny i programowy. Zestawienie obu warstw pokazuje, jak zmiany w lokalnych usługach przekładają się na realizację celów polityki spójności; przy raportowaniu celów Agendy 2030 tę samą konstrukcję uzupełnia się o wskaźniki z platformy SDG.

Analizy transportowe i środowiskowe. Podstawą są dane z API TranStat. Jeśli analiza ma być odniesiona do konkretnych jednostek terytorialnych — do porównania regionów lub gmin — kody i nazwy tych jednostek pobiera się z API TERYT i używa jako klucza łączącego. Ze względu na eksperymentalny charakter statystyk transportowych w raporcie trzeba wprost wskazać źródło danych i ich status, a wnioski formułować ostrożniej niż przy danych pochodzących z BDL czy DBW.

Krok po kroku: integracja API GUS w analizie lokalnej