Liczba z adresem

Bank Danych Lokalnych nie oddaje użytkownikowi samej liczby. Oddaje również informację, do jakiej zmiennej liczba należy, jakiej jednostki terytorialnej dotyczy, w czym została wyrażona i za jaki rok ją zapisano. Do wartości dołącza atrybut, czyli oznaczenie sytuacji szczególnej. To dlatego odczyt danych nie kończy się na znalezieniu kolumny, którą można posortować. Dokumentacja GUS opisuje cały zestaw zasobów, z których dopiero powstaje nadająca się do odczytania tabela. Nazwa województwa i liczba mieszkańców są widoczną częścią tego zestawu.^[1][3][4]

W przypadku ludności punkt wejścia stanowi temat P2137: ludność według grup wieku i płci. Jego opis wskazuje podział administracyjny na dzień 31 grudnia. Zmienna 72305 należy do tego tematu i ma w obu wymiarach oznaczenie „ogółem”. Jednostką miary jest osoba. Taki zapis pozwala ustalić, że chodzi o ludność ogółem, bez wydzielania wskazanej grupy wieku ani płci. Nie trzeba odgadywać tego na podstawie wielkości liczby: odpowiednie informacje znajdują się w metadanych.^[2][3]

Zapytanie o tę zmienną dla województw, za rok 2025, zwraca 16 rekordów. Każdy rekord ma identyfikator, nazwę i listę wartości. W tej liście zapisano rok, wartość oraz identyfikator atrybutu. W odpowiedzi występują województwa; nie ma osobnego wiersza zatytułowanego Polska. Odpowiedź nie zawiera również przyczyn różnic między województwami. Jest zestawem wartości określonej zmiennej dla określonego poziomu terytorialnego. Taką właśnie tabelę, wraz z adresem źródła, można odczytać i porównywać.^[4]

Temat i zmienna

Dokumentacja przedstawia tematy jako hierarchicznie powiązane grupy zmiennych. Wyszukiwanie może zaczynać się od ogólnego zakresu, a następnie przechodzić do jego części. Zasób tematów informuje, czy wybrany temat ma zmienne: służy do tego pole hasVariables. Sam tytuł grupy nie jest jeszcze wybraną miarą. W temacie ludności według wieku i płci trzeba dodatkowo wskazać zmienną odpowiadającą interesującemu połączeniu tych wymiarów. Właśnie na tym etapie ogólne pytanie o ludność zmienia się w konkretne zapytanie do bazy.^[1]

W metadanych zmiennej 72305 widoczne są nazwy wymiarów zapisane jako n1 oraz n2. Obie mają wartość „ogółem”. Metadane tematu podają, że jego wymiary to wiek i płeć. Odczytanie tych zasobów razem daje więcej niż sam skrótowy opis zmiennej. Pozwala przyporządkować jej wartości do tematu i jego wymiarów. Identyfikator tematu w rekordzie zmiennej łączy te informacje bez potrzeby dopasowywania nazw na podstawie podobieństwa słów.^[2][3]

GUS określa zmienne jako cechy wielowymiarowe, opisujące zjawisko z obowiązywaniem w konkretnych latach i na określonym poziomie jednostek. W przykładzie z dokumentacji zmienna może łączyć pracujących, grupę wieku oraz płeć. Z tego samego powodu w zbiorze ludności występuje wiele różnych przekrojów. Rekord dotyczący ogółu nie jest automatycznie rekordem dotyczącym wybranej części populacji. Informacja o wymiarach należy do opisu zmiennej, a nie do komentarza dopisywanego dopiero po utworzeniu rankingu.^[1][2]

Lista lat przy zmiennej 72305 zaczyna się od 1995 i kończy na 2025. W metadanych tematu również występują te lata. To jawny zakres czasowy wskazany przez zasoby użyte w tym odczycie. Rok zapisany przy wartości jest osobnym polem, dzięki czemu po pobraniu danych nadal wiadomo, którego okresu dotyczy dana pozycja. Sama dostępność starszych lat w metadanych nie zastępuje odczytania wartości dla wybranego roku i jednostki.^[2][3]

Jednostka miary i terytorium

Jednostki miary stanowią w API odrębny zasób słownikowy. Są związane ze zmiennymi: dokumentacja podaje między innymi przykład tysięcy litrów. W rozpatrywanym rekordzie ludności nazwa jednostki brzmi „osoba”, a jej identyfikator to 26. Zapis w jednostkach miary pozwala więc odczytać wielkość zgodnie z opisem zmiennej. Liczba ludności w tej odpowiedzi nie została przedstawiona jako udział procentowy ani jako gęstość zaludnienia. Opis jednostki wskazuje bezwzględną liczbę osób.^[1][3][4]

