Privacy and Cookie Policy

We use cookies to improve the user experience. By continuing on this page, you accept our use of cookies.

OK

Please read our Privacy and Cookie Policy here to find out more.

Databank API - Beta

With Statistics Denmark’s API for StatBank it is possible to get access to all the published data in StatBank.

Console

We have made a console available whereby one can try out the API.

The console is a manual tool for programmers who want to use the API. The tool helps the programmer in terms of finding out how the API is called. The console is in Danish, if the browser has that as preferred language, otherwise in English.

Start console

General introduction

Queries are sent to the preferred functions’ URL and the necessary information is posted as a JSON-object.

As a rule, all communication must be UTF-8 encoded.

The API can respond in respectively JSON or XML. Regarding DATA call, other return formats apply.

It is possible to provide parameters in the URL, but it is recommended to POST data. When supplying parameters in the URL (GET), the information must be URL encoded. For examples, see the console.

The API’s address is http://api.statbank.dk.

Function

Version number and name of the desired function must always be provided:
http://api.statbank.dk/v1/subjects
http://api.statbank.dk/v1/tables
http://api.statbank.dk/v1/tableinfo
http://api.statbank.dk/v1/data

Language

From the outset, the API will respond in Danish. For every call, the language can be stated with a parameter:

{
   "lang": "en"
}

Either ”da” for Danish or ”en” for English can be stated.

In some cases the API will return error messages in both Danish and English if the error has resulted in lacking determination of language.

Format

For all other functions than DATA, the formats JSON or XML can be stated:

{
   "format": "JSON"
}

Tables and subjects

There are two ways of finding tables via the API: the functions SUBJECTS and TABLES.

SUBJECTS

The function SUBJECTS gives access to the hierarchy of subjects that contains all the tables. The hierarchy can be queried one or several levels at a time.

If the function is called without parameters, the upper level in the hierarchy will be returned. Afterwards, these subjects’ subtopics can be found by calling SUBJECTS once again with statement of the desired subjects etc..

The following function specific parameters can be provided:

{
   "subjects": [
      "02",
      "2401"
   ],
   "includeTables": true,
   "recursive": true
}

subjects: Subjects for which subtopics are wanted.

includeTables: Whether the result should contain tables. Otherwise, only subjects are returned and tables can subsequently be retrieved with the function TABLES..

recursive: Whether subtopics/tables will be retrieved all the way down the hierarchy. Otherwise, only the closest level under the provided subjects will be retrieved. .

TABLES

The function TABLES return tables that are criteria filtered. If no criteria are specified, all tables are returned.

The following function specific parameters can be provided:

{
   "subjects": [
      "02",
      "2401"
   ],
   "pastdays": 1,
   "includeinactive": true
}

subjects: Subjects from which tables will be returned. Subject codes are retrieved with the function SUBJECTS.

pastdays: Number of days backwards, for which to return updated tables.

includeInactive: Whether to return tables that no longer are updated.

Metadata and data

A table consists of metadata and data.

Metadata is information about e.g. the table’s title and the unit of data. For certain data formats, e.g. CSV, this information is only available through metadata. Therefore, the information has to be read in connection with every data request.

In terms of other formats such as Excel or chart (PNG), the data response itself contains information about e.g. title and unit. Yet, it might be beneficial to read metadata in order to see e.g. a possible note for data.

TABLEINFO

The function TABLEINFO returns metadata for a table. The answer contains information about variables and their codes. Use these codes when data is requested with the function DATA.

Table must always be stated:

{
   "table": "folk1c"
}

DATA

The function DATA returns data from a table.

The API tries to eliminate the variables for which values have not been selected. If region is not selected in the table FOLK1C, for instance, data will be returned for the entire country.

In case that elimination is not desired for certain variables, the variable by its code must be provided along with the codes for the desired values. Codes for variables and values are found via the function TABLEINFO.

For instance, the table FOLK1C’s variable “country of origin” has the code “ieland”, and the value “Denmark” for this variable has the code “5100”. If data is desired for those observations where the country of origin is Denmark, the following must be provided:

{
   "table": "folk1c",
   "format": "CSV",
   "variables": [
      {
         "code": "ieland",
         "values": [
            "5100"
         ]
      }
   ]
}

