• Information Portal
  • A
  • A
  • A
  • Information Portal
  • A
  • A
  • A

API BDL

  • Back
  • API TranStat
  • API SDP
  • API DBW
  • API REGON
  • API TERYT
  • API SDG
  • API STRATEG
API TranStat API SDP API DBW API REGON API TERYT API SDG API STRATEG Back
General information Registration Manual Contact Statistics
General information

LOCAL DATA BANK (POL.: BDL) is Poland's largest database of the economy, society and the environment.

BDL offers thousands statistical data grouped thematically. The first data comes from 1995.

  • Data and indicators describe statistical towns, municipalities, counties, voivodships and Poland as well as units compliant with the NUTS nomenclature: subregions, regions and macroregions.
  • Information resources (annual and short-term statistics) are constantly supplemented and updated.

The API application allows to browse and download for further processing the full range of data located in the Bank. The data is made available through REST API in XML and JSON format.

The BDL API was implemented as part of a project "Open data - access, standard, education", whose leader is the Ministry of Digitization. The project is co-financed from the European Union funds from the Operational Program Digital Poland.

Registration
Manual

Scope of information

The scope of data available in the API and in the BDL web application is the same, but for technological and ergonomic reasons, the organization and presentation of information is slightly different. This is to ensure an easy start for new users who do not know the BDL structure, as well as the appropriate performance and convenience of using the so-called permanent users.


Limits and API key

For API security reasons, quantitative limits are imposed on the number of requests. Users who need larger limits may register and get an automatically generated personal API key. The API key should be provided in the request as an HTTP header named X-ClientId, e.g.

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

In the field of requests, the following user limits apply:

Period Anonymous user Registered user
1s 5 10
15m 100 500
12h 1 000 5 000
7d 10 000 50 000

Resource structure

The following BDL resources are made available in the API application:

  1. Aggregates - data aggregation levels for which data are available, e.g. municipalities or urban-rural communes.
  2. Attributes - descriptions of specific situations in the data that are associated with each numerical value, e.g. 'Value smaller than the adopted presentation format'.
  3. Data - numerical data in the form of three [real number, attribute identifier, year identifier], in the form of a data set for a specific variable or set of data for one unit (more information below).
  4. Units of measurement - units of measurement appearing in the data, related to specific variables, e.g. 'thousand liters'.
  5. Level of validity - the level of validity of data by:
    • 0 - Polish level
    • 1 - Macro-regions level
    • 2 - Voivedships level
    • 3 - Regions level
    • 4 - Subregions level
    • 5 - Counties level
    • 6 - Municipalities level
    • 7 - Statistical towns level
  6. Topics – hierarchically related groups of variables according to the substantive scope, eg. 'Population', 'Population by age and gender groups' (more information below).
  7. Units - hierarchically related list of territorial units (from Poland up to municipalities) and statistical towns.
  8. Variables - these are multidimensional features representing a specific phenomenon, with a defined validity in years and at a specific level of units, e.g. the number of employees for the ages of '20 -26 'and gender' men '.
  9. Years - years of validity for which data may exist, e.g. '2003', '2004'.

Variability and quantity of resources

Resources such as Aggregates, Attributes, Units of Measure and Years are dictionary resources with very low variability and multiplicity, therefore they can be treated as so-called 'typical dictionaries', occasionally updated at specific time intervals or at the user request. These resources are not paged and can’t be searched according to complicated criteria.

Resource such as Units, denoting the territorial division units, is a resource of large multiplicity and very small variability, updated only when inputting the data for the new year in BDL (at the beginning of the year). Due to its multiplicity, it may cause difficulties in downloading it in full size, therefore we are able to search and download partially according to our own criteria, of course in a limited scope.

Resources such as Data and Variables are resources with very high variability, because the Bank is constantly undergoing the process of extending the scope of data as well as verification and corrections.


Downloading data

The data is made available by the API in two alternative ways:

  • for one variable and many territorial units
  • for one territorial unit and many variables

Data for one variable and many territorial units

The process of downloading data for one variable and many territorial units in a simplified way may look as follows:

  1. Download a list of main level topics, e.g.

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

  2. Choose a topic and download a list of sublevels until you reach the level in which the topic has variables (hasVariables=true), e.g.

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

  3. Download the list of variables for the selected topic and select the variable of interest.

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

  4. Download data for the selected variable, possibly narrowing down the list of territorial units and years to an interesting range, e.g.

    /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

Data for one territorial unit and many variables

The process of downloading data for one territorial unit and many variables in a simplified way may look as follows:

  1. Select a territorial unit by navigating the list of territorial units, e.g.

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

  2. Download a list of main level topics, e.g.

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

  3. Navigating the list of topics and variables, select the variables that interest you, e.g.

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

  4. Download data for the selected unit and selected variables, narrowing down the range of years, e.g.

    /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

In both approaches, the issue of discretionary is the time and the rules for retrieving dictionary data, i.e. attributes, aggregate lists, etc.


Examples

We invite you to read the examples of valid API calls.

  • Aggregates
  • Attributes
  • Data
  • Units of measure
  • The level of validity
  • Territorial units
  • Years
  • Topics
  • Variables