Jednostka miary i jednostka terytorialna pełnią różne role. Pierwsza mówi, w czym wyrażona została wartość. Druga wskazuje obszar, któremu tę wartość przypisano. W odpowiedzi dotyczącej ludności małopolskie występuje pod identyfikatorem 011200000000. Nazwa i identyfikator są elementami tego samego rekordu. Lista jednostek terytorialnych w API ma strukturę hierarchiczną, a dokumentacja pokazuje możliwość wyszukiwania jednostek na wybranym poziomie i pod wskazaną jednostką nadrzędną.^[1][4]

Dokumentacja rozróżnia poziom Polski, makroregionów, województw, regionów, podregionów, powiatów, gmin oraz miejscowości statystycznych. Województwa mają poziom 2, gminy poziom 6. W metadanych rozpatrywanej zmiennej widnieje poziom 6, natomiast użyte zapytanie o dane wskazuje unit-level=2 i rzeczywiście zwraca województwa. Są to informacje z różnych miejsc odpowiedzi: opis zmiennej oraz wybór poziomu pobieranych wyników. Odczyt metadanych warto więc zestawić z samym wynikiem zapytania.^[1][3][4]

GUS podaje, że dane BDL opisują także jednostki zgodne z nomenklaturą NUTS. Wśród zasobów znajdują się agregaty, na przykład gminy miejskie i gminy miejsko-wiejskie. Nie każda lista obszarów jest zatem listą województw. W dokumentacji poziomy, agregaty i jednostki stanowią rozróżnione zasoby. Przy pobieraniu danych można wskazać poziom oraz zawęzić jednostki przez jednostkę nadrzędną. Taki wybór określa zakres tabeli jeszcze przed odczytaniem poszczególnych wartości.^[1]

Słownik atrybutów

Opis zasobu Dane mówi o trójce złożonej z liczby rzeczywistej, identyfikatora atrybutu i identyfikatora roku. Atrybuty opisują szczególne sytuacje powiązane z wartościami liczbowymi. Dokumentacja wymienia wartość mniejszą od przyjętego formatu prezentacji, a słownik API pokazuje również inne przypadki. Zapis liczbowy i jego oznaczenie trzeba więc odczytać razem. Samo pole val nie zawiera pełnej informacji, którą API przekazuje o danej obserwacji.^[1][5]

W pobranej tabeli ludności każdy rekord ma attrId równy 1. Słownik opisuje ten identyfikator nazwą „wartość”, pozostawiając opis szczególny pusty. W innych rekordach słownika znajdują się oznaczenia szacunków wstępnych, zmian metodologicznych, możliwej niekompletności agregatu oraz danych o niskiej precyzji. Tych opisów nie trzeba dopisywać z pamięci ani zgadywać na podstawie symbolu. Są udostępnione w źródle jako osobne pola atrybutów.^[4][5]

Szczególnie ważna jest różnica pomiędzy wartością zerową a brakiem informacji. Słownik zawiera oznaczenie z nazwą „0”, którego opis mówi o braku informacji, konieczności zachowania tajemnicy statystycznej albo o niemożliwym czy niecelowym wypełnieniu pozycji. Inne oznaczenie opisuje daną jeszcze niedostępną, która będzie dostępna później. Nazwa lub znak użyty do prezentacji nie wystarcza zatem do utożsamienia każdej takiej pozycji z pomiarem zjawiska o zerowej wartości.^[5]

W tym samym słowniku istnieje również opis znaczącej wartości zerowej wynikającej z bilansu niezerowych danych wejściowych. GUS jako przykład podaje przyrost naturalny przy równej liczbie urodzeń i zgonów. To inna sytuacja niż brak informacji. Osobny atrybut dotyczy wartości mniejszej niż przyjęty format prezentacji. Rozróżnienia są zapisane bezpośrednio w opisach, choć na skróconej tabeli część pozycji mogłaby wyglądać podobnie. Słownik zachowuje informację, którą sam zapis liczbowy potrafi ukryć.^[5]

Występują także atrybuty łączące kilka okoliczności. Jeden opis obejmuje jednocześnie zmiany metodologiczne i możliwość niekompletności agregatu. Inny łączy zmianę metodologii z wartością mniejszą od formatu prezentacji. Jest też znak braku informacji wynikającego ze zmiany poziomu prezentacji, wykazu jednostek terytorialnych albo listy cech w okresie sprawozdawczym. Takie komunikaty dotyczą sposobu odczytywania danych, a nie wyłącznie ich wyglądu. Przy korzystaniu ze słownika należy zachować cały opis przypisany danemu oznaczeniu.^[5]

