PxApi

PxApi(url, language=None, disable_cache=False, timeout=30)

A wrapper around the PxWeb API. Enables exploring available datasets interactively, getting table data, variables as well as other metadata.

Parameters

Name	Type	Description	Default
url	str | KnownApi	Either a shorthand name for a builtin API, e.g. “scb”. To check out avaiable APIs, use get_known_apis().	required
language	str	The language to be used with the API. You can check available languages using the .get_config() method.	None
disable_cache	bool	Disable the in-memory cache that is used for API responses.	False
timeout	int	The timeout in seconds to use when calling the API.	30

Examples

Get the SCB PxWeb API using the shorthand:

>>> api = PxApi("scb")
>>> api
PxApi(url='https://api.scb.se/ov0104/v2beta/api/v2',
           language='sv',
           disable_cache=False,
           timeout=30)

Methods

Name	Description
all_tables	Get a list of all tables available with some basic metadata. Use .get_table_metadata() for extensive metadata about a specific table.
get_code_list	Get information about a code list.
get_config	Retrieve the configuration for the API.
get_paths	List all paths available to explore. Use the ID to list tables on a specific path with .tables_on_path().
get_table_data	Get table data that can be used with dataframes like polars or pandas. The query is constructed with the method parameters.
get_table_metadata	Get the complete set of metadata for a table.
get_table_variables	Get the specific metadata for variables and value codes. Also includes information whether a variable can be eliminated as well as the available code lists.
search	Search for tables.
tables_on_path	List all the tables available on the path.

all_tables

PxApi.all_tables()

Get a list of all tables available with some basic metadata. Use .get_table_metadata() for extensive metadata about a specific table.

Returns

Name	Type	Description
	list[dict]	All tables.

get_code_list

PxApi.get_code_list(code_list_id)

Get information about a code list.

Parameters

Name	Type	Description	Default
code_list_id	str	The ID of a code list.	required

Returns

Name	Type	Description
	dict	The API response with the code list information.

Examples

By checking out the table variables with the .get_table_variables() method we can get available code lists.

>>> meta = api.get_table_variables("TAB638")

With the metadata, get the code lists available for “Region”.

>>> meta.get("Region").get("codelists")
[{'id': 'agg_RegionA-region_2', 'label': 'A-regioner'},
{'id': 'agg_RegionKommungrupp2005-_1', 'label': 'Kommungrupper (SKL:s) 2005'},
{'id': 'agg_RegionKommungrupp2011-', 'label': '...'},
{'id': 'vs_RegionKommun07', 'label': 'Kommuner'},
{'id': 'vs_RegionLän07', 'label': 'Län'},
{'id': 'vs_RegionRiket99', 'label': 'Riket'},
...]

Now we can look closer at a specific code list by using the method.

>>> api.get_code_list("vs_RegionLän07")
{
...     'id': 'vs_RegionLän07',
...     'label': 'Län',
...     'language': 'sv',
...     'type': 'Valueset',
...     'values': [
...         {'code': '01', 'label': 'Stockholms län'},
...         {'code': '03', 'label': 'Uppsala län'},
...         {'code': '04', 'label': 'Södermanlands län'},
...         ...
...     ]
... }

get_config

PxApi.get_config()

Retrieve the configuration for the API.

Returns

Name	Type	Description
	dict	The API response containing the configuration.

Examples

>>> conf = api.get_config()

Check the languages available.

>>> conf.get("languages")
[{'id': 'sv', 'label': 'Svenska'},
 {'id': 'en', 'label': 'English'}]

get_paths

PxApi.get_paths(path_id=None)

List all paths available to explore. Use the ID to list tables on a specific path with .tables_on_path().

Examples