”*” can be used as wildcard for value codes, indicating that ”*” means all values and e.g. ”*K1” means all values with a code ending with “K1”.

Some tables contain variables that cannot be eliminated automatically. Values always have to be selected for these variables. Data formats that are streamed, do not currently allow elimination of variables.

A total is stated as e.g. “sum(0-4;5-9;10-14;15-19;20-24)”, which will return a sum for the stated codes. A text can be added to a sum: "sum(0-24 year=0-4;5-9;10-14;15-19;20-24)" as well as a code: "sum(0_24|0-24 year=0-4;5-9;10-14;15-19;20-24)". If the same request is used to retrieve data in different languages, it can be useful to add specific texts for every language: "sum(0_24|[da 0-24 år][en 0-24 years]=0-4;5-9;10-14;15-19;20-24)".

Periods are returned as distinct and sorted (either increasingly or as stated in timeOrder), regardless of the order and duplicates in the request. Periods can – as with other variables’ values – be stated by code and possibly include the wildcard ”*”. Moreover, nth rules can be used for statement of periods. Nth rules always have to be encircled with brackets. +/- placed in front or first/last specifies the desired sequence of the periods. The three latest periods can e.g. be stated (-n +3). Three oldest periods -(-n+3), newest period (1), second newest period (2), second oldest period -(2) etc. Codes and rules can be mixed in a comma separated list. The nth rule works as the css selector described at http://www.w3.org/TR/2011/REC-css3-selectors-20110929/#nth-child-pseudo.

If a period is not stated, data will be returned for the latest period in the table, corresponding to the statement “(1)”.

There are the following function specific parameters. “table” and “format” is mandatory.

{
   "table": "folk1c",
   "format": "CSV",
   "valuePresentation": "Default",
   "timeOrder": "Ascending",
   "variables": [
      {
         "code": "OMRÅDE",
         "placement": "stub",
         "values": [
            "000",
            "185",
            "791",
            "787"
         ]
      },
      {
         "code": "KØN",
         "values": [
            "*"
         ]
      },
      {
         "code": "Tid",
         "values": [
            "2010k2",
            "(1)"
         ]
      }
   ]
}

table: Table that data are retrieved from.

format: Desired format for return of data. See the paragraph Data formats bellow.

valuePresentation: How text is shown. The parameter can be omitted or one of the following values can be stated:
Default, Code, Value, CodeAndValue or ValueAndCode

timeOrder: The sequence for periods stated as ascending or descending.

variables: Collection of variable objects with statement of its code and the codes for the desired values. In the example, data are retrieved for the areas: All Denmark (000), Tårnby (185), Viborg (791) and Thisted (787), for both sexes (*) for the period second quarter 2010 (2010K2) and the latest period ((1)). Moreover, it is stated that the variable “OMRÅDE” is to be placed in the table’s stub (stated as head or stub).

Data formats

The following data formats can be selected for the DATA function:

PX : PC-Axis (ANSI)
CSV: Semicolon separated
JSONSTAT: JSON-stat
DSTML: StatBank's XML-format
PNG: Graph as picture (see description below)
AREMOS: AREMOS

The following are streaming formats, which are described below:
BULK: Semicolon separated file
SDMXCOMPACT: SDMX-ML Compact
SDMXGENERIC: SDMX-ML Generic

The following are presentation formats for which small changes may be implemented in the production environment, even though the system does not change version number.
XLSX: Excel
HTML: HTML

Special data formats

PNG

Data can be returned as a chart. For this format a number of parameters can be stated, which determine how the chart will be presented in the returned image file.

{
   "table": "folk1c",
   "format": "PNG",
   "variables": [
      {
         "code": "køn",
         "values": [
            "1",
            "2"
] } ], "chartsettings": { "type": "column", "width": "900", "height": "400", "showlegend": "true", "showtitle": "true", "fontsize": "13", "sort": "false", "autopivot": "true", "labelsangle": "0",
"titlecolor": "ff000000",
"seriescolors": [ "00ff00", "0000ff" ], "valuecolors": [ "2ff0000" ] } }