List of all aggregates XML JSON JSONAPI
Aggregate with identifier Id=3 XML JSON JSONAPI
Metadata XML JSON
List of all attributes XML JSON JSONAPI
Attribute with identifier Id=K3 XML JSON JSONAPI
Metadata XML JSON
Data for the variable with identifier Id=3643 for the years 2000, 2010 XML JSON JSONAPI
Data for the variable with identifier Id= 65809 for the years 2004-2006 XML JSON JSONAPI
Data for the variable with identifier Id=420, for the locality from the Małopolska voivodeship XML JSON JSONAPI
Data for a territorial unit with Id=012400000000, for the variable with Id=3643, for the years 2004-2006 XML JSON JSONAPI
Data for the locality with Id=030210564011-0986283, for the variable with Id=270672 XML JSON JSONAPI
Metadata XML JSON
List of all units of measure XML JSON JSONAPI
Unit of measure with identifier Id=3 XML JSON JSONAPI
Metadata XML JSON
List of all levels of validity XML JSON JSONAPI
Level of validity with identifier Id=3 XML JSON JSONAPI
Metadata XML JSON
List of all territorial units XML JSON JSONAPI
List of all territorial units with their own paging XML JSON JSONAPI
Territorial unit with identifier Id=030200000000 XML JSON JSONAPI
Metadata XML JSON
A list of all years of validity XML JSON JSONAPI
Year with identifier Id=2003 XML JSON JSONAPI
Metadata XML JSON
List of all top-level topics XML JSON JSONAPI
Topic with identifier Id=K3 XML JSON JSONAPI
List of second-level topics for the parent topic with Id=K3 XML JSON JSONAPI
Searching topics with the word 'cars' in the name XML JSON JSONAPI
Metadata XML JSON
List of all variables XML JSON JSONAPI
List of variables for the topic with Id=P2137, occurring in the years 2005,2006 XML JSON JSONAPI
Variable with identifier id=1688 XML JSON JSONAPI
Searching for variables with the word 'cars' in the names of dimensions XML JSON JSONAPI
Metadata XML JSON
Aggregates
List of all aggregates XML JSON JSONAPI
Aggregate with identifier Id=3 XML JSON JSONAPI
Metadata XML JSON
Attributes
List of all attributes XML JSON JSONAPI
Attribute with identifier Id=K3 XML JSON JSONAPI
Metadata XML JSON
Data
Data for the variable with identifier Id=3643 for the years 2000, 2010 XML JSON JSONAPI
Data for the variable with identifier Id= 65809 for the years 2004-2006 XML JSON JSONAPI
Data for the variable with identifier Id=420, for the locality from the Małopolska voivodeship XML JSON JSONAPI
Data for a territorial unit with Id=012400000000, for the variable with Id=3643, for the years 2004-2006 XML JSON JSONAPI
Data for the locality with Id=030210564011-0986283, for the variable with Id=270672 XML JSON JSONAPI
Metadata XML JSON
Units of measure
List of all units of measure XML JSON JSONAPI
Unit of measure with identifier Id=3 XML JSON JSONAPI
Metadata XML JSON
The level of validity
List of all levels of validity XML JSON JSONAPI
Level of validity with identifier Id=3 XML JSON JSONAPI
Metadata XML JSON
Territorial units
List of all territorial units XML JSON JSONAPI
List of all territorial units with their own paging XML JSON JSONAPI
Territorial unit with identifier Id=030200000000 XML JSON JSONAPI
Metadata XML JSON
Years
A list of all years of validity XML JSON JSONAPI
Year with identifier Id=2003 XML JSON JSONAPI
Metadata XML JSON
Topics
List of all top-level topics XML JSON JSONAPI
Topic with identifier Id=K3 XML JSON JSONAPI
List of second-level topics for the parent topic with Id=K3 XML JSON JSONAPI
Searching topics with the word 'cars' in the name XML JSON JSONAPI
Metadata XML JSON
Variables
List of all variables XML JSON JSONAPI
List of variables for the topic with Id=P2137, occurring in the years 2005,2006 XML JSON JSONAPI
Variable with identifier id=1688 XML JSON JSONAPI
Searching for variables with the word 'cars' in the names of dimensions XML JSON JSONAPI
Metadata XML JSON

Documentation

  • Methods description
  • Swagger
  • ReDoc


The use of data is possible on the basis of Attribution 4.0 International licence (CC BY 4.0.) https://creativecommons.org/licenses/by/4.0/

Contact

If you notice any irregularities in the operation of the BDL API application or if you have any doubts about the scope of the data provided, please contact us by email to clarify the problem.

In order to handle your notification in the most efficient way, please provide us with the most detailed information as it is possible, about the problem you have seen:

  • type of API client (browser and its type, own program, system tool, etc.)
  • programming language (only in case with own program)
  • full URL address which is called
  • the headers and response content returned by the server
  • a text description of the problem observed


Please send technical notifications to the address bdl.kontakt@stat.gov.pl (giving in the subject: API-Pomoc).
Any other notifications or problems of a non-technical nature to the address bdl.kontakt@stat.gov.pl (giving in the subject: API-Informacje).

Statistics

214 976 344 queries from 04.12.2018

7 154 registered users


The daily use of the service - last 7 days

logo

Statistics Poland
Aleja Niepodległości 208
00-925 Warszawa
Go to the Statistics Poland Portal

Copyright © 2018-2025 Statistics Poland
  • Privacy Policy