>>> api.get_paths()
[
... {'id': 'AA', 'label': 'Ämnesövergripande statistik'},
... {'id': 'AA0003', 'label': 'Registerdata för integration'},
... {'id': 'AA0003B', 'label': 'Statistik med inriktning mot arbetsmarknaden'},
... {'id': 'AA0003C', 'label': 'Statistik med inriktning mot flyttmönster'},
... {'id': 'AA0003D', 'label': 'Statistik med inriktning mot boende'},
... ...
]

You can also inspect a subpath by supplying a path_id.

>>> api.get_paths("AM0101")
[
... {'id': 'AM', 'label': 'Arbetsmarknad'},
... {'id': 'AM0101',
...  'label': 'Konjunkturstatistik, löner för privat sektor (KLP)'},
... {'id': 'AM0101A', 'label': 'Arbetare: Timlön efter näringsgren'},
... {'id': 'AM0101B', 'label': 'Tjänstemän: Månadslön efter näringsgren'},
... {'id': 'AM0101C', 'label': 'Äldre tabeller som inte uppdateras'},
... {'id': 'AM0101X', 'label': 'Nyckeltal'},
]

Returns

Name	Type	Description
	list[dict]	Paths available.

get_table_data

PxApi.get_table_data(table_id, value_codes=None, code_list=None)

Get table data that can be used with dataframes like polars or pandas. The query is constructed with the method parameters. An empty value code selection returns a default selection for the table.

Parameters

Name	Type	Description	Default
table_id	str	An ID of a table to get data from.	required
value_codes	dict	The value codes to use for data selection where the keys are the variable codes. You can use the .get_table_variables() to explore what’s available.	None
code_list	dict	Any named code list to use with a variable for code selection.	None

Returns

Name	Type	Description
	list[dict]	A dataset in a native format that can be loaded into a dataframe.

Examples

A simple query to get the population of 2024 for all the Stockholm municipalities using 5-year age groups.

>>> dataset = api.get_table_data(
...     table_id="TAB638",
...     value_codes={
...         "ContentsCode": ["BE0101N1"],
...         "Region": ["01*"],
...         "Alder": ["*"],
...         "Tid": ["2024"]
...     },
...     code_list={
...         "Alder": "agg_Ålder5år",
...         "Region": "vs_RegionKommun07"
...     }
... )

This dataset can then easily be turned into a dataframe, for example with polars.

>>> pl.DataFrame(dataset)
shape: (572, 5)
┌─────────────────────┬────────────────┬────────────────┬──────┬───────┐
│ region              ┆ ålder          ┆ tabellinnehåll ┆ år   ┆ value │
│ ---                 ┆ ---            ┆ ---            ┆ ---  ┆ ---   │
│ str                 ┆ str            ┆ str            ┆ str  ┆ i64   │
╞═════════════════════╪════════════════╪════════════════╪══════╪═══════╡
│ 0114 Upplands Väsby ┆ 0-4 år         ┆ Folkmängd      ┆ 2024 ┆ 2931  │
│ 0114 Upplands Väsby ┆ 5-9 år         ┆ Folkmängd      ┆ 2024 ┆ 3341  │
│ 0114 Upplands Väsby ┆ 10-14 år       ┆ Folkmängd      ┆ 2024 ┆ 3237  │
│ 0114 Upplands Väsby ┆ 15-19 år       ┆ Folkmängd      ┆ 2024 ┆ 3083  │
│ 0114 Upplands Väsby ┆ 20-24 år       ┆ Folkmängd      ┆ 2024 ┆ 2573  │
│ …                   ┆ …              ┆ …              ┆ …    ┆ …     │
│ 0192 Nynäshamn      ┆ 85-89 år       ┆ Folkmängd      ┆ 2024 ┆ 554   │
│ 0192 Nynäshamn      ┆ 90-94 år       ┆ Folkmängd      ┆ 2024 ┆ 230   │
│ 0192 Nynäshamn      ┆ 95-99 år       ┆ Folkmängd      ┆ 2024 ┆ 51    │
│ 0192 Nynäshamn      ┆ 100+ år        ┆ Folkmängd      ┆ 2024 ┆ 7     │
│ 0192 Nynäshamn      ┆ uppgift saknas ┆ Folkmängd      ┆ 2024 ┆ 0     │
└─────────────────────┴────────────────┴────────────────┴──────┴───────┘

