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.

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.

---

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/

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

186 844 000 queries from 04.12.2018

5 522 registered users

---

The daily use of the service - last 7 days