• Portal Informacyjny
  • A
  • A
  • A
  • Portal Informacyjny
  • A
  • A
  • A

API BDL

  • POWRÓT
  • API REGON
  • API TERYT
  • API SDG
  • API STRATEG
  • API DBW
Informacje ogólne Rejestracja Instrukcja Kontakt Statystyki
Informacje ogólne

BANK DANYCH LOKALNYCH jest największą w Polsce bazą danych o gospodarce, społeczeństwie i środowisku.

BDL oferuje ponad 40 tys. cech statystycznych pogrupowanych tematycznie. Pierwsze dane pochodzą z 1995 roku.

  • 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.
  • Zasoby informacyjne (statystyki roczne i krótkookresowe) są na bieżąco uzupełniane oraz aktualizowane.

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.

Rejestracja
Instrukcja

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.

GET https://bdl.stat.gov.pl/api/v1/data/by-variable/3643?format=xml&year=2000&year=2010 HTTP/1.1
Host: hostname
X-ClientId: 1A6B2AB1-0DF0-4DAC-74A3-07D7C07FC3BE

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.

  • Agregaty
  • Atrybuty
  • Dane
  • Jednostki miary
  • Poziom obowiązywania
  • Jednostki terytorialne
  • Lata
  • Tematy
  • Zmienne
Lista wszystkich agregatów XML JSON JSONAPI
Agregat z identyfikatorem Id=3 XML JSON JSONAPI
Metadane XML JSON
Lista wszystkich atrybutów XML JSON JSONAPI
Atrybut z identyfikatorem Id=K3 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
Lista wszystkich jednostek miar XML JSON JSONAPI
Jednostka miary z identyfikatorem Id=3 XML JSON JSONAPI
Metadane XML JSON
Lista wszystkich poziomów obowiązywania XML JSON JSONAPI
Poziom obowiązywania z identyfikatorem Id=3 XML JSON JSONAPI
Metadane XML JSON
Lista wszystkich jednostek terytorialnych XML JSON JSONAPI
Lista wszystkich jednostek terytorialnych z własnym stronicowaniem XML JSON JSONAPI
Jednostka terytorialna z identyfikatorem Id=030200000000 XML JSON JSONAPI
Metadane XML JSON
Lista wszystkich lat obowiązywania XML JSON JSONAPI
Rok z identyfikatorem Id=2003 XML JSON JSONAPI
Metadane XML JSON
Lista wszystkich tematów najwyższego poziomu XML JSON JSONAPI
Temat z identyfikatorem Id=K3 XML JSON JSONAPI
Lista tematów drugiego poziomu dla tematu nadrzędnego z Id=K3 XML JSON JSONAPI
Wyszukiwanie tematów ze słowem 'samochody' w nazwie XML JSON JSONAPI
Metadane XML JSON
Lista wszystkich zmiennych XML JSON JSONAPI
Lista zmiennych dla tematu z Id=P2137, występujących w latach 2005,2006 XML JSON JSONAPI
Zmienna z identyfikatorem Id=1688 XML JSON JSONAPI
Wyszukiwanie zmiennych ze słowem 'samochody' w nazwach wymiarów XML JSON JSONAPI
Metadane XML JSON
Agregaty
Lista wszystkich agregatów XML JSON JSONAPI
Agregat z identyfikatorem Id=3 XML JSON JSONAPI
Metadane XML JSON
Atrybuty
Lista wszystkich atrybutów XML JSON JSONAPI
Atrybut z identyfikatorem Id=K3 XML JSON JSONAPI
Metadane XML JSON
Dane
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
Jednostki miary
Lista wszystkich jednostek miar XML JSON JSONAPI
Jednostka miary z identyfikatorem Id=3 XML JSON JSONAPI
Metadane XML JSON
Poziom obowiązywania
Lista wszystkich poziomów obowiązywania XML JSON JSONAPI
Poziom obowiązywania z identyfikatorem Id=3 XML JSON JSONAPI
Metadane XML JSON
Jednostki terytorialne
Lista wszystkich jednostek terytorialnych XML JSON JSONAPI
Lista wszystkich jednostek terytorialnych z własnym stronicowaniem XML JSON JSONAPI
Jednostka terytorialna z identyfikatorem Id=030200000000 XML JSON JSONAPI
Metadane XML JSON
Lata
Lista wszystkich lat obowiązywania XML JSON JSONAPI
Rok z identyfikatorem Id=2003 XML JSON JSONAPI
Metadane XML JSON
Tematy
Lista wszystkich tematów najwyższego poziomu XML JSON JSONAPI
Temat z identyfikatorem Id=K3 XML JSON JSONAPI
Lista tematów drugiego poziomu dla tematu nadrzędnego z Id=K3 XML JSON JSONAPI
Wyszukiwanie tematów ze słowem 'samochody' w nazwie XML JSON JSONAPI
Metadane XML JSON
Zmienne
Lista wszystkich zmiennych XML JSON JSONAPI
Lista zmiennych dla tematu z Id=P2137, występujących w latach 2005,2006 XML JSON JSONAPI
Zmienna z identyfikatorem Id=1688 XML JSON JSONAPI
Wyszukiwanie zmiennych ze słowem 'samochody' w nazwach wymiarów XML JSON JSONAPI
Metadane XML JSON

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

Kontakt

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

Statystyki

178 917 468 zapytań od 04.12.2018

4 975 zarejestrowanych użytkowników


Dzienne wykorzystanie usługi - ostatnie 7 dni

logo GUS

Główny Urząd Statystyczny
Aleja Niepodległości 208
00-925 Warszawa
Przejdź do Portalu GUS

Copyright © 2018-2023 Główny Urząd Statystyczny

Deklaracja dostępności