Zakres informacyjny

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.

---

Limity i klucz API

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

---

Struktura zasobów

W aplikacji API udostępniane są następujące zasoby BDL:

1. Agregaty - poziomy agregowania danych, dla których znajdują się dane, np. gminy miejskie lub gminy miejsko-wiejskie.
2. Atrybuty - opisy specyficznych sytuacji w danych, które powiązane są z każdą wartością liczbową, np. 'Wartość mniejsza niż przyjęty format prezentacji'.
3. Dane - dane liczbowe w postaci trójki [liczba rzeczywista, identyfikator atrybutu, identyfikator roku], w postaci zbioru danych dla konkretnej zmiennej lub zbioru danych dla jednej jednostki (więcej informacji poniżej).
4. Jednostki miary - jednostki miary występujące w danych, związane z konkretnymi zmiennymi, np. 'tysiąc litrów'.
5. Poziom obowiązywania - poziom obowiązywania danych według:
   • 0 - Poziom Polski
   • 1 - Poziom Makroregionów
   • 2 - Poziom Województw
   • 3 - Poziom Regionów
   • 4 - Poziom Podregionów
   • 5 - Poziom Powiatów
   • 6 - Poziom Gmin
   • 7 - Poziom miejscowości statystycznej
6. Tematy - hierarchicznie powiązane grupy zmiennych wg zakresu merytorycznego, np. 'Ludność', 'Ludność wg grup wieku i płci' (więcej informacji poniżej).
7. Jednostki - hierarchicznie powiązana lista jednostek terytorialnych (od Polski do gmin włącznie) i miejscowości statystycznych.
8. Zmienne - to wielowymiarowe cechy reprezentujące określone zjawisko, z określonym obowiązywaniem w latach i na konkretnym poziomie jednostek, np. liczba pracujących dla wieku '20-26' i płci 'mężczyźni'.
9. Lata - lata obowiązywania, dla których mogą występować dane, np. '2003', '2004'.

---

Zmienność oraz liczebność zasobów

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.

---

Pobieranie danych

Dane udostępniane są przez API na dwa alternatywne sposoby:

• dla jednej zmiennej i wielu jednostek terytorialnych
• dla jednej jednostki terytorialnej oraz wielu zmiennych

Dane dla jednej zmiennej i wielu jednostek terytorialnych

Proces pobierania danych dla jednej zmiennej i wielu jednostek terytorialnych w dużym uproszczeniu może wyglądać następująco:

1. Pobierz listę tematów głównego poziomu, np.

   /api/v1/subjects?format=xml
   /api/v1/subjects?lang=pl&format=json

2. Wybieraj temat i pobieraj listę poziomów podrzędnych aż dojdziesz do poziomu, w którym temat ma zmienne (hasVariables=true), np.

   /api/v1/subjects?parent-id=K15
   /api/v1/subjects?parent-id=G186

3. Pobierz listę zmiennych dla wybranego tematu i wybierz interesującą cię zmienną

   /api/v1/Variables?subject-id=P3183

4. Pobierz dane dla wybranej zmiennej, ewentualnie zawężając listę jednostek terytorialnych oraz lata do interesującego zakresu, np.

   /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

Dane dla jednej jednostki terytorialnej oraz wielu zmiennych

Proces pobierania danych dla jednej jednostki terytorialnej oraz wielu zmiennych w dużym uproszczeniu może wyglądać następująco:

1. Wybierz jednostkę terytorialną nawigując po liście jednostek terytorialnych, np.

   /api/v1/Units
   /api/v1/Units?level=2
   /api/v1/Units?parent-id=011200000000&level=5
   

2. Pobierz listę tematów głównego poziomu, np.

   /api/v1/subjects?format=xml
   /api/v1/subjects?lang=pl&format=json

3. Nawigując po liście tematów i zmiennych wybierz interesujące cię zmienne, np.

   /api/v1/subjects?parent-id=K15
   /api/v1/subjects?parent-id=G186
   /api/v1/Variables?subject-id=P3183

4. Pobierz dane dla wybranej jednostki i wybranych zmiennych zawężając ewentualnie zakres lat, np.

   /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.

---

Przykłady

Zapraszamy do zapoznania się z przykładami poprawnych wywołań API.

---

Dokumentacja

• Opis metod
• Swagger
• ReDoc

---

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:

• rodzaj klienta API (przeglądarka i jej rodzaj, własny program, narzędzie systemowe itp)
• język programowania (tylko w przypadku własnego programu)
• wywoływany pełny adres URL
• zwrócone przez serwer nagłówki oraz treść odpowiedzi
• tekstowy opis 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).

178 917 468 zapytań od 04.12.2018

4 975 zarejestrowanych użytkowników

---

Dzienne wykorzystanie usługi - ostatnie 7 dni