BANK DANYCH LOKALNYCH jest największą w Polsce bazą danych o gospodarce, społeczeństwie i środowisku.
BDL oferuje tysiące cech statystycznych pogrupowanych tematycznie. Pierwsze dane pochodzą z 1995 roku.
Aplikacja API pozwala przeglądać i pobierać do dalszego przetwarzania pełny zakres danych znajdujących się w Banku. Dane udostępniane są poprzez REST-owe API w formacie XML oraz JSON.
API do BDL zrealizowano w ramach partnerskiego projektu „Otwarte dane – dostęp, standard, edukacja”, którego Liderem jest Ministerstwo Cyfryzacji. Projekt jest współfinansowany ze środków Unii Europejskiej z Programu Operacyjnego Polska Cyfrowa.
Zakres danych udostępnianych w API i w aplikacji internetowej BDL jest taki sam, ale z przyczyn technologicznych i ergonomicznych sposób organizacji i prezentacji informacji jest nieznacznie inny. Ma to na celu zapewnienie łatwego startu nowym użytkownikom, którzy nie znają struktury BDL, a także odpowiedniej wydajności i wygody użytkowania tzw. stałym użytkownikom.
Ze względów bezpieczeństwa API na ilość żądań nałożone są limity ilościowe. Użytkownicy potrzebujący większych limitów mogą się zarejestrować i uzyskać generowany automatycznie osobisty klucz API. Klucz API należy podawać w żądaniu jako nagłówek HTTP o nazwie X-ClientId, np.
W zakresie żądań obowiązują następujące limity dla użytkowników:
Okres | Użytkownik anonimowy | Użytkownik zarejestrowany |
---|---|---|
1s | 5 | 10 |
15m | 100 | 500 |
12h | 1 000 | 5 000 |
7d | 10 000 | 50 000 |
W aplikacji API udostępniane są następujące zasoby BDL:
Zasoby Agregaty, Atrybuty, Jednostki miary oraz Lata są zasobami słownikowymi o bardzo małej zmienności i małej liczności, stąd mogą być potraktowane jako tzw. 'typowe słowniki', sporadycznie aktualizowane w określonych odstępach czasowych bądź na żądanie użytkownika. Zasoby te nie są stronicowane i nie ma możliwości ich wyszukiwania według skomplikowanych kryteriów.
Zasób Jednostki, oznaczający jednostki podziału terytorialnego, jest zasobem o dużej liczności i bardzo małej zmienności, aktualizowanym w zasadzie tylko przy wprowadzaniu w BDL danych dla nowego roku, a więc na początku roku. Ze względu na jego liczność problematyczne może być pobieranie go w całości, stąd mamy możliwość przeszukiwania i pobierania partiami wg własnych kryteriów, oczywiście w ograniczonym zakresie.
Zasoby Dane i Zmienne są zasobami o bardzo dużej zmienności, gdyż Bank ulega nieustannemu procesowi poszerzania zakresu danych oraz weryfikacji i korekt.
Dane udostępniane są przez API na dwa alternatywne sposoby:
Proces pobierania danych dla jednej zmiennej i wielu jednostek terytorialnych w dużym uproszczeniu może wyglądać następująco:
/api/v1/subjects?format=xml
/api/v1/subjects?lang=pl&format=json
/api/v1/subjects?parent-id=K15
/api/v1/subjects?parent-id=G186
/api/v1/data/by-variable/3643?format=xml&unit-level=2
/api/v1/data/by-variable/3643?format=xml&year=2009&year=2010&year=2011&unit-parent-id=010000000000&unit-level=2
/api/v1/data/by-variable/2137?unit-level=4&page-size=10&page=3
/api/v1/data/localities/by-variable/148190?unit-parent-id=011212001011
Proces pobierania danych dla jednej jednostki terytorialnej oraz wielu zmiennych w dużym uproszczeniu może wyglądać następująco:
/api/v1/Units
/api/v1/Units?level=2
/api/v1/Units?parent-id=011200000000&level=5
/api/v1/subjects?format=xml
/api/v1/subjects?lang=pl&format=json
/api/v1/subjects?parent-id=K15
/api/v1/subjects?parent-id=G186
/api/v1/Variables?subject-id=P3183
/api/v1/data/by-unit/023200000000?var-id=3643
/api/v1/data/by-unit/023200000000?var-id=3643&var-id=2137&var-id=148190
/api/v1/data/localities/by-unit/011212001011-0981682?var-id=148190
/api/v1/data/localities/by-unit/011212001011-0981682?var-id=148190&year=2009&year=2011
W obu podejściach kwestią uznaniową jest czas i zasady pobierania danych słownikowych, tzn. atrybutów, listy agregatów itd.
Zapraszamy do zapoznania się z przykładami poprawnych wywołań API.
Dane dla zmiennej z identyfikatorem Id=3643 za lata 2000,2010 | XML | JSON | JSONAPI |
Dane dla zmiennej z identyfikatorem Id=65809 za lata 2004-2006 | XML | JSON | JSONAPI |
Dane dla zmiennej z identyfikatorem Id=420, dla miejscowości z województwa Małopolskiego | XML | JSON | JSONAPI |
Dane dla jednostki terytorialnej z Id=012400000000, dla zmiennej z Id=3643, za lata 2004-2006 | XML | JSON | JSONAPI |
Dane dla miejscowości z Id=030210564011-0986283, dla zmiennej z Id=270672 | XML | JSON | JSONAPI |
Metadane | XML | JSON |
Dane dla zmiennej z identyfikatorem Id=3643 za lata 2000,2010 | XML | JSON | JSONAPI |
Dane dla zmiennej z identyfikatorem Id=65809 za lata 2004-2006 | XML | JSON | JSONAPI |
Dane dla zmiennej z identyfikatorem Id=420, dla miejscowości z województwa Małopolskiego | XML | JSON | JSONAPI |
Dane dla jednostki terytorialnej z Id=012400000000, dla zmiennej z Id=3643, za lata 2004-2006 | XML | JSON | JSONAPI |
Dane dla miejscowości z Id=030210564011-0986283, dla zmiennej z Id=270672 | XML | JSON | JSONAPI |
Metadane | XML | JSON |
Dane są możliwe do wykorzystywania w oparciu o licencję międzynarodową Creative Commons by 4.0 – Uznanie autorstwa https://creativecommons.org/licenses/by/4.0/legalcode.pl
W razie zauważenia nieprawidłowości w działaniu aplikacji BDL API czy wątpliwości na temat zakresu udostępnianych danych prosimy o kontakt mailowy w celu wyjaśnienia problemu.
Aby jak najsprawniej obsłużyć zgłoszenie prosimy o przekazywanie nam w miarę możliwości jak najbardziej szczegółowych informacji na temat zauważonego problemu:
Zgłoszenia natury technicznej prosimy kierować na adres bdl.kontakt@stat.gov.pl (podając w temacie: API-Pomoc).
Wszelkie inne zgłoszenia czy problemy natury nietechnicznej na adres bdl.kontakt@stat.gov.pl (podając w temacie: API-Informacje).
205 658 670 zapytań od 04.12.2018
6 396 zarejestrowanych użytkowników
Dzienne wykorzystanie usługi - ostatnie 7 dni
Główny Urząd Statystyczny
Aleja Niepodległości 208
00-925 Warszawa
Przejdź do Portalu GUS
Copyright © 2018-2024 Główny Urząd Statystyczny