API reference

Data

get_df

Retrieve one or more ILOSTAT datasets.

Parameters:

Name	Type	Description	Default
dataset_id	str, list of str, or tuple of str	One or more ILOSTAT dataset identifiers.	required
segment	str	ILOSTAT bulk-data segment.	"indicator"
type	('code', 'label', 'both')	Output representation for coded dimensions.	"code"
lang	('en', 'fr', 'es')	Language used for labels.	"en"
filters	dict or None	Filters applied to each dataset.	None
best_source	('yes', 'no', 'all')	Select best-source observations.	"yes"
fixed	bool	If True, treat filter values as literal strings.	True
cache_dir	(str, Path or None)	Directory used to cache downloaded files.	None
refresh	bool	If True, refresh metadata before checking cached data.	False

Returns:

Type	Description
DataFrame	Requested ILOSTAT data.

get_sdmx

Retrieve ILOSTAT resources using SDMX conventions.

Parameters:

Name	Type	Description	Default
dataset_id	str or None	ILOSTAT dataset identifier. Required for data, structure, and codelist resources. For resource="dataflow", None returns the complete dataflow catalogue and a dataset identifier returns the corresponding dataflow.	None
resource	('data', 'structure', 'codelist', 'dataflow')	SDMX resource to retrieve.	"data"
component	str or None	SDMX component identifier used when resource="codelist", for example "REF_AREA", "SEX", or "AGE".	None
segment	str	ILOSTAT bulk-data segment.	"indicator"
type	('code', 'label', 'label_short', 'both')	Output representation used for DataFrame resources. "code" returns codes only. "label" returns localized full labels. "label_short" returns localized compact labels for classification dimensions when available. "both" returns codes together with localized full labels. This option does not modify SDMX-ML or SDMX-JSON serializations.	"code"
format	('dataframe', 'sdmx-ml', 'sdmx-json')	Output format. "dataframe" returns a pandas DataFrame. "sdmx-ml" returns SDMX-ML output where supported. "sdmx-json" returns SDMX-JSON output where supported.	"dataframe"
lang	('en', 'fr', 'es')	Language used for labels and dataflow names.	"en"
filters	dict or None	Filters applied when resource="data".	None
best_source	('yes', 'no', 'all')	Select best-source observations when resource="data".	"yes"
fixed	bool	If True, treat filter values as literal strings when resource="data".	True
cache_dir	(str, Path or None)	Directory used to cache downloaded files.	None
refresh	bool	If True, refresh the relevant resources before checking cached data.	False

Returns:

Type	Description
DataFrame or str	Requested SDMX-oriented resource. SDMX-ML and SDMX-JSON serializations are returned as strings.

Metadata

get_toc

Retrieve an ILOSTAT table of contents.

The TOC is refreshed from the ILOSTAT server once per Python session for each segment, language, and cache directory.

Parameters:

Name	Type	Description	Default
segment	str	ILOSTAT data segment.	"indicator"
lang	('en', 'fr', 'es')	Language of the table of contents.	"en"
cache_dir	(str, Path or None)	Directory used to cache downloaded files.	None
refresh	bool	If True, force a new download of the table of contents.	False

Returns:

Type	Description
DataFrame	ILOSTAT table of contents.

get_metadata

Retrieve metadata for an ILOSTAT dataset.

Parameters:

Name	Type	Description	Default
dataset_id	str	ILOSTAT dataset identifier.	required
segment	str	ILOSTAT data segment.	"indicator"
cache_dir	(str, Path or None)	Directory used to cache downloaded files.	None
refresh	bool	If True, download the metadata again even if a cached copy already exists.	False

Returns:

Type	Description
dict	Dataset metadata.

Dictionaries

get_dic

Retrieve an ILOSTAT dictionary.

Parameters:

Name	Type	Description	Default
dic	str	Dictionary name, for example "ref_area", "sex", or "classif_type".	required
lang	('en', 'fr', 'es')	Dictionary language.	"en"
cache_dir	(str, Path or None)	Directory used to cache downloaded dictionaries.	None
refresh	bool	If True, force a new download of the dictionary.	False

Returns:

Type	Description
DataFrame	Requested ILOSTAT dictionary.

get_dataset_dic

Retrieve the dataset-specific ILOSTAT dictionary.

The cached dictionary is versioned using the dataset last.update value from the table of contents.

Parameters:

Name	Type	Description	Default
dataset_id	str	ILOSTAT dataset identifier.	required
segment	str	ILOSTAT data segment.	"indicator"
cache_dir	(str, Path or None)	Directory used to cache downloaded files.	None
refresh	bool	If True, refresh the table of contents before checking the cached dictionary.	False

Returns:

Type	Description
dict	Dataset-specific dictionary.

Cache

get_cache_dir

Return the ILOSTAT cache directory.

Parameters:

Name	Type	Description	Default
cache_dir	(str, Path or None)	Custom cache directory. If None, use the operating system's standard user cache directory.	None

Returns:

Type	Description
Path	Cache directory.

clean_cache

Remove all files from the ILOSTAT cache.

Parameters:

Name	Type	Description	Default
cache_dir	(str, Path or None)	ILOSTAT cache directory to clean. If None, clean the default ILOSTAT user cache directory. If provided, clean the specified cache directory.	None

Notes

The cache directory itself is preserved.