get_table_metadata

PxApi.get_table_metadata(table_id)

Get the complete set of metadata for a table.

Parameters

Name	Type	Description	Default
table_id	str	The ID of a table to get metadata from.	required

Returns

Name	Type	Description
	dict	The API response containing the metadata.

Examples

>>> meta = api.get_table_metadata("TAB638")
>>> meta.keys()
dict_keys(['version', 'class', 'href', 'label', 'source',
...         'updated', 'link', 'note', 'role', 'id',
...         'size', 'dimension', 'extension'])
>>> meta.get("label")
'Folkmängden efter region, civilstånd, ålder, kön, tabellinnehåll och år'

get_table_variables

PxApi.get_table_variables(table_id)

Get the specific metadata for variables and value codes. Also includes information whether a variable can be eliminated as well as the available code lists. The information returned is unpacked and slightly more easily navigated than the output from the .get_table_metadata() method.

Parameters

Name	Type	Description	Default
table_id	str	The ID of a table to get metadata from.	required

Returns

Name	Type	Description
	dict	The API response containing the metadata.

Examples

>>> api.get_table_variable("TAB638")
{
...     'Region': {
...         'label': 'region',
...         'category': {'label': {'00': 'Riket', '01': 'Stockholms län', ...}},
...         'elimination': True,
...         'codelists': [{'id': 'vs_RegionKommun07', 'label': 'Kommuner'}, ...]
...     },
...     'Alder': {
...         'label': 'ålder',
...         'category': {'label': {'0': '0 år', '1': '1 år', ...}},
...         'elimination': True,
...         'codelists': [{'id': 'agg_Ålder5år', 'label': '5-årsklasser'}, ...]
...     },
...     'Tid': {
...         'label': 'år',
...         'category': {'label': {'2022': '2022', '2023': '2023', ...}},
...         'elimination': False,
...         'codelists': []
...     },
...     ...
}

search

PxApi.search(
    query=None,
    past_days=None,
    include_discontinued=None,
    page_size=None,
)

Search for tables.

Parameters

Name	Type	Description	Default
query	str	A string to search for.	None
past_days	int	Return results where tables have been updated within n number of days.	None
include_discontinued	bool	Include any tables that are discontinued.	None
page_size	int	Number of results per page in the returning dict. Results will be paginated if they exceed this value.	None

Returns

Name	Type	Description
	dict	The API response of the search query.

Examples

>>> api = PxApi("scb")
>>> search = api.search(query="arbetsmarknad", past_days=180)
>>> len(search.get("tables"))
4

tables_on_path

PxApi.tables_on_path(path_id)

List all the tables available on the path.

Examples

>>> api.tables_on_path("AM0101C")
[
... {'id': 'TAB2566',
...  'label': 'Genomsnittlig månadslön för tjänstemän, privat sektor (KLP) efter näringsgren SNI2002 ...'},
... {'id': 'TAB2552',
...  'label': 'Genomsnittlig timlön för arbetare, privat sektor (KLP) efter näringsgren SNI2002 ...'},
... {'id': 'TAB386',
...  'label': 'Antal arbetare inom industrin efter näringsgren SNI92 ...'},
... {'id': 'TAB2565',
...  'label': 'Genomsnittlig månadslön för tjänstemän, privat sektor (KLP) efter provision och näringsgren SNI92 ...'},
... {'id': 'TAB2551',
...  'label': 'Genomsnittlig timlön för arbetare, privat sektor (KLP) efter näringsgren SNI92 ...'},
... ...
]     

Returns

Name	Type	Description
	list[dict]	All tables on the path.