Rok danych, aktualizacja, odczyt

Odpowiedź na zapytanie o ludność województw zawiera przy każdej wartości rok 2025. To on wskazuje okres, którego dotyczy pozycja w tabeli. W metadanych tematu zapisano osobno pole lastUpdate, z datą 2026-05-06. API udostępnia więc zarówno lata występowania danych, jak i informację o aktualizacji zasobu. Tych pól nie należy zastępować jednym ogólnym podpisem pod wykresem, ponieważ w odpowiedzi pełnią różne funkcje i mogą zawierać różne daty.^[2][4]

Dokumentacja wyraźnie zaznacza, że dane i zmienne są zasobami o dużej zmienności. Bank jest poszerzany, a informacje podlegają weryfikacji oraz korektom. Inaczej opisano słowniki, wśród nich atrybuty i jednostki miary: mają małą zmienność oraz niewielką liczność. Oznacza to, że struktura API odróżnia zasoby, które zwykle zmieniają się rzadko, od tych, których zawartość jest stale aktualizowana. Nie wszystkie składniki tabeli mają więc jednakowy rytm zmian.^[1]

Metadane tematu ludności wskazują podział administracyjny na dzień 31 grudnia. Ta informacja opisuje podstawę terytorialną danych. Z kolei dokumentacja listy jednostek mówi, że jest ona aktualizowana zasadniczo przy wprowadzaniu danych dla nowego roku. Rok wartości, opis podziału administracyjnego i aktualizacja listy jednostek to powiązane, ale odrębne elementy. BDL udostępnia je w odpowiednich zasobach, zamiast umieszczać wszystkie informacje w samej nazwie województwa czy gminy.^[1][2]

Dwie drogi do tabeli

API pozwala pobierać dane dla jednej zmiennej i wielu jednostek terytorialnych albo dla jednej jednostki i wielu zmiennych. Dokumentacja przedstawia oba sposoby wraz z kolejnością działań i przykładowymi adresami. Pierwsza ścieżka zaczyna się od odnalezienia tematu i wybrania zmiennej. Druga zaczyna się od odnalezienia jednostki terytorialnej, a następnie doboru zmiennych. Różni się punkt wejścia, natomiast w obu przypadkach potrzebne są identyfikatory zasobów, których dane mają zostać pobrane.^[1]

W ścieżce według zmiennej można najpierw pobrać tematy głównego poziomu. Parametr parent-id pozwala przechodzić do tematów podrzędnych. Po dojściu do tematu zawierającego zmienne pobiera się ich listę, wskazując subject-id. Następnie wybiera się konkretną zmienną i pobiera przypisane do niej dane. Dokumentacja pokazuje zawężanie wyników do lat, poziomu jednostek oraz jednostki nadrzędnej. To sekwencja od zakresu merytorycznego do konkretnego zbioru wartości.^[1]

Przy ścieżce według jednostki można rozpocząć od listy jednostek terytorialnych i wskazać ich poziom. Dostępne jest też zawężenie przez jednostkę nadrzędną. Po wybraniu obszaru wyszukuje się tematy oraz zmienne, a następnie przekazuje ich identyfikatory w zapytaniu o dane jednostki. Przykłady GUS pokazują powtarzanie parametru var-id dla kolejnych zmiennych. Pokazują również możliwość zawężenia lat. Dzięki temu zapytanie nie musi obejmować całego zasobu dostępnego dla wybranej jednostki.^[1]

Dokumentacja zawiera osobne przykłady dla miejscowości statystycznych. Ich adresy wykorzystują część localities, zarówno przy pobieraniu według zmiennej, jak i według jednostki. To istotne rozróżnienie w sposobie adresowania zasobów. BDL obejmuje nie tylko podstawowy ciąg jednostek administracyjnych, ale również miejscowości statystyczne. Zakres tego, co można pobrać, jest opisany w instrukcji oraz zilustrowany konkretnymi wywołaniami, zamiast wynikać z domysłu o strukturze terytorialnej.^[1]

Co wynika z wojewódzkiej tabeli

W zwróconym zbiorze mazowieckie ma wartość 5505857, a opolskie 923536. Dla małopolskiego zapisano 3429342, dla wielkopolskiego 3471302, a dla śląskiego 4261792. Każda z tych pozycji dotyczy tej samej zmiennej ludności ogółem, tego samego roku oraz jednostki miary „osoba”. Odczyt tych wartości daje porównanie liczebności przypisanej województwom w danej tabeli. Nie zawiera jednak osobnych kolumn o urodzeniach, zgonach czy migracjach.^[4]

