Dane demograficzne i gospodarcze gminy (GUS BDL) - dla obszaru, przez API
Sprawdź, jak wygląda gmina albo powiat wokół nieruchomości: ludność, bezrobocie, dochody mieszkańców, budownictwo mieszkaniowe, pokrycie planami miejscowymi. Odpowiedź w JSON, po nazwie miejscowości albo po kodzie TERYT.
Klucz przychodzi mailem, bez karty. Autoryzacja to jeden nagłówek Authorization: Bearer. Poniższe wywołanie możesz uruchomić od razu, bez rejestracji.
{
"location": {
"name": "Powiat m. Gdynia",
"country_code": "PL",
"location_type": "city",
"teryt": "2262",
"level": "powiat"
},
"coverage": "full",
"indicators": {
"unemployment_rate": {
"name": "Stopa bezrobocia rejestrowanego - ogółem",
"unit": "%",
"variable_id": 60270,
"category": "economy",
"level": "powiat",
"values": {
"2025": 2.8
}
},
"gdp_per_capita": {
"name": "Produkt krajowy brutto na 1 mieszkańca (województwo)",
"unit": "zł",
"variable_id": 458421,
"category": "economy_macro",
"level": "wojewodztwo",
"values": {
"2024": 92806
}
}
},
"meta": {
"variables_count": 2,
"categories": [
"economy",
"economy_macro"
],
"levels_included": [
"powiat",
"wojewodztwo"
],
"data_source": "GUS BDL (Bank Danych Lokalnych)",
"as_of": "2025"
},
"demo": true
}Zapytaj nazwą miejscowości albo kodem TERYT, a dostaniesz zestaw wskaźników z Banku Danych Lokalnych, każdy z rokiem, jednostką i poziomem administracyjnym. Odpowiedź opisuje cały obszar administracyjny, więc dwie sąsiednie działki w tej samej gminie dostaną te same liczby. Nazwa miejscowości rozwiązuje się do powiatu, a po dane gminne trzeba zapytać kodem TERYT.
Pola odpowiedzi
Tabela wyjaśnia każde pole z przykładowej odpowiedzi wyżej.
| Pole | Typ | Znaczenie |
|---|---|---|
| location | object | jednostka, której dotyczy odpowiedź, po rozwiązaniu zapytania. Zwróć uwagę na name i level: pytanie nazwą miasta trafia w powiat, więc name bywa inne niż to, o co pytałeś |
| location.name / .country_code / .location_type / .teryt / .level | string | null, string, string, string, string | nazwa z GUS (null przy no_data), kod kraju zawsze PL, rodzaj jednostki (city dla miasta na prawach powiatu, county dla powiatu ziemskiego, municipality dla gminy, voivodeship dla województwa), kod TERYT po rozwiązaniu (gmina zawsze siedmiocyfrowa) oraz poziom: gmina, powiat albo wojewodztwo |
| location.hierarchy | object | jednostki nadrzędne, każda z kodem TERYT i nazwą; możliwe klucze to powiat, podregion i wojewodztwo. Puste dla województwa. W trybie demo tego pola nie ma wcale - dlatego nie widać go w przykładzie wyżej |
| coverage | string | dwa stany. full znaczy, że mamy dla tej jednostki wskaźniki. no_data znaczy, że kod TERYT został zaadresowany, ale GUS nie ma dla niego ani jednej wartości - indicators jest wtedy pustym obiektem, a tokeny wracają |
| indicators | object | słownik: skrót wskaźnika (unemployment_rate, pit_per_capita) na obiekt z opisem i wartościami. Zestaw kluczy zależy od poziomu, o który pytasz, i od filtra category |
| indicators[].name / .unit / .variable_id / .category | string, string, number | null, string | nazwa wskaźnika po polsku tak, jak nazywa go GUS; jednostka (%, zł, m2, szt., osoba, lata, tys. osób, ha, pkt proc.); identyfikator zmiennej w Banku Danych Lokalnych, pusty dla wskaźników liczonych przez nas; jedna z 11 kategorii - demographics, economy, economy_macro, housing, planning, infrastructure, environment, safety, re_market, education, prices |
| indicators[].level | string | poziom administracyjny, z którego pochodzi TA wartość: gmina, powiat, podregion albo wojewodztwo. Pole osobne dla każdego wskaźnika, bo jedna odpowiedź miesza poziomy |
| indicators[].values | object | rok na wartość liczbową. Bez parametrów lat wraca jeden wpis - najświeższy rok dostępny dla tej zmiennej, a nie rok bieżący. Z yearFrom i yearTo wraca cały szereg |
| indicators[].derived | boolean | true dla wskaźnika, którego GUS nie publikuje wprost i który liczymy z opublikowanych zmiennych. Takie pozycje mają variable_id puste |
| indicators[].note | string | zastrzeżenie o jakości danej zmiennej, dołączane tylko tam, gdzie jest potrzebne. Dziś dotyczy budżetów powiatowych miast na prawach powiatu |
| indicators[].snapshot / .snapshot_note | boolean, string | true dla zmiennej ze spisu powszechnego, razem ze zdaniem o tym, kiedy spodziewana jest kolejna. Takiej wartości nie ma sensu monitorować pod kątem świeżości |
| meta | object | podsumowanie odpowiedzi |
| meta.variables_count / .categories / .levels_included / .data_source / .as_of | number, array, array, string, string | null | liczba wskaźników w tej odpowiedzi; kategorie, które w niej wystąpiły; poziomy administracyjne, które w niej wystąpiły; nazwa zbioru źródłowego; najświeższy rok danych spośród wszystkich wskaźników. as_of jest rokiem danych, a nie datą pobrania naszej kopii |
| demo | boolean | obecne i równe true w trybie pokazowym. Tryb pokazowy curuje odpowiedź do pięciu wskaźników i pomija hierarchy; z własnym kluczem API dostajesz komplet |
Jak czytać odpowiedź
Miejsca, w których tę odpowiedź łatwo przeczytać źle.
Nazwa miejscowości rozwiązuje się do powiatu
Parametr location rozwiązuje się przez wykaz nazw do czterocyfrowego kodu powiatu. Zapytanie o Gdynię wraca jako Powiat m. Gdynia z poziomem powiat, i tak samo zachowa się każde inne miasto. Zmierzone 2 września 2026 na produkcji: zapytanie powiatowe zwraca 21 wskaźników, gminne 58. Po dane gminne pytaj więc teryt z sześcioma albo siedmioma cyframi. Siódma cyfra wskazuje inną jednostkę, a nie inny zapis tej samej: 1465011 to cała Warszawa, 1465108 to jej Śródmieście, a 4 i 5 rozdzielają gminę miejsko-wiejską na miasto i wieś, które kod z 3 uśrednia razem.
Jedna odpowiedź miesza cztery poziomy administracyjne
Zapytanie o gminę dokłada do wyniku wszystkie jednostki nadrzędne, bo część wskaźników GUS publikuje dopiero wyżej. W przykładzie obok bezrobocie jest powiatowe, a PKB na mieszkańca wojewódzkie - 92 806 zł opisuje całe Pomorskie, nie Gdynię. Rozkład dla zapytania gminnego, zmierzony 2 września 2026: 37 wskaźników z poziomu gminy, 13 z powiatu, 2 z podregionu i 6 z województwa. Zanim porównasz dwie liczby, sprawdź level przy każdej z nich - zestawienie wskaźnika wojewódzkiego z gminnym da wniosek o niczym.
Najświeższy rok znaczy najświeższy dla tej zmiennej
Bez parametrów lat każdy wskaźnik wraca z ostatnim rokiem, dla którego GUS ma wartość, i te lata się różnią. W pomiarze z 2 września 2026 jedna odpowiedź gminna niosła bezrobocie za 2025, dochody za 2024, PKB podregionu za 2023, dane spisowe za 2021 oraz gęstość zabudowy za 2014. Ostatnia pozycja nie ma przy sobie żadnej flagi ani noty - rok w kluczu values jest jedynym sygnałem. Czytaj ten klucz zawsze, a jeśli potrzebujesz porównywalnego przekroju, zawęź zapytanie parametrem year.
Zero w dochodach powiatu bierze się z ustroju miasta
Miasto na prawach powiatu prowadzi jeden budżet, więc w statystyce dochodów powiatowych raportuje zero. Dotyczy to 52 miast, a w naszym zbiorze wychodzi jako powiat_income_per_capita oraz pit_per_capita_powiat z wartością zerową i z wypełnionym polem note. Dla takich miast czytaj odpowiedniki gminne, gmina_income_per_capita i pit_per_capita, które są kompletne. Ten sam mechanizm zafałszował korelację w naszym audycie z maja 2026: dochody powiatu wyszły ujemnie skorelowane z cenami dokładnie dlatego, że najdroższe rynki miały tam strukturalne zero.
Wskaźnik liczony znika, gdy nie ma z czego go policzyć
Pięć pozycji w odpowiedzi liczymy sami z opublikowanych zmiennych i oznaczamy je polem derived. Kiedy mianownik jest zerowy, takiego wskaźnika po prostu nie ma w indicators - klucz znika, zamiast dostać wartość pustą. Zmierzone 2 września 2026: Duszniki-Zdrój oddały 56 wskaźników zamiast 58, bo w ostatnim roku z danymi nie oddano tam do użytkowania ani jednego mieszkania i średnia powierzchnia nowego mieszkania nie miała dzielnika. Jeśli budujesz na tej warstwie tabelę, sprawdzaj najpierw obecność klucza, a dopiero potem jego wartość.
no_data przy dobrym kodzie zwykle znaczy złą siódmą cyfrę
Nieznana gmina podana sześcioma cyframi kończy się kodem 404. Siedmiocyfrowy kod przechodzi bez sprawdzenia, więc zła siódma cyfra adresuje jednostkę, której nie ma, i wraca odpowiedź 200 z coverage równym no_data oraz pustym indicators. Tokeny za takie wywołanie oddajemy, co widać w nagłówku X-Credits-Refunded, a sama odpowiedź jedzie z Cache-Control: no-store, bo luka w danych bywa przejściowa. Zanim uznasz, że gmina nie ma statystyk, sprawdź, czy siódma cyfra pasuje do jej rodzaju.
Te same wskaźniki dokładają się do porównania dzielnic
Zapytanie GET /api/v1/transactions/summary/compare z parametrem include=demographics zestawia ceny transakcyjne kilku obszarów i dokłada do każdego wiersza kontekst z tej warstwy. Kosztuje 5 tokenów za wywołanie, a samo wzbogacenie nie jest liczone osobno. Zmierzone 2 września 2026 dla Gdyni i Sopotu: 13 pozycji przy każdej dzielnicy, w tym trzy liczone ze zderzenia obu źródeł - price_to_income_years, absorption_rate oraz market_liquidity_per_1000. Kształt odpowiedzi jest tam inny niż tutaj: pojedyncza wartość z rokiem zamiast szeregu.
Cennik
Jedno wywołanie tego endpointu kosztuje 1 token. Tokeny wracają przy każdej odpowiedzi z kodem błędu: zły format kodu TERYT, nierozpoznana nazwa miejscowości, nieznana gmina, niedozwolony zakres lat. Wracają też przy odpowiedzi 200, w której coverage ma wartość no_data - wtedy w nagłówkach widać X-Credits-Refunded. Płatna jest odpowiedź, która niesie choć jeden wskaźnik.
Free
Na próbę
400 tokenów na start, potem 50 tygodniowo
to 400 wywołań tego endpointu
- -Wszystkie endpointy
- -Serwer MCP
- -Bez karty
Standard
Dla rzeczoznawców
60,27 zł brutto
2 000 tokenów / mies.
to 2000 wywołań tego endpointu
- -Wszystko z Free
- -2 000 tokenów API + MCP
- -Pełny dostęp do wyszukiwarki
Professional
Dla programistów i mniejszych zespołów
121,77 zł brutto
5 000 tokenów / mies.
to 5000 wywołań tego endpointu
- -Wszystko ze Standard
- -5 000 tokenów API + MCP
- -Pełny dostęp do wyszukiwarki
Advanced
Dla firm wycenowych i deweloperów
367,77 zł brutto
25 000 tokenów / mies.
to 25 000 wywołań tego endpointu
- -Wszystko z Professional
- -Redystrybucja: dane w Twoim produkcie lub usłudze (z atrybucją Cenogram)
- -Wsparcie e-mail: odpowiedź w 24 h
Business
Dla proptech i większych zespołów
1843,77 zł brutto
200 000 tokenów / mies.
to 200 000 wywołań tego endpointu
- -Wszystko z Advanced
- -White-label: atrybucja nie jest wymagana
- -Wsparcie e-mail: odpowiedź w 8 h
Przejście na wyższy plan zastępuje obecną subskrypcję, a rozliczenie rusza od nowa
Częste pytania
Nie, to API Cenogramu. Bank Danych Lokalnych ma własny publiczny interfejs i jest bezpłatny. My trzymamy wybrane 50 zmiennych z 11 kategorii przygotowane pod rynek nieruchomości, oddajemy je jednym wywołaniem razem z jednostkami nadrzędnymi i pozwalamy zestawić je z cenami transakcyjnymi, więc nie musisz sam składać zapytań o każdą zmienną i każdy poziom osobno.
Nazwa w parametrze location rozwiązuje się do czterocyfrowego kodu powiatu i tak zaprojektowaliśmy to celowo, bo nazwy miejscowości nie są jednoznaczne. Po dane gminne podaj teryt z sześcioma albo siedmioma cyframi, na przykład 146501 albo 1465011 dla Warszawy. Kody znajdziesz przez GET /api/v1/locations, a w Claude przez narzędzie list_locations.
Zależy od poziomu, o który pytasz. Pomiar z 2 września 2026 na produkcji: zapytanie o gminę zwróciło 58 wskaźników, o powiat 21, o województwo 6. Różnica bierze się stąd, że część zmiennych GUS publikuje dopiero na wyższym poziomie, a zapytanie gminne dostaje jednostki nadrzędne w pakiecie. Filtr category i parametry lat zawężają ten zestaw.
Nie. To jedyna warstwa w tej rodzinie z kluczem administracyjnym, więc opisuje całą gminę albo cały powiat. Dwie sąsiadujące działki w tej samej gminie dostaną identyczne wartości. Do danych przypisanych do konkretnej działki służą pozostałe strony w dziale, na przykład pozwolenia na budowę albo strefy planistyczne.
1 token. Tokeny wracają przy każdej odpowiedzi z kodem błędu, czyli przy złym formacie kodu TERYT, nierozpoznanej nazwie miejscowości, nieznanej gminie i niedozwolonym zakresie lat. Wracają też przy odpowiedzi 200 z coverage równym no_data, kiedy kod adresuje jednostkę bez ani jednego wskaźnika - widać to wtedy w nagłówku X-Credits-Refunded. Płacisz za odpowiedź, która niesie dane.
W Claude na nazwę gminy albo kod TERYT odpowiada narzędzie get_demographics. Zwraca ten sam zestaw wskaźników co REST, razem z rokiem i poziomem administracyjnym każdego z nich, i kosztuje 1 token. Zestawienie kilku dzielnic z cenami transakcyjnymi robi osobne narzędzie compare_locations z włączoną demografią. Jak podłączyć serwer MCP.
Bank Danych Lokalnych prowadzi Główny Urząd Statystyczny i udostępnia te dane na licencji CC BY 4.0, więc wolno ich używać komercyjnie i przekazywać dalej pod warunkiem wskazania źródła. Wartości podajemy tak, jak publikuje je GUS, razem z rokiem, jednostką i poziomem administracyjnym. Pięć pozycji liczymy sami z opublikowanych zmiennych - takie wskaźniki mają derived: true i puste variable_id, więc widać w odpowiedzi, gdzie kończy się liczba urzędowa. Naszą kopię zbioru odświeżamy raz w roku. Pełny tekst licencji: CC BY 4.0.
Warunki korzystania z naszego API: regulamin.
Zacznij za darmo
400 tokenów na start, potem 50 tygodniowo. Klucz API w 30 sekund, bez karty.