2024-10-04
PxWebApi 1.0 description Content Content ................................................................................................................. 1 1 Readers’ guide ................................................................................................... 3 1.1 What this instruction covers ..................................................................... 3 1.2 How this document is organised ............................................................... 3 1.3 Terminology .............................................................................................. 3 2 Getting started .................................................................................................. 3 3 URLs................................................................................................................... 3 3.1 API-NAME ................................................................................................. 4 3.2 API-VERSION ............................................................................................ 4 3.3 LANGUAGE ................................................................................................ 5 3.4 DATABASE-ID ........................................................................................... 5 3.5 LEVEL1...LEVELN ...................................................................................... 5 3.6 TABLE-ID .................................................................................................. 5 4 JSON formats ..................................................................................................... 6 4.1 Database result list .................................................................................... 6 4.2 Database levels result list .......................................................................... 6 4.3 Table metadata result ................................................................................ 8 4.4 Table retrieval query ............................................................................... 10 4.4.1 Example of retrivals in format csv ............................................................... 12 4.4.2 Example of retrivals in format csv2 ............................................................. 12 4.4.3 Example of retrivals in format csv ............................................................... 12 Mikael Nordberg Statistics Sweden
2024-10-04 4.5 Table response ......................................................................................... 13 4.5.1 Metadata part ............................................................................................. 13 4.5.2 Data part ................................................................................................... 14 5 Limitations ...................................................................................................... 15 6 Logging ............................................................................................................ 15
2024-10-04
1 Readers’ guide 1.1 What this instruction covers This manual describes how to use the PxWeb API. The manual is primarily intended for people who want an introduction on how to use the API. The reader is not required to have any type of PxWeb experience to understand the content, but it helps. It also helps to have some knowledge of the HTTP protocol. 1.2 How this document is organised Chapters 3 and 4 are intended for the end user who wants to learn more about how to access the API. The other chapters describe the API from a maintenance point of view. 1.3 Terminology HTTP verb – Can be looked upon as HTTP request methods where GET and POST are the most commonly used. HTTP response code – The HTTP protocol uses different response codes to indicate the response status from the user request. For a list of response codes, see http://www.w3.org/Protocols/rfc2616/rfc2616- sec10.html
2 Getting started If you just wish to use the API and want to familiarize yourself with it, you should read Chapters 3 and 4. If you are interested in enabling the API to expose your PxWeb database, then you should read all the chapters.
3 URLs The URL is the way to access the API and it has some similarities to a RESTful API. Note that the examples in this documentation are fictional and may not work in the real database of Statistics Sweden.
2024-10-04 The URLs are constructed with different components: • API-NAME defines the root part of the API. • API-VERSION defines the version of the API. • LANGUAGE defines the language of the data retrieval. DATABASE-ID defines the database where the statistical cubes are stored. • LEVELS defines zero or more levels that show the various divisions in the database. • TABLE-ID defines the identity of the table
Example showing the URL for the table BefProgFoddaMedel11: Suggested URL for implementation at Statistics Sweden would look like:
3.1
API-NAME
Browsing the API-NAME will redirect the caller to an information
page about the API or an Http 404 Not Found response.
3.2
API-VERSION
Browsing the /API-NAME/API-VERSION will redirect the user to a
page with information, e.g. terms of usage, features, etc., for the
specific version of the API.
http://api.scb.se/OV0104/v1/doris/en/ssd/BE/BE0401/BE0401B/BefProgFoddaMedel11
API-NAME/API-VERSION/LANGUAGE/DATABASE-ID/<LEVELS>/TABLE-ID
/axis/v1/sv/ssd/BE/BE0401/BE0401B/BefProgFoddaMedel11
Notice that currently you will get an Http 404 Not Found response.
2024-10-04
3.3 LANGUAGE Browsing (HTTP verb GET) the /API-NAME/API-VERSION/LANGUAGE will result in a JSON formatted result page listing the available databases for that language. 3.4 DATABASE-ID Browsing (HTTP verb GET) the /API-NAME/API- VERSION/LANGUAGE/DATABASE-ID will result in a JSON formatted result page listing the first level nodes of the specified database for the specified language. For the result format, see 4.1. 3.5 LEVEL1...LEVELN Browsing (HTTP verb GET) the /API-NAME/API- VERSION/LANGUAGE/DATABASE-ID/LEVEL1 to /API-NAME/API- VERSION/LANGUAGE/DATABASE-ID/LEVEL1.../LEVELN will result in a JSON formatted result page listing the available levels and tables for the specified databases for that language and that level. For the result format, see 4.2. 3.6 TABLE-ID Browsing (HTTP verb GET) the /API-NAME/API- VERSION/LANGUAGE/DATABASE-ID/LEVEL1.../LEVELN/TABLE-ID will result in a JSON formatted result page specifying the metadata of the table. For the result format, see 4.3.
Browsing (HTTP verb POST) the /API-NAME/API- VERSION/LANGUAGE/DATABASE-ID/LEVEL1.../LEVELN/TABLE-ID requires a JSON formatted query object. The query object specifies what data should be retrieved from the data cube. The result will be formatted in the format specified in the query. For the query format, see 4.4. For the JSON formatted response table, see 4.5.
2024-10-04
4 JSON formats 4.1 Database result list This is an array of database objects that has an identity, dbid and a textual description, text. There are three types of node objects: l, t and h, where l is a sublevel, t is a table and h is a heading. Example result of the URL “/doris/en” shows that we have one database. 4.2 Database levels result list This is an array of node objects that has an identity, id and a textual description, text and a type. Example result of the URL “/doris/en/ssd” shows that we have 15 root nodes in the database.
[
{"id":"BE",
{"id":"FM",
"type":"l",
"type":"l",
"text":"Population"},
"text":"Financial markets"},
{"id":"HE",
{"id":"LE",
"type":"l",
"type":"l",
"text":"Household finances"},
"text":"Living conditions"},
{"id":"MI",
{"id":"NV",
"type":"l",
"type":"l",
"text":"Environment"},
"text":"Business activities"},
{"id":"PR",
{"id":"AM",
"type":"l",
"type":"l",
"text":"Prices and Consumption"},
"text":"Labour market"},
{"id":"BO",
{"id":"HA",
"type":"l",
"type":"l",
"text":"Housing, construction and building"},
"text":"Trade in goods and services"},
{"id":"JO",
{"id":"ME",
"type":"l",
"type":"l",
"text":"Agriculture, forestry and fishery"},
"text":"Democracy"},
{"id":"NR",
{"id":"OE",
"type":"l",
"type":"l",
"text":"National accounts"},
"text":"Public finances"},
] {"id":"UF", "type":"l", "text":"Education and research"} Example result of the URL “/doris/en/ssd/BE/BE0401/BE0401B” shows that we have 4 table nodes in the database. [{"dbid":"ssd","text":"Statistics Sweden"}] [ { "id": "BefolkprognRev2009", "type": "t", "text": "Population by age and sex. Year 2009-2110 2009 - 2110"}, { "id": "BefolkprognRev2010", "type": "t", "text": "Population by age and sex. Year 2010-2110 2010 - 2110"}, { "id": "BefolkprognRev4", "type": "t", "text": "Population size by age and sex. Year 2005-2050 2004 - 2050"}, { "id": "BefolkprognRev2008", "type": "t", "text": "Population by age and sex. Year 2008-2110 2008 - 2110"} ]
2024-10-04
A heading node object can look like this:
[ {"id":"XX", "type":"h", "text":"Population heading"} ]
2024-10-04 4.3 Table metadata result This has a title property and an array of variables. The variable object has four properties: code, text, elimination and time. The code and text properties are mandatory properties, while the elimination and time are optional. If time or elimination is not specified, the default value of “n” is used. The properties time and elimination could have either y (yes) or n (no) specified. If a variable has elimination set to “y”, one can then omit selecting a value for that variable. There can only be one variable that has the time property set to “t” for a table. It also contains two lists. One that contains the codes for the all the values of which the variable can assume and one list of all the presentation text for the values.
Example result of the URL “/doris/sv/ssd/BE/BE0401/BE0401B/BefProgFoddaMedel10” shows that the table consist of four dimensions: region, age, gender and period.
{ "title": "Births by country of birth, age and period", "variables": [ { "code": "Fodelseland", "text": "country of birth", "values":["010","020","030","040","050","060","070"], "valueTexts": ["Sweden","Nordic countries excl. Sweden", "EU excl. Nordic countries", "Europe excl. EU and Nordic countries","Low HDI excl. Europe", "Medium HDI excl. Europe","High HDI excl. Europe"], "elimination": true}, { "code": "Alder", "text": "age", "values": ["-14","15","16","17","18","19","20","21","22","23", "24","25","26","27","28","29","30","31","32","33", "34","35","36","37","38","39","40","41","42","43", "44","45","46","47","48","49+"], "valueTexts": ["-14 years","15 years","16 years","17 years", "18 years","19 years","20 years","21 years", "22 years","23 years","24 years","25 years",
2024-10-04
"26 years","27 years","28 years","29 years", "30 years","31 years","32 years","33 years", "34 years","35 years","36 years","37 years", "38 years","39 years","40 years","41 years", "42 years","43 years","44 years","45 years", "46 years","47 years","48 years","49+ years"], "elimination": true}, { "code": "ContentsCode", "text": "observations", "values":["BE0401M2"], "valueTexts":["Births"]}, { "code": "Tid", "text": "period", "values": ["2010","2011","2012","2013","2014","2015","2016", "2017","2018","2019","2020","2021","2022","2023", "2024","2025","2026","2027","2028","2029","2030", "2031","2032","2033","2034","2035","2036","2037", "2038","2039","2040","2041","2042","2043","2044", "2045","2046","2047","2048","2049","2050","2051", "2052","2053","2054","2055","2056","2057","2058", "2059"], "valueTexts": ["2010","2011","2012","2013","2014","2015","2016", "2017","2018","2019","2020","2021","2022","2023", "2024","2025","2026","2027","2028","2029","2030", "2031","2032","2033","2034","2035","2036","2037", "2038","2039","2040","2041","2042","2043","2044", "2045","2046","2047","2048","2049","2050","2051", "2052","2053","2054","2055","2056","2057","2058", "2059"], "time": true } ] }
2024-10-04
4.4 Table retrieval query The table retrieval query consists of two parts: the actual query and the response object. The query consists of objects that specify which values are selected for each variable. If a selection is missing for a variable, then the values are selected by the following rules:
- If the variable has elimination set to “yes” and has an elimination value (a total value), then only that value is selected.
- If the variable has elimination set to “yes” but has no elimination value, then the aggregated sum of all values is used.
- If the variable has elimination set to “no”, then all values for that variable are selected. The selection consists of a property of the variable code and a selection which has a filter and an array of values. The filter specifies how the values are given. Supported filters are: Item. This filter lists valid values in the values collection. All. This filter uses a wildcard selector on the values. Each wildcard selector is given in the values collection. Only one wild card is allowed. E.g. 01* gives all values that starts with 01, * gives all values. Top. This is used to select the first number of values. The amount of values is given by the first value in the values collection. If the variable is a time variable, then this will select the latest number of time periods. Agg. This states that the values listed in the values collection are aggregated. The identity of the aggregation is given after the colon, e.g. agg:ageG5. Vs. This states that the values listed in the values collection are from a different value set. The identity of the value set is given after the colon, e.g. vs:regionX. The response object is optional. If no response object is specified, a px file formatted result will be returned to the client. Supported formats are: • px • csv • csv2 • csv3
2024-10-04
• json
• xlsx
• json-stat
• json-stat2
• sdmx
The format json-stat will return the response as JSON-stat version 1.2 and the format json-stat2 will return the response as JSON-stat 2.0.
Example POST query to the URL “/doris/en/ssd/BE/BE0401/BE0401B/BefProgFoddaMedel10”. We specify all values for each variable that we are interested in. Since the gender was eliminable, we did not specify it, so we eliminate it.
{
"query": [{"code":"Fodelseland",
"selection":{"filter":"item", "values":["010","020"]}},
{"code":"Alder",
"selection":{"filter":"all", "values":["*"]}},
{"code":"Tid",
"selection":{ "filter":"top", "values":["3"]}}],
"response": {"format":"csv"}
}