Odpowiedź API ma pole totalRecords o wartości 16. Zwrócona lista zawiera nazwy województw, a każde z nich ma własny identyfikator. Dane nie są opisem pojedynczego miasta ani listą gmin. Zakres wynika z parametru unit-level=2 oraz zawartości odpowiedzi. Wszystkie wartości w tej tabeli mają rok 2025 i attrId równy 1. Te wspólne elementy można sprawdzić bez dopisywania hipotez o demografii poszczególnych obszarów.^[1][4]

Właśnie tak wygląda granica informacji dostępnej w tym odczycie: wybrana zmienna, zakres terytorialny, rok i wartości wraz z atrybutami. API oferuje także inne tematy oraz zmienne, ale trzeba je osobno wybrać. Dokumentacja nie przedstawia jednego wywołania jako odpowiedzi na wszystkie pytania o region. Pokazuje zamiast tego możliwość zestawiania wielu zmiennych dla obszaru albo porównywania obszarów dla pojedynczej zmiennej. Tabela ludności jest jednym z takich odczytów.^[1]

Korzystanie z publicznego API

Zakres danych w API i aplikacji internetowej jest taki sam. GUS zastrzega, że organizacja oraz prezentacja informacji różnią się z powodów technologicznych i ergonomicznych. API udostępnia dane przez REST, w formatach XML oraz JSON. W instrukcji przykłady odsyłają także do wariantu JSONAPI i dokumentacji metod. Użytkownik może więc korzystać z interfejsu przeznaczonego do dalszego przetwarzania, a nie tylko z widoku danych przygotowanego w aplikacji internetowej.^[1]

Liczba zapytań jest limitowana. Dokumentacja rozróżnia użytkownika anonimowego i zarejestrowanego, który otrzymuje osobisty klucz API. Klucz jest przekazywany w nagłówku HTTP X-ClientId. Dla anonimowego użytkownika podano limit 5 żądań w ciągu sekundy, a dla zarejestrowanego 10. Istnieją również limity dla dłuższych przedziałów czasu. Rejestracja służy uzyskaniu większych limitów, nie oznacza innego zakresu merytorycznego danych opisanego w instrukcji API.^[1]

Duże zasoby można przeszukiwać i pobierać partiami według określonych kryteriów. Dokumentacja uzasadnia to licznością listy jednostek terytorialnych. Zasoby słownikowe opisuje natomiast jako niestronicowane, bez wyszukiwania według skomplikowanych kryteriów. Przykłady zapytań do danych pokazują parametry rozmiaru strony i numeru strony. To kolejna różnica między zasobami, którą należy uwzględnić podczas przygotowania programu pobierającego dane, zamiast zakładać identyczną obsługę każdej listy.^[1]

GUS udostępnia dane na licencji Creative Commons Uznanie autorstwa 4.0. Strona dokumentacji prowadzi do pełnego tekstu licencji oraz wskazuje kontakt w sprawach technicznych i merytorycznych. Przy zgłaszaniu problemu urząd prosi o możliwie szczegółowe informacje: rodzaj klienta API, język programu, pełny adres wywołania, nagłówki i treść odpowiedzi oraz opis problemu. Także tutaj punktem odniesienia jest konkretne zapytanie i jego wynik, a nie sam komunikat, że jakaś liczba wygląda inaczej.^[1]

Czytanie adresu zapytania

Adres odczytu użytego w tym tekście wskazuje ścieżkę data/by-variable/72305. Końcowy identyfikator określa zmienną, a część by-variable odpowiada opisanej w instrukcji metodzie pobierania według zmiennej. Dalsza część adresu zawiera parametry zapytania. W tym przypadku unit-level ma wartość 2, year ma wartość 2025, a format to json. Osobny parametr wskazuje rozmiar strony wyników. Każdy z tych elementów jest zapisany w adresie źródła pod tekstem. Można więc oddzielnie odczytać wybór zmiennej, poziomu, roku oraz formatu odpowiedzi.^[1][3][4][5]

Parametry roku mogą pojawiać się w przykładach wielokrotnie. Instrukcja pokazuje pobieranie danych za wybrane lata przez powtarzanie year, podobnie jak przy wyborze wielu zmiennych powtarzane jest var-id. W przykładach pobierania według zmiennej występuje również unit-parent-id. Pozwala on wskazać jednostkę nadrzędną dla zakresu terytorialnego zapytania. Są to sposoby zawężania zbioru wyników przedstawione w oficjalnej instrukcji, nie pola, które trzeba później dopisywać ręcznie do gotowej tabeli.^[1]