In the example, data is collected from the table FOLK1C. The values for Men (1) and Woman (2) are chosen for the variable sex (KØN). In addition, a number of settings about the chart’s presentation are stated.

type: Chart type for presentation of data. The following values can be stated:
Line, Column, StackedColumn, StackColumn100, Bar, StackedBar,
StackedBar100, Area, StackedArea, StackedArea100, Pie, ColumnAndLines, Population.

width: The image’s width in pixels.

height: The image’s height in pixels.

When changing the size, not only scaling of the image will take place. The chart’s layout itself is determined by the available space.

showlegend: Whether the image must contain a box with specification of series texts.

showtitle: Whether the image must contain the table’s title and subtitle.

fontsize: Font sixe.

sort: Whether the observations must be sorted.

autopivot: Whether the variable with most values must be removed to the label axis.

labelsangle: Angle of texts on the label axis.

seriescolors: Collection of colours for series. Colours are specified as e.g. “ff0000” for red. In the example above, green and blue are specified as the first colours that will be used for series.

valuecolors: Collection of colours for specific values. Specified by code followed by colour. For instance, “2012K400ff00” means that fourth quarter of 2012 will be displayed in green. In the example above, it is specified that observations with the code (women) will be displayed in red.

STREAMING FORMATS

If many values are chosen for a table, some extracts may be too large to handle at the server. Some extracts may contain billions of cells.

Since dataset of this size easily can be used in e.g. databases, we have decided to make this output type available.

The result is different from the other formats as regards several important aspects:

- Some observations are omitted. If a combination of values is missing, the observation for this combination is 0 (the number zero). If the combination is present, but the number is missing, it either means that the observation is missing, it is confidential or it is too insecure to be stated.

- Variables cannot be omitted (eliminated) and the rows (the values) are not necessarily sorted in the same order as prescribed in the query.

Change of BETA log

We continuously develop the source code in order to improve and optimize the API. In the BETA period these changes will be implemented in the production environment. Yet, the API version number will not be increased.

Some changes which apply to the usage of the API will – in this period – be added to the following list.

October 2017
   - HTTPS now supported. Please use right away. Later on we will 301-redirect all HTTP requests, in which case a POST request body will be lost.
   - Now possible to allow multiple variables in head of CSV-output
   - Now possible to let value presentation override codes in column names of CSV-output
   - Bug fixed where third party component failed on dataset with exactly one timeperiod, where it's code contained "-"
   - Changed in backend regarding caching of data

September 2017
   - Elimination value can no longer be part of a sum
   - Sum values can be delimited by comma
   - Console use own jQuery, so it can be used in a closed system opened for that specific site

June 2017
   - Headers trimmed for special characters to improve usage in other systems
   - Correct transfer of chartsettings when using GET request

March 2017
   - Improved CORS
   - Charts limited to a maximum of 50 series

January 2017
   - Added returned status code and headers to console
   - Added contact information to TABLEINFO

October2016
   - Added information about documentation of statistics to TABLEINFO

June 2016
   - An error when extracting data in JSONSTAT, when multiple variables has geo-information is fixed

April 2016
   - Added information on geographic map for variable (map) to TABLEINFO

March 2016
   - Added information on subject status (active) to SUBJECTS

December 2015
   - Improved error messages for errors when using saved queries

October 2015
   - Corrections for content variable in JSONSTAT
   - Corrections for selection of valuepresentation

Juli 2015
   - An error where time code was presented in English when extracted in Danish is fixed
   - Now possible to eliminate a variable by one of its values

Juni 2015
   - Presentation text as value followed by code no longe available 

April 2015
   - The data format in the functions SUBJECTS and TABLES does now correspond to the format in TABLEINFO
   - Restrictions for sums for certain tables, variables and method of measurement (stock/flow etc.)
   - Comma can be used in summation texts

March 2015
   - Incorporations of sums in data extract

November 2014
   - Statements of times with nth rules (something resembling http://www.w3.org/TR/2011/REC-css3-selectors-20110929/#nth-child-pseudo)
   - AREMOS format is removed

October 2014
   - Column headline is added for the formats CSV and BULK
   - The format BULK is able to show text now. If codes are desired, choose explicitly valuePresentation=code

Responsible for this page

Web og Statistikbank