Sposób pobierania słowników GUS pozostawia do decyzji użytkownika: instrukcja nazywa uznaniowym czas oraz zasady pobierania atrybutów czy listy agregatów. Jednocześnie podaje ich małą zmienność. Inaczej opisuje zasoby danych i zmiennych, które podlegają ciągłemu poszerzaniu i korektom. Taki podział daje użytkownikowi informację o charakterze zasobów przed zaplanowaniem odczytów. Nie oznacza jednak, że słownik jest elementem zbędnym: opisy atrybutów nadal należą do informacji potrzebnej do zrozumienia wartości.^[1]

Szczególne oznaczenia w słowniku

Atrybut 3 ma nazwę „wartość”, symbol k i opis mówiący o możliwej niekompletności agregatu. Atrybut 9 ma symbol s i opis szacunków wstępnych. Atrybut 11 jest oznaczony symbolem M oraz opisem zmian metodologicznych. Atrybuty 20 i 21 mają ten sam opis: dane o niskiej precyzji. Widać zatem, że identyfikator jest odrębnym polem od nazwy i symbolu. Sama powtarzająca się nazwa „wartość” nie zawiera wszystkich uwag przypisanych do danej pozycji słownika.^[5]

Atrybut 97 opisuje dane łączne dla powiatu i miasta na prawach powiatu. W tym przypadku uwaga dotyczy zakresu terytorialnego prezentacji. Atrybut 15 opisuje brak informacji związany między innymi ze zmianą poziomu prezentacji albo wykazu jednostek terytorialnych. Są to różne sytuacje, choć obie odnoszą się do organizacji danych, a nie tylko do wielkości pomiaru. Słownik pozwala je rozróżnić przez pełny opis, zamiast sprowadzać wszystkie oznaczenia do wspólnego komunikatu o braku wartości.^[5]

Przy wartości zerowej słownik rozróżnia również wariant ze zmianami metodologicznymi. Atrybut 94 opisuje znaczącą wartość zerową wynikającą z bilansu niezerowych danych wejściowych, a atrybut 98 dodaje do tego zmiany metodologiczne. Przy obu podano przykład równowagi urodzeń i zgonów. To szczegółowe wyjaśnienie pokazuje, dlaczego atrybut nie jest jedynie etykietą błędu. Może doprecyzowywać poprawnie zapisaną wartość, wskazując jej sens albo dodatkową okoliczność dotyczącą sposobu wyznaczenia.^[5]

Od odczytu do porównania

Schemat API prowadzi od tematów i zmiennych do danych, a opis wartości prowadzi dalej do atrybutów, jednostek miary i lat. Jest to jedna struktura informacji udostępnionej przez GUS. Przy ludności jej elementy można zobaczyć w temacie P2137, zmiennej 72305, odpowiedzi dla województw oraz słowniku atrybutów. Każdy z tych zasobów wyjaśnia inny fragment tabeli. Żaden nie wymaga dopisywania fikcyjnych rozmówców ani opowieści o przyczynach zmian, których ta tabela nie przedstawia.^[1][2][3][5]

Porównanie zaczyna się więc od opisu danych. Nazwy i identyfikatory pozwalają wskazać obszar, jednostka miary określa sposób odczytania wielkości, rok wskazuje okres, a atrybut zachowuje zastrzeżenia dotyczące wartości. W pobranym zestawie ludności te informacje są dostępne wprost. Dopiero ich wspólny odczyt pozwala nazwać tabelę precyzyjnie: ludność ogółem województw, za wskazany rok, wyrażona w osobach. To opis zawartości źródła, z którego można rozpocząć dalsze pytania o dane.^[3][4][5]

Źródła

• https://api.stat.gov.pl/home/bdlapi - odczyt 2026-10-18
• https://bdl.stat.gov.pl/api/v1/subjects/P2137?format=json - odczyt 2026-10-18
• https://bdl.stat.gov.pl/api/v1/variables/72305?format=json - odczyt 2026-10-18
• https://bdl.stat.gov.pl/api/v1/data/by-variable/72305?unit-level=2&year=2025&format=json&page-size=100 - odczyt 2026-10-18
• https://bdl.stat.gov.pl/api/v1/attributes?format=json - odczyt 2026-10-18

Czy te liczby można porównać?