""" ILOSTAT Data Wrapper Fetches international labour statistics from the ILO ILOSTAT SDMX REST API and the ILOSTAT Bulk Download Facility. API Reference: Base URL (SDMX): https://sdmx.ilo.org/rest TOC (indicators): https://rplumber.ilo.org/metadata/toc/indicator TOC (ref area): https://rplumber.ilo.org/metadata/toc/ref_area Bulk Download CSV: SDMX REST API preferred; bulk .rds files at rplumber.ilo.org/files/indicator/ User Guide: https://webapps.ilo.org/ilostat-files/Documents/SDMX_User_Guide.pdf Authentication: None required — ILOSTAT is open data, no API key needed. Rate Limits: Not formally documented; HTTP 413 is returned when the query result set exceeds the server payload limit (~300,000 records). Use the bulk download facility or add dimension filters to reduce payload size. Response Formats: SDMX-JSON (jsondata), SDMX-CSV (csv / csvfilewithlabels), SDMX-ML (XML) Default format used here: CSV with labels for easy parsing. SDMX Key dimension order (dot-separated): FREQ . REF_AREA . MEASURE . SEX . CLASSIF1 [. CLASSIF2] e.g. "CAN.A.UNE_DEAP_RT.SEX_T.AGE_YTHADULT_YGE15" Wildcarding: omit a dimension to wildcard it (use just the dots). OR logic: use + between values, e.g. "CAN+USA+GBR" Returns JSON output for C++ integration. """ import sys import json import io import requests import traceback from typing import Dict, Any, List, Optional from datetime import datetime # --------------------------------------------------------------------------- # Constants # --------------------------------------------------------------------------- SDMX_BASE_URL = "https://sdmx.ilo.org/rest" # Bulk download: the old www.ilo.org URLs redirect to webapps.ilo.org but both # return 404 for CSV/GZ files as of 2025. The Rilostat R package uses # rplumber.ilo.org which serves .rds (R binary) files. For Python use the # SDMX REST API for data; rplumber.ilo.org only for the TOC CSV endpoint. BULK_BASE_URL = "https://www.ilo.org/ilostat-files/WEB_bulk_download" # Table of Contents: discovered working endpoint on rplumber.ilo.org TOC_BASE_URL = "https://rplumber.ilo.org/metadata/toc" TOC_BY_INDICATOR_URL = f"{TOC_BASE_URL}/indicator" TOC_BY_REF_AREA_URL = f"{TOC_BASE_URL}/ref_area" DEFAULT_TIMEOUT = 60 # seconds # --------------------------------------------------------------------------- # Key indicator codes (measure codes without the DF_ prefix) # These are the 'flow' identifiers used in the SDMX key. # The full dataflow ID used in the URL is: ILO,DF_ # --------------------------------------------------------------------------- # Employment INDICATOR_EMP_TOTAL_SEX_AGE = "EMP_TEMP_SEX_AGE_NB" # Employment by sex & age (number) INDICATOR_EMP_TOTAL_SEX_STE = "EMP_TEMP_SEX_STE_NB" # Employment by sex & status in employment INDICATOR_EMP_TO_POP_RATIO = "EMP_DWAP_SEX_AGE_RT" # Employment-to-population ratio INDICATOR_EMP_MODELLED = "EMP_2EMP_SEX_AGE_NB" # ILO modelled estimates — employment # Unemployment INDICATOR_UNE_RATE_SEX_AGE = "UNE_DEAP_SEX_AGE_RT" # Unemployment rate by sex & age (used in SDMX key) INDICATOR_UNE_TOTAL_SEX_AGE_NB = "UNE_2UNE_SEX_AGE_NB" # Unemployment count (annual) INDICATOR_UNE_MODELLED_RATE = "UNE_DEAP_SEX_AGE_RT" # ILO modelled unemployment rate # Labour Force / Working-Age Population INDICATOR_EAP_TOTAL_SEX_AGE = "EAP_TEAP_SEX_AGE_NB" # Labour force by sex & age INDICATOR_EAP_PARTICIPATION_RATE = "EAP_DWAP_SEX_AGE_RT" # Labour force participation rate INDICATOR_WAP_TOTAL_SEX_AGE = "WAP_WAPF_SEX_AGE_NB" # Working-age population by sex & age # Wages & Earnings (verified dataflow IDs from /dataflow/ILO 2025-02) INDICATOR_EAR_HOURLY_SEX = "EAR_4HRL_SEX_CUR_NB" # Mean hourly earnings by sex & currency (DSD dims: REF_AREA.FREQ.MEASURE.SEX.CUR) INDICATOR_EAR_MONTHLY_SEX = "EAR_4MTH_SEX_CUR_NB" # Mean monthly earnings by sex & currency INDICATOR_EAR_MIN_WAGE = "EAR_4MMN_CUR_NB" # Statutory minimum wage (DSD dims: REF_AREA.FREQ.MEASURE.CUR — no SEX) INDICATOR_EAR_GENDER_GAP_OCC = "EAR_GGAP_OCU_RT" # Gender wage gap by occupation (verified existing) INDICATOR_EAR_LOW_PAY = "EAR_XTLP_SEX_RT" # Low pay incidence by sex (verified existing) INDICATOR_EAR_SDG_HOURLY = "SDG_0851_SEX_OCU_NB" # SDG 8.5.1 average hourly earnings # Labour Income / Productivity INDICATOR_LAP_INCOME_SHARE = "LAP_2GDP_NOC_RT" # Labour income share (% of GDP, modelled) INDICATOR_LAP_INCOME_DIST = "LAP_2LID_QTL_RT" # Income distribution by decile INDICATOR_LAP_GENDER_INCOME_GAP = "LAP_2FTM_NOC_RT" # Gender income gap (women-to-men ratio) # Hours of Work INDICATOR_HOW_MEAN_WEEKLY_SEX = "HOW_TEMP_SEX_ECO_NB" # Mean weekly hours by sex & economic activity INDICATOR_HOW_EXCESSIVE_48H = "HOW_XEES_SEX_ECO_RT" # Share working > 48h/week # SDG Labour Market Indicators INDICATOR_SDG_WORKING_POVERTY = "SDG_0111_SEX_AGE_RT" # SDG 1.1.1 working poverty rate (%) INDICATOR_SDG_SOCIAL_PROTECTION = "SDG_0131_SEX_SOC_RT" # SDG 1.3.1 social protection coverage INDICATOR_SDG_LABOUR_INCOME_SHARE = "SDG_1041_NOC_RT" # SDG 10.4.1 labour income share # Exchange rates (for currency conversion context) INDICATOR_CCF_EXCHANGE_RATES = "CCF_XOXR_CUR_RT" # Official exchange rates (LCU per USD) INDICATOR_CCF_PPP = "CCF_XPPP_CUR_RT" # PPP conversion factors # --------------------------------------------------------------------------- # Frequency codes # --------------------------------------------------------------------------- FREQ_ANNUAL = "A" FREQ_QUARTERLY = "Q" FREQ_MONTHLY = "M" # --------------------------------------------------------------------------- # Common ISO-2 country code groups # --------------------------------------------------------------------------- G7_COUNTRIES = "CAN+USA+GBR+DEU+FRA+ITA+JPN" G20_COUNTRIES = "CAN+USA+GBR+DEU+FRA+ITA+JPN+AUS+BRA+CHN+IND+IDN+MEX+RUS+SAU+ZAF+KOR+TUR+ARG+EUN" EU_COUNTRIES = "AUT+BEL+BGR+HRV+CYP+CZE+DNK+EST+FIN+FRA+DEU+GRC+HUN+IRL+ITA+LVA+LTU+LUX+MLT+NLD+POL+PRT+ROU+SVK+SVN+ESP+SWE" # --------------------------------------------------------------------------- # Helper utilities # --------------------------------------------------------------------------- def _build_dataflow_id(indicator_code: str) -> str: """Build the SDMX dataflow ID from a plain indicator code.""" if indicator_code.startswith("DF_"): return indicator_code return f"DF_{indicator_code}" def _session() -> requests.Session: """Return a pre-configured requests Session.""" s = requests.Session() s.headers.update({ "User-Agent": "Fincept-Terminal/4.0.2 (ILOSTAT-wrapper)", "Accept-Language": "en", }) return s def _parse_csv_response(text: str) -> List[Dict[str, Any]]: """ Parse a CSV text body into a list of dicts. Uses the stdlib csv module to avoid requiring pandas. """ import csv reader = csv.DictReader(io.StringIO(text)) rows = [] for row in reader: cleaned = {} for k, v in row.items(): k = k.strip().strip('"') v = v.strip() # Try numeric conversion try: cleaned[k] = float(v) if "." in v else int(v) except (ValueError, TypeError): cleaned[k] = v if v != "" else None rows.append(cleaned) return rows def _safe_float(val: Any) -> Optional[float]: try: return float(val) except (TypeError, ValueError): return None # --------------------------------------------------------------------------- # Core SDMX REST query builder # --------------------------------------------------------------------------- class ILOStatError: """Structured error container for host JSON consumption.""" def __init__(self, endpoint: str, error: str, status_code: Optional[int] = None): self.endpoint = endpoint self.error = error self.status_code = status_code self.timestamp = int(datetime.now().timestamp()) def to_dict(self) -> Dict[str, Any]: return { "endpoint": self.endpoint, "error": self.error, "status_code": self.status_code, "timestamp": self.timestamp, "type": "ILOStatError", } class ILOStatWrapper: """ Complete Python wrapper for the ILOSTAT SDMX REST API and Bulk Download Facility. SDMX REST API base URL: https://sdmx.ilo.org/rest Agency ID: ILO (always) Dataflow pattern: ILO,DF_[,] Supported resource types: data — actual observations dataflow — list / describe dataflows (indicators) datastructure — DSD (dimensions, attributes, measures) codelist — code lists (e.g. CL_AREA, CL_SEX) conceptscheme — concept schemes categoryscheme — category schemes categorisation — categorisations Data URL format: {base}/data/{agency},{flow}[,{version}]/{key} ?startPeriod=YYYY[-MM[-DD]] &endPeriod=YYYY[-MM[-DD]] &detail=dataonly|serieskeysonly|full &updatedAfter=YYYY-MM-DDThh:mm:ss &firstNObservations=N &lastNObservations=N &dimensionAtObservation=AllDimensions|TIME_PERIOD Accept: text/csv → returns SDMX-CSV Accept: application/json → returns SDMX-JSON (complex nested structure) Key format (dot-separated dimension values, in DSD-defined order): FREQ.REF_AREA.MEASURE.SEX.CLASSIF1[.CLASSIF2] Omit a dimension to wildcard (consecutive dots mean wildcard). Use + for OR: CAN+USA+GBR Use ALL to wildcard every dimension. Example calls: # Canada monthly unemployment rate, all sexes, adults 15+ GET https://sdmx.ilo.org/rest/data/ILO,DF_UNE_DEAP_SEX_AGE_RT,1.0/CAN.M.UNE_DEAP_RT.SEX_T.AGE_YTHADULT_YGE15 ?startPeriod=2010&format=csv # All countries, annual employment by sex & age GET https://sdmx.ilo.org/rest/data/ILO,DF_EMP_TEMP_SEX_AGE_NB/ALL ?startPeriod=2000&endPeriod=2023&format=csv Bulk Download: Indicator CSV: https://www.ilo.org/ilostat-files/WEB_bulk_download/indicator/{INDICATOR_CODE}.csv.gz TOC: https://www.ilo.org/ilostat-files/WEB_bulk_download/indicator/table_of_contents_en.csv """ def __init__(self): self.sdmx_base = SDMX_BASE_URL self.bulk_base = BULK_BASE_URL self.session = _session() # ------------------------------------------------------------------ # Internal request helpers # ------------------------------------------------------------------ def _get_csv(self, url: str, params: Optional[Dict] = None) -> str: """Perform a GET request expecting CSV; return raw text.""" headers = {"Accept": "text/csv"} resp = self.session.get(url, params=params, headers=headers, timeout=DEFAULT_TIMEOUT) resp.raise_for_status() return resp.text def _get_json(self, url: str, params: Optional[Dict] = None) -> Dict[str, Any]: """Perform a GET request expecting JSON.""" headers = {"Accept": "application/json"} resp = self.session.get(url, params=params, headers=headers, timeout=DEFAULT_TIMEOUT) resp.raise_for_status() return resp.json() def _get_xml(self, url: str, params: Optional[Dict] = None) -> str: """Perform a GET request expecting XML text.""" headers = {"Accept": "application/xml"} resp = self.session.get(url, params=params, headers=headers, timeout=DEFAULT_TIMEOUT) resp.raise_for_status() return resp.text # ------------------------------------------------------------------ # Structural / metadata endpoints # ------------------------------------------------------------------ def list_dataflows(self, topic_prefix: Optional[str] = None) -> Dict[str, Any]: """ Retrieve all available ILOSTAT dataflows (indicators). Calls: GET {base}/dataflow/ILO Returns a list of dataflow objects parsed from the XML response. Args: topic_prefix: Optional filter, e.g. "EMP", "UNE", "EAR", "HOW", "WAP", "LAP" If supplied only matching dataflows are returned. Returns dict: { "success": True, "data": [{"id": "DF_EMP_TEMP_SEX_AGE_NB", "name": "...", "agency": "ILO"}, ...], "count": N, "parameters": {"topic_prefix": ...} } """ try: url = f"{self.sdmx_base}/dataflow/ILO" # Fetch as XML because the JSON format for structure queries is unreliable xml_text = self._get_xml(url) # Parse minimal dataflow information from the XML without lxml dependency import re # Match Dataflow elements and extract id and name attributes / child Name elements dataflows = [] # Pattern to extract dataflow blocks df_blocks = re.findall( r'<(?:str:|structure:)?Dataflow\b([^>]*)>(.*?)', xml_text, re.DOTALL | re.IGNORECASE, ) if not df_blocks: # Simpler attribute-only match (self-closing or with children) id_matches = re.findall( r'<(?:str:|structure:)?Dataflow\b[^>]*\bid=["\']([^"\']+)["\'][^>]*>', xml_text, re.IGNORECASE, ) for df_id in id_matches: dataflows.append({"id": df_id, "agency": "ILO"}) else: for attrs_str, body in df_blocks: df_id_m = re.search(r'\bid=["\']([^"\']+)["\']', attrs_str) name_m = re.search(r'<(?:com:|common:)?Name[^>]*>([^<]+)', body, re.IGNORECASE) df_id = df_id_m.group(1) if df_id_m else "unknown" df_name = name_m.group(1).strip() if name_m else df_id dataflows.append({"id": df_id, "name": df_name, "agency": "ILO"}) # Apply topic prefix filter if topic_prefix: prefix_upper = topic_prefix.upper() dataflows = [d for d in dataflows if prefix_upper in d.get("id", "")] return { "success": True, "data": dataflows, "count": len(dataflows), "parameters": {"topic_prefix": topic_prefix}, } except requests.exceptions.HTTPError as e: return {"error": ILOStatError("list_dataflows", str(e), e.response.status_code).to_dict()} except Exception as e: return {"error": ILOStatError("list_dataflows", str(e)).to_dict()} def get_codelist(self, codelist_id: str, agency: str = "ILO") -> Dict[str, Any]: """ Retrieve a specific codelist by ID. Calls: GET {base}/codelist/{agency}/{codelist_id} Common codelist IDs: CL_AREA — ISO country / region codes used by ILO CL_SEX — Sex disaggregation codes (SEX_T, SEX_M, SEX_F) CL_FREQ — Frequency codes (A, Q, M) CL_ECO — Economic activity classification (ISIC) CL_AGE — Age group classification CL_OCU — Occupation classification (ISCO) Returns dict with list of code entries. """ try: url = f"{self.sdmx_base}/codelist/{agency}/{codelist_id}" xml_text = self._get_xml(url) import re # Extract Code elements codes = [] code_blocks = re.findall( r'<(?:str:|structure:)?Code\b([^>]*)>(.*?)', xml_text, re.DOTALL | re.IGNORECASE, ) for attrs_str, body in code_blocks: code_id_m = re.search(r'\bid=["\']([^"\']+)["\']', attrs_str) name_m = re.search(r'<(?:com:|common:)?Name[^>]*>([^<]+)', body, re.IGNORECASE) code_id = code_id_m.group(1) if code_id_m else "unknown" code_name = name_m.group(1).strip() if name_m else code_id codes.append({"id": code_id, "label": code_name}) return { "success": True, "codelist_id": codelist_id, "agency": agency, "data": codes, "count": len(codes), } except requests.exceptions.HTTPError as e: return {"error": ILOStatError("get_codelist", str(e), e.response.status_code).to_dict()} except Exception as e: return {"error": ILOStatError("get_codelist", str(e)).to_dict()} def get_data_structure(self, dsd_id: str) -> Dict[str, Any]: """ Retrieve the Data Structure Definition (DSD) for a given indicator. Calls: GET {base}/datastructure/ILO/{dsd_id} The DSD describes all dimensions, their order, and the codelists they reference. The dsd_id is the same as the indicator code (without the DF_ prefix). Example: dsd_id = "EMP_TEMP_SEX_AGE_NB" """ try: url = f"{self.sdmx_base}/datastructure/ILO/{dsd_id}" xml_text = self._get_xml(url) return { "success": True, "dsd_id": dsd_id, "raw_xml": xml_text, } except requests.exceptions.HTTPError as e: return {"error": ILOStatError("get_data_structure", str(e), e.response.status_code).to_dict()} except Exception as e: return {"error": ILOStatError("get_data_structure", str(e)).to_dict()} # ------------------------------------------------------------------ # Table of Contents (bulk download) # ------------------------------------------------------------------ def get_table_of_contents( self, segment: str = "indicator", language: str = "en", search: Optional[str] = None, ) -> Dict[str, Any]: """ Download and parse the ILOSTAT Table of Contents CSV. This is the definitive catalogue of ~500 indicator datasets. Each row contains the dataset id, frequency, time range, last update, and file size. Args: segment: "indicator" (default) or "ref_area" language: "en" (default), "fr", or "es" search: Optional case-insensitive substring to filter indicator rows. TOC URL: https://rplumber.ilo.org/metadata/toc/{segment} (CSV response; the old www.ilo.org bulk-download CSV URLs are no longer publicly accessible) Returns dict: { "success": True, "data": [{"id": "EMP_TEMP_SEX_AGE_NB_A", "indicator": "...", ...}, ...], "count": N } """ try: # rplumber.ilo.org returns CSV directly for both segments # The language parameter is not supported by this endpoint (English only) url = f"{TOC_BASE_URL}/{segment}" text = self._get_csv(url) rows = _parse_csv_response(text) if search: search_lower = search.lower() rows = [ r for r in rows if any(search_lower in str(v).lower() for v in r.values()) ] return { "success": True, "data": rows, "count": len(rows), "parameters": {"segment": segment, "language": language, "search": search}, } except requests.exceptions.HTTPError as e: return {"error": ILOStatError("get_table_of_contents", str(e), e.response.status_code).to_dict()} except Exception as e: return {"error": ILOStatError("get_table_of_contents", str(e)).to_dict()} # ------------------------------------------------------------------ # Data retrieval — SDMX REST API # ------------------------------------------------------------------ def get_data( self, indicator_code: str, key: str = "ALL", start_period: Optional[str] = None, end_period: Optional[str] = None, detail: str = "dataonly", last_n_obs: Optional[int] = None, first_n_obs: Optional[int] = None, version: str = "1.0", ) -> Dict[str, Any]: """ Core data query against the ILOSTAT SDMX REST API. Calls: GET {base}/data/ILO,DF_{indicator_code},{version}/{key} ?startPeriod=...&endPeriod=...&detail=... Args: indicator_code: The indicator/DSD code without the DF_ prefix. E.g. "UNE_DEAP_SEX_AGE_RT" or "EMP_TEMP_SEX_AGE_NB" key: Dot-separated dimension key. "ALL" wildcards everything. Format: FREQ.REF_AREA.MEASURE.SEX.CLASSIF1[.CLASSIF2] Example: "A.DEU.UNE_DEAP_RT.SEX_T.AGE_YTHADULT_YGE15" Use + for OR: "CAN+USA+GBR.A..." start_period: Start year/date in ISO format (e.g. "2010" or "2010-01"). end_period: End year/date in ISO format. detail: Level of detail: "dataonly" — observations only (fastest) "full" — observations + all attributes "serieskeysonly" — no observations, just dimension keys "nodata" — structure only, no obs values last_n_obs: Return only the last N observations per series. first_n_obs: Return only the first N observations per series. version: Dataflow version (default "1.0"). Returns: { "success": True, "indicator": "UNE_DEAP_SEX_AGE_RT", "dataflow": "ILO,DF_UNE_DEAP_SEX_AGE_RT,1.0", "key": "ALL", "data": [ { "FREQ": "A", "REF_AREA": "USA", "MEASURE": "UNE_DEAP_RT", "SEX": "SEX_T", "AGE": "AGE_YTHADULT_YGE15", "TIME_PERIOD": "2022", "OBS_VALUE": 3.6 }, ... ], "count": N, "parameters": {...} } """ try: # Build the dataflow reference df_id = _build_dataflow_id(indicator_code) flow_ref = f"ILO,{df_id},{version}" url = f"{self.sdmx_base}/data/{flow_ref}/{key}" params: Dict[str, Any] = {"detail": detail} if start_period: params["startPeriod"] = start_period if end_period: params["endPeriod"] = end_period if last_n_obs is not None: params["lastNObservations"] = last_n_obs if first_n_obs is not None: params["firstNObservations"] = first_n_obs csv_text = self._get_csv(url, params=params) rows = _parse_csv_response(csv_text) # Coerce OBS_VALUE to float where possible for row in rows: if "OBS_VALUE" in row and row["OBS_VALUE"] is not None: row["OBS_VALUE"] = _safe_float(row["OBS_VALUE"]) return { "success": True, "indicator": indicator_code, "dataflow": flow_ref, "key": key, "data": rows, "count": len(rows), "parameters": { "start_period": start_period, "end_period": end_period, "detail": detail, "last_n_obs": last_n_obs, "first_n_obs": first_n_obs, }, } except requests.exceptions.HTTPError as e: sc = e.response.status_code if e.response is not None else None msg = str(e) if sc == 413: msg = ( "HTTP 413 Payload Too Large: query returned too many results. " "Narrow the key (add country, frequency, or classification filters) " "or use get_bulk_data() for full datasets." ) return {"error": ILOStatError("get_data", msg, sc).to_dict()} except Exception as e: return {"error": ILOStatError("get_data", str(e)).to_dict()} # ------------------------------------------------------------------ # High-level, domain-specific convenience methods # ------------------------------------------------------------------ def get_unemployment( self, countries: str = "ALL", frequency: str = FREQ_ANNUAL, sex: str = "SEX_T", age_group: str = "AGE_YTHADULT_YGE15", start_period: Optional[str] = None, end_period: Optional[str] = None, ) -> Dict[str, Any]: """ Fetch unemployment rate data. Indicator: DF_UNE_DEAP_SEX_AGE_RT (ILO modelled estimates — unemployment rate) Dataflow: https://sdmx.ilo.org/rest/data/ILO,DF_UNE_DEAP_SEX_AGE_RT,1.0/{key} Dimension key order: REF_AREA . FREQ . MEASURE . SEX . AGE Args: countries: ISO-2 country code(s). Use + for multiple: "USA+DEU+FRA" Use "ALL" to get all countries (may be slow / 413). frequency: "A" (annual), "Q" (quarterly), "M" (monthly) sex: "SEX_T" (total), "SEX_M" (male), "SEX_F" (female) age_group: Common values: "AGE_YTHADULT_YGE15" — 15 and over (standard) "AGE_YTHADULT_Y15-24" — youth 15-24 "AGE_YTHADULT_YGE25" — adult 25 and over start_period: e.g. "2000" end_period: e.g. "2023" Example URL: https://sdmx.ilo.org/rest/data/ILO,DF_UNE_DEAP_SEX_AGE_RT,1.0/ USA.A.UNE_DEAP_RT.SEX_T.AGE_YTHADULT_YGE15?startPeriod=2010 Returns standard data dict. """ # Key: REF_AREA.FREQ.MEASURE.SEX.AGE measure = "UNE_DEAP_RT" key = f"{countries}.{frequency}.{measure}.{sex}.{age_group}" result = self.get_data( indicator_code = "UNE_DEAP_SEX_AGE_RT", key = key, start_period = start_period, end_period = end_period, ) result["topic"] = "unemployment_rate" return result def get_employment( self, countries: str = "ALL", frequency: str = FREQ_ANNUAL, sex: str = "SEX_T", age_group: str = "_T", start_period: Optional[str] = None, end_period: Optional[str] = None, ) -> Dict[str, Any]: """ Fetch total employment data by sex and age. Indicator: DF_EMP_TEMP_SEX_AGE_NB (employment by sex and age, number) Dataflow: https://sdmx.ilo.org/rest/data/ILO,DF_EMP_TEMP_SEX_AGE_NB,1.0/{key} Dimension key order: REF_AREA.FREQ.MEASURE.SEX.AGE Common age group codes: "_T" — Total (all ages) "AGE_YTHADULT_YGE15" — 15 and over "AGE_YTHADULT_Y15-24" — Youth 15-24 "AGE_5YRBANDS_YGE65" — 65 and over """ measure = "EMP_TEMP_NB" key = f"{countries}.{frequency}.{measure}.{sex}.{age_group}" result = self.get_data( indicator_code = "EMP_TEMP_SEX_AGE_NB", key = key, start_period = start_period, end_period = end_period, ) result["topic"] = "employment_total" return result def get_employment_to_population_ratio( self, countries: str = "ALL", frequency: str = FREQ_ANNUAL, sex: str = "SEX_T", age_group: str = "AGE_YTHADULT_YGE15", start_period: Optional[str] = None, end_period: Optional[str] = None, ) -> Dict[str, Any]: """ Fetch employment-to-population ratio. Indicator: DF_EMP_DWAP_SEX_AGE_RT """ measure = "EMP_DWAP_RT" key = f"{countries}.{frequency}.{measure}.{sex}.{age_group}" result = self.get_data( indicator_code = "EMP_DWAP_SEX_AGE_RT", key = key, start_period = start_period, end_period = end_period, ) result["topic"] = "employment_to_population_ratio" return result def get_labour_force_participation( self, countries: str = "ALL", frequency: str = FREQ_ANNUAL, sex: str = "SEX_T", age_group: str = "AGE_YTHADULT_YGE15", start_period: Optional[str] = None, end_period: Optional[str] = None, ) -> Dict[str, Any]: """ Fetch labour force participation rate. Indicator: DF_EAP_DWAP_SEX_AGE_RT (labour force participation rate) """ measure = "EAP_DWAP_RT" key = f"{countries}.{frequency}.{measure}.{sex}.{age_group}" result = self.get_data( indicator_code = "EAP_DWAP_SEX_AGE_RT", key = key, start_period = start_period, end_period = end_period, ) result["topic"] = "labour_force_participation_rate" return result def get_wages( self, countries: str = "ALL", frequency: str = FREQ_ANNUAL, wage_type: str = "monthly", sex: str = "SEX_T", currency: str = "CUR_TYPE_LCU", start_period: Optional[str] = None, end_period: Optional[str] = None, ) -> Dict[str, Any]: """ Fetch mean earnings data (hourly or monthly). Verified dataflow IDs (from the live SDMX /dataflow/ILO endpoint): hourly → DF_EAR_4HRL_SEX_CUR_NB DSD dims: REF_AREA.FREQ.MEASURE.SEX.CUR Measure: EAR_4HRL_NB monthly → DF_EAR_4MTH_SEX_CUR_NB DSD dims: REF_AREA.FREQ.MEASURE.SEX.CUR Measure: EAR_4MTH_NB minimum → DF_EAR_4MMN_CUR_NB (statutory minimum wage, no sex dimension) DSD dims: REF_AREA.FREQ.MEASURE.CUR Measure: EAR_4MMN_NB Args: wage_type: "hourly" | "monthly" (default) | "minimum" currency: CL_CUR codelist value: "CUR_TYPE_LCU" — Local currency units [default] "CUR_TYPE_USD" — US Dollars "CUR_TYPE_EUR" — Euros (where applicable) "CUR_TYPE_PPP" — PPP-adjusted international dollars Example (Germany monthly wages in LCU): https://sdmx.ilo.org/rest/data/ILO,DF_EAR_4MTH_SEX_CUR_NB,1.0/ DEU.A.EAR_4MTH_NB.SEX_T.CUR_TYPE_LCU?startPeriod=2010 """ if wage_type == "hourly": indicator_code = "EAR_4HRL_SEX_CUR_NB" measure = "EAR_4HRL_NB" key = f"{countries}.{frequency}.{measure}.{sex}.{currency}" elif wage_type == "minimum": indicator_code = "EAR_4MMN_CUR_NB" measure = "EAR_4MMN_NB" # Minimum wage DSD has no SEX dimension: REF_AREA.FREQ.MEASURE.CUR key = f"{countries}.{frequency}.{measure}.{currency}" else: # monthly (default) indicator_code = "EAR_4MTH_SEX_CUR_NB" measure = "EAR_4MTH_NB" key = f"{countries}.{frequency}.{measure}.{sex}.{currency}" result = self.get_data( indicator_code = indicator_code, key = key, start_period = start_period, end_period = end_period, ) result["topic"] = f"wages_{wage_type}" return result def get_gender_wage_gap( self, countries: str = "ALL", frequency: str = FREQ_ANNUAL, occupation: str = "OCU_ISCO08_TOTAL", start_period: Optional[str] = None, end_period: Optional[str] = None, ) -> Dict[str, Any]: """ Fetch gender wage gap by occupation. Indicator: DF_EAR_GGAP_OCU_RT DSD dimension order (verified): REF_AREA . FREQ . MEASURE . OCU Note: This dataflow has NO SEX dimension — it is inherently a gender gap measure. Args: occupation: OCU codelist code (same CL_OCU as employment by occupation). "OCU_ISCO08_TOTAL" — Total all occupations [default] "" (empty string) — wildcard to get all occupation breakdowns Example: https://sdmx.ilo.org/rest/data/ILO,DF_EAR_GGAP_OCU_RT,1.0/ GBR.A.EAR_GGAP_RT.OCU_ISCO08_TOTAL?startPeriod=2015 """ measure = "EAR_GGAP_RT" if occupation: key = f"{countries}.{frequency}.{measure}.{occupation}" else: key = f"{countries}.{frequency}.{measure}." result = self.get_data( indicator_code = "EAR_GGAP_OCU_RT", key = key, start_period = start_period, end_period = end_period, ) result["topic"] = "gender_wage_gap" return result def get_hours_of_work( self, countries: str = "ALL", frequency: str = FREQ_ANNUAL, sex: str = "SEX_T", economic_act: str = "ECO_ISIC4_TOTAL", start_period: Optional[str] = None, end_period: Optional[str] = None, ) -> Dict[str, Any]: """ Fetch mean weekly hours of work. Indicator: DF_HOW_TEMP_SEX_ECO_NB (mean weekly hours by sex & economic activity) DSD dimension order: REF_AREA . FREQ . MEASURE . SEX . ECO Common ECO codes (same CL_ECO codelist as employment by sector): "ECO_ISIC4_TOTAL" — Total (all sectors) [default] "ECO_ISIC4_A" — Agriculture, forestry and fishing "ECO_ISIC4_C" — Manufacturing "ECO_ISIC4_F" — Construction "ECO_ISIC4_G" — Wholesale and retail trade "ECO_ISIC4_K" — Financial and insurance activities "ECO_ISIC4_O" — Public administration and defence "ECO_ISIC4_P" — Education "ECO_ISIC4_Q" — Human health and social work Pass economic_act="" to wildcard (all sector breakdowns). """ measure = "HOW_TEMP_NB" if economic_act: key = f"{countries}.{frequency}.{measure}.{sex}.{economic_act}" else: key = f"{countries}.{frequency}.{measure}.{sex}." result = self.get_data( indicator_code = "HOW_TEMP_SEX_ECO_NB", key = key, start_period = start_period, end_period = end_period, ) result["topic"] = "hours_of_work_mean_weekly" return result def get_labour_income_share( self, countries: str = "ALL", frequency: str = FREQ_ANNUAL, start_period: Optional[str] = None, end_period: Optional[str] = None, ) -> Dict[str, Any]: """ Fetch labour income share as % of GDP (ILO modelled estimates). Indicator: DF_LAP_2GDP_NOC_RT SDG 10.4.1 proxy indicator. """ measure = "LAP_2GDP_RT" key = f"{countries}.{frequency}.{measure}" result = self.get_data( indicator_code = "LAP_2GDP_NOC_RT", key = key, start_period = start_period, end_period = end_period, ) result["topic"] = "labour_income_share" return result def get_working_poverty( self, countries: str = "ALL", frequency: str = FREQ_ANNUAL, sex: str = "SEX_T", age_group: str = "AGE_YTHADULT_YGE15", start_period: Optional[str] = None, end_period: Optional[str] = None, ) -> Dict[str, Any]: """ Fetch working poverty rate (SDG 1.1.1). Indicator: DF_SDG_0111_SEX_AGE_RT DSD dimension order (verified): REF_AREA . FREQ . MEASURE . SEX . AGE Working poverty: employed persons living below US$3.65/day (2017 PPP). Args: age_group: AGE codelist code. "AGE_YTHADULT_YGE15" — 15 and over [default] "" (empty string) — wildcard all age groups Example: https://sdmx.ilo.org/rest/data/ILO,DF_SDG_0111_SEX_AGE_RT,1.0/ IND.A.SDG_0111_RT.SEX_T.AGE_YTHADULT_YGE15?startPeriod=2010 """ measure = "SDG_0111_RT" if age_group: key = f"{countries}.{frequency}.{measure}.{sex}.{age_group}" else: key = f"{countries}.{frequency}.{measure}.{sex}." result = self.get_data( indicator_code = "SDG_0111_SEX_AGE_RT", key = key, start_period = start_period, end_period = end_period, ) result["topic"] = "working_poverty_rate" return result def get_employment_by_sector( self, countries: str = "ALL", frequency: str = FREQ_ANNUAL, sex: str = "SEX_T", sector: str = "ECO_ISIC4_TOTAL", start_period: Optional[str] = None, end_period: Optional[str] = None, ) -> Dict[str, Any]: """ Fetch employment broken down by economic sector (ISIC Rev.4). Indicator: DF_EMP_TEMP_SEX_ECO_NB (employment by sex and economic activity) DSD dimension order (verified): REF_AREA . FREQ . MEASURE . SEX . ECO Common ECO sector codes (ILO CL_ECO codelist, ISIC Rev.4): "ECO_ISIC4_TOTAL" — Total (all sectors) [default] "ECO_ISIC4_A" — Agriculture, forestry and fishing "ECO_ISIC4_B" — Mining and quarrying "ECO_ISIC4_C" — Manufacturing "ECO_ISIC4_D" — Electricity, gas, steam and air conditioning supply "ECO_ISIC4_E" — Water supply, sewerage, waste management "ECO_ISIC4_F" — Construction "ECO_ISIC4_G" — Wholesale and retail trade; repair of motor vehicles "ECO_ISIC4_H" — Transportation and storage "ECO_ISIC4_I" — Accommodation and food service activities "ECO_ISIC4_J" — Information and communication "ECO_ISIC4_K" — Financial and insurance activities "ECO_ISIC4_L" — Real estate activities "ECO_ISIC4_M" — Professional, scientific and technical activities "ECO_ISIC4_N" — Administrative and support service activities "ECO_ISIC4_O" — Public administration and defence "ECO_ISIC4_P" — Education "ECO_ISIC4_Q" — Human health and social work activities "ECO_ISIC4_R" — Arts, entertainment and recreation "ECO_ISIC4_S" — Other service activities "ECO_ISIC4_T" — Activities of households as employers "ECO_ISIC4_U" — Activities of extraterritorial organizations Trailing dot wildcard (all sectors): pass sector="" to get all sector breakdowns. """ measure = "EMP_TEMP_NB" # Allow trailing wildcard: if sector is empty, omit it (trailing dot wildcards last dim) if sector: key = f"{countries}.{frequency}.{measure}.{sex}.{sector}" else: key = f"{countries}.{frequency}.{measure}.{sex}." result = self.get_data( indicator_code = "EMP_TEMP_SEX_ECO_NB", key = key, start_period = start_period, end_period = end_period, ) result["topic"] = "employment_by_sector" return result def get_employment_by_occupation( self, countries: str = "ALL", frequency: str = FREQ_ANNUAL, sex: str = "SEX_T", occupation: str = "OCU_ISCO08_TOTAL", start_period: Optional[str] = None, end_period: Optional[str] = None, ) -> Dict[str, Any]: """ Fetch employment by occupation (ISCO-08 1-digit). Indicator: DF_EMP_TEMP_SEX_OCU_NB DSD dimension order: REF_AREA . FREQ . MEASURE . SEX . OCU Common occupation codes (ILO CL_OCU codelist, ISCO-08): "OCU_ISCO08_TOTAL" — Total all occupations [default] "OCU_ISCO08_1" — Managers "OCU_ISCO08_2" — Professionals "OCU_ISCO08_3" — Technicians and associate professionals "OCU_ISCO08_4" — Clerical support workers "OCU_ISCO08_5" — Service and sales workers "OCU_ISCO08_6" — Skilled agricultural, forestry and fishery workers "OCU_ISCO08_7" — Craft and related trades workers "OCU_ISCO08_8" — Plant and machine operators, and assemblers "OCU_ISCO08_9" — Elementary occupations "OCU_ISCO08_0" — Armed forces occupations Pass occupation="" to wildcard (all occupation breakdowns). """ measure = "EMP_TEMP_NB" if occupation: key = f"{countries}.{frequency}.{measure}.{sex}.{occupation}" else: key = f"{countries}.{frequency}.{measure}.{sex}." result = self.get_data( indicator_code = "EMP_TEMP_SEX_OCU_NB", key = key, start_period = start_period, end_period = end_period, ) result["topic"] = "employment_by_occupation" return result def get_employment_by_status( self, countries: str = "ALL", frequency: str = FREQ_ANNUAL, sex: str = "SEX_T", status: str = "STE_ICSE93_TOTAL", start_period: Optional[str] = None, end_period: Optional[str] = None, ) -> Dict[str, Any]: """ Fetch employment by status in employment (ICSE-93 / ICSE-18). Indicator: DF_EMP_TEMP_SEX_STE_NB DSD dimension order: REF_AREA . FREQ . MEASURE . SEX . STE Common status codes (ILO CL_STE codelist, ICSE-93): "STE_ICSE93_TOTAL" — Total [default] "STE_ICSE93_1" — Employees "STE_ICSE93_2" — Employers "STE_ICSE93_3" — Own-account workers "STE_ICSE93_4" — Members of producers cooperatives "STE_ICSE93_5" — Contributing family workers "STE_ICSE93_6" — Workers not classifiable by status Pass status="" to wildcard (all status breakdowns). """ measure = "EMP_TEMP_NB" if status: key = f"{countries}.{frequency}.{measure}.{sex}.{status}" else: key = f"{countries}.{frequency}.{measure}.{sex}." result = self.get_data( indicator_code = "EMP_TEMP_SEX_STE_NB", key = key, start_period = start_period, end_period = end_period, ) result["topic"] = "employment_by_status_in_employment" return result def get_informal_employment( self, countries: str = "ALL", frequency: str = FREQ_ANNUAL, sex: str = "SEX_T", start_period: Optional[str] = None, end_period: Optional[str] = None, ) -> Dict[str, Any]: """ Fetch informal employment rate. Indicator: DF_EMP_2EMP_SEX_STE_RT (share of informal employment by sex and status) """ measure = "EMP_2EMP_RT" key = f"{countries}.{frequency}.{measure}.{sex}._T" result = self.get_data( indicator_code = "EMP_2EMP_SEX_STE_RT", key = key, start_period = start_period, end_period = end_period, ) result["topic"] = "informal_employment" return result def get_social_protection_coverage( self, countries: str = "ALL", frequency: str = FREQ_ANNUAL, sex: str = "SEX_T", start_period: Optional[str] = None, end_period: Optional[str] = None, ) -> Dict[str, Any]: """ Fetch social protection coverage (SDG 1.3.1). Indicator: DF_SDG_0131_SEX_SOC_RT """ measure = "SDG_0131_RT" key = f"{countries}.{frequency}.{measure}.{sex}._T" result = self.get_data( indicator_code = "SDG_0131_SEX_SOC_RT", key = key, start_period = start_period, end_period = end_period, ) result["topic"] = "social_protection_coverage" return result def get_country_profile( self, country: str, start_period: Optional[str] = None, end_period: Optional[str] = None, ) -> Dict[str, Any]: """ Fetch a comprehensive labour market profile for a single country. Runs multiple queries and bundles results into one response. Each sub-query falls back gracefully on failure. Args: country: ISO-2 country code, e.g. "DEU", "IND", "BRA" start_period: e.g. "2010" end_period: e.g. "2023" Returns: { "success": True, "country": "DEU", "data": { "unemployment_rate": {...}, "employment_to_pop": {...}, "labour_force_participation": {...}, "hours_of_work": {...}, "wages_monthly": {...}, "labour_income_share": {...}, }, "parameters": {...} } """ try: profile: Dict[str, Any] = {} # Unemployment rate try: profile["unemployment_rate"] = self.get_unemployment( countries=country, start_period=start_period, end_period=end_period ) except Exception as exc: profile["unemployment_rate"] = {"error": str(exc)} # Employment-to-population ratio try: profile["employment_to_pop"] = self.get_employment_to_population_ratio( countries=country, start_period=start_period, end_period=end_period ) except Exception as exc: profile["employment_to_pop"] = {"error": str(exc)} # Labour force participation rate try: profile["labour_force_participation"] = self.get_labour_force_participation( countries=country, start_period=start_period, end_period=end_period ) except Exception as exc: profile["labour_force_participation"] = {"error": str(exc)} # Mean weekly hours of work try: profile["hours_of_work"] = self.get_hours_of_work( countries=country, start_period=start_period, end_period=end_period ) except Exception as exc: profile["hours_of_work"] = {"error": str(exc)} # Monthly wages try: profile["wages_monthly"] = self.get_wages( countries=country, wage_type="monthly", start_period=start_period, end_period=end_period ) except Exception as exc: profile["wages_monthly"] = {"error": str(exc)} # Labour income share try: profile["labour_income_share"] = self.get_labour_income_share( countries=country, start_period=start_period, end_period=end_period ) except Exception as exc: profile["labour_income_share"] = {"error": str(exc)} return { "success": True, "country": country, "data": profile, "parameters": { "country": country, "start_period": start_period, "end_period": end_period, }, } except Exception as e: return {"error": ILOStatError("get_country_profile", str(e)).to_dict()} def get_sdg_indicator( self, sdg_code: str, countries: str = "ALL", frequency: str = FREQ_ANNUAL, start_period: Optional[str] = None, end_period: Optional[str] = None, ) -> Dict[str, Any]: """ Fetch a specific SDG labour market indicator. Common SDG codes available in ILOSTAT: "SDG_0111_SEX_AGE_RT" — 1.1.1 Working poverty rate "SDG_0131_SEX_SOC_RT" — 1.3.1 Social protection coverage "SDG_0551_NOC_RT" — 5.5.1 Women in managerial positions "SDG_0552_NOC_RT" — 5.5.2 Women in senior and middle management "SDG_0811_SEX_AGE_RT" — 8.1.1 Annual growth rate of GDP per employed person "SDG_0851_SEX_OCU_NB" — 8.5.1 Average hourly earnings "SDG_0852_SEX_AGE_RT" — 8.5.2 Unemployment rate "SDG_0861_SEX_AGE_NB" — 8.6.1 Youth not in education, employment or training (NEET) "SDG_0871_SEX_AGE_RT" — 8.7.1 Child labour "SDG_0881_NOC_RT" — 8.8.1 Fatal occupational injuries "SDG_0882_NOC_RT" — 8.8.2 Non-fatal occupational injuries "SDG_1041_NOC_RT" — 10.4.1 Labour income share (% of GDP) Args: sdg_code: The full indicator code, e.g. "SDG_0852_SEX_AGE_RT" countries: ISO-2 country code(s) or "ALL" frequency: "A", "Q", or "M" Returns standard data dict. """ # Build a minimal key — the exact key dimensions depend on the specific DSD. # Using ALL key is safest for discovery; narrow down as needed. result = self.get_data( indicator_code = sdg_code, key = countries if countries == "ALL" else f"{countries}.{frequency}", start_period = start_period, end_period = end_period, ) result["topic"] = f"sdg_{sdg_code}" return result # ------------------------------------------------------------------ # Bulk download method (for large datasets) # ------------------------------------------------------------------ def get_bulk_data( self, indicator_id: str, ref_area: Optional[str] = None, start_period: Optional[str] = None, end_period: Optional[str] = None, max_rows: Optional[int] = None, ) -> Dict[str, Any]: """ Download a full dataset for a given indicator via the SDMX REST API using an ALL key (wildcards every dimension). Note on bulk download facility: The classic CSV.GZ files at www.ilo.org/ilostat-files/WEB_bulk_download/ were migrated to webapps.ilo.org but appear to no longer be publicly accessible as of 2025. The Rilostat R package uses .rds binary files at rplumber.ilo.org which are not parseable from Python without R. This method therefore uses the SDMX REST API with an ALL key, which is functionally equivalent but subject to the 300,000-record payload limit (HTTP 413). For datasets larger than this, filter by ref_area or use the SDMX key to narrow the query before calling this function. Args: indicator_id: The indicator DSD code without the _A/_Q/_M frequency suffix AND without the DF_ prefix, e.g. "EMP_TEMP_SEX_AGE_NB". The frequency suffix present in the TOC id (e.g. _A) should be omitted here — frequency is handled via the SDMX key. ref_area: Optional ISO-2 country code to filter the SDMX key, e.g. "DEU". If omitted, ALL countries are requested. start_period: Start year/date, e.g. "2010". end_period: End year/date, e.g. "2023". max_rows: Cap on rows returned in the response (applied after fetch). Returns standard data dict. """ try: # Strip _A/_Q/_M frequency suffix that appears in the TOC id clean_id = indicator_id for suffix in ("_A", "_Q", "_M"): if clean_id.endswith(suffix): clean_id = clean_id[:-len(suffix)] break sdmx_key = ref_area if ref_area else "ALL" result = self.get_data( indicator_code = clean_id, key = sdmx_key, start_period = start_period, end_period = end_period, ) if result.get("success") and max_rows: result["data"] = result["data"][:max_rows] result["count"] = len(result["data"]) result["indicator_id"] = indicator_id result["source"] = "sdmx_all_key" return result except requests.exceptions.HTTPError as e: sc = e.response.status_code if e.response is not None else None return {"error": ILOStatError("get_bulk_data", str(e), sc).to_dict()} except Exception as e: return {"error": ILOStatError("get_bulk_data", str(e)).to_dict()} # ------------------------------------------------------------------ # Search / discovery helpers # ------------------------------------------------------------------ def search_indicators(self, query: str, language: str = "en") -> Dict[str, Any]: """ Search the ILOSTAT table of contents for matching indicators. Wraps get_table_of_contents() with a search filter. Args: query: Free-text search string (case-insensitive substring match). language: "en", "fr", or "es" Returns standard data dict with matching TOC rows. """ return self.get_table_of_contents(segment="indicator", language=language, search=query) def list_countries(self) -> Dict[str, Any]: """ Return the ILO area code list (ISO-2 + ILO region aggregates). Calls: GET {base}/codelist/ILO/CL_AREA """ return self.get_codelist("CL_AREA") def list_sex_codes(self) -> Dict[str, Any]: """Return sex disaggregation codes (SEX_T, SEX_M, SEX_F).""" return self.get_codelist("CL_SEX") def list_age_codes(self) -> Dict[str, Any]: """Return age group codes used in ILOSTAT.""" return self.get_codelist("CL_AGE") def list_economic_activity_codes(self) -> Dict[str, Any]: """Return ISIC-based economic activity codes (CL_ECO).""" return self.get_codelist("CL_ECO") def list_occupation_codes(self) -> Dict[str, Any]: """Return ISCO-based occupation codes (CL_OCU).""" return self.get_codelist("CL_OCU") def get_available_indicators_summary(self) -> Dict[str, Any]: """ Return a curated static reference of the most commonly used ILOSTAT indicator codes, grouped by topic. This is a fast local reference — use get_table_of_contents() or list_dataflows() for the live, complete catalogue. """ indicators = { "employment": [ {"code": "EMP_TEMP_SEX_AGE_NB", "freq": ["A", "Q", "M"], "description": "Employment by sex and age (number)"}, {"code": "EMP_TEMP_SEX_ECO_NB", "freq": ["A"], "description": "Employment by sex and economic activity (ISIC)"}, {"code": "EMP_TEMP_SEX_OCU_NB", "freq": ["A"], "description": "Employment by sex and occupation (ISCO)"}, {"code": "EMP_TEMP_SEX_STE_NB", "freq": ["A"], "description": "Employment by sex and status in employment"}, {"code": "EMP_DWAP_SEX_AGE_RT", "freq": ["A", "Q"], "description": "Employment-to-population ratio by sex and age"}, {"code": "EMP_2EMP_SEX_AGE_NB", "freq": ["A"], "description": "ILO modelled estimates — employment"}, {"code": "EMP_2EMP_SEX_STE_RT", "freq": ["A"], "description": "Informal employment share by sex and status"}, ], "unemployment": [ {"code": "UNE_DEAP_SEX_AGE_RT", "freq": ["A", "Q", "M"], "description": "Unemployment rate by sex and age (ILO modelled)"}, {"code": "UNE_2UNE_SEX_AGE_NB", "freq": ["A"], "description": "Unemployment count by sex and age (annual)"}, {"code": "UNE_TUNE_SEX_AGE_NB", "freq": ["Q"], "description": "Unemployment by sex and age (quarterly)"}, ], "labour_force": [ {"code": "EAP_DWAP_SEX_AGE_RT", "freq": ["A", "Q", "M"], "description": "Labour force participation rate by sex and age"}, {"code": "EAP_TEAP_SEX_AGE_NB", "freq": ["A", "Q"], "description": "Labour force (economically active population) by sex and age"}, {"code": "WAP_WAPF_SEX_AGE_NB", "freq": ["A"], "description": "Working-age population by sex and age"}, ], "wages_earnings": [ {"code": "EAR_4HRL_SEX_CUR_NB", "freq": ["A"], "description": "Mean hourly earnings by sex and currency (CUR dim: CUR_TYPE_LCU/USD/EUR/PPP)"}, {"code": "EAR_4MTH_SEX_CUR_NB", "freq": ["A"], "description": "Mean monthly earnings by sex and currency"}, {"code": "EAR_4MMN_CUR_NB", "freq": ["A"], "description": "Statutory minimum wage (nominal; no sex dimension)"}, {"code": "EAR_GGAP_OCU_RT", "freq": ["A"], "description": "Gender wage gap by occupation"}, {"code": "EAR_XTLP_SEX_RT", "freq": ["A"], "description": "Low pay incidence by sex"}, {"code": "SDG_0851_SEX_OCU_NB", "freq": ["A"], "description": "SDG 8.5.1 average hourly earnings"}, ], "currency_codes_cur": { "CUR_TYPE_LCU": "Local currency units", "CUR_TYPE_USD": "US Dollars", "CUR_TYPE_EUR": "Euros", "CUR_TYPE_PPP": "PPP-adjusted international dollars", }, "hours_of_work": [ {"code": "HOW_TEMP_SEX_ECO_NB", "freq": ["A"], "description": "Mean weekly hours by sex and economic activity"}, {"code": "HOW_XEES_SEX_ECO_RT", "freq": ["A"], "description": "Share of employed working > 48h/week"}, ], "labour_income_productivity": [ {"code": "LAP_2GDP_NOC_RT", "freq": ["A"], "description": "Labour income share (% of GDP, ILO modelled)"}, {"code": "LAP_2LID_QTL_RT", "freq": ["A"], "description": "Labour income distribution by decile"}, {"code": "LAP_2FTM_NOC_RT", "freq": ["A"], "description": "Gender income gap (women-to-men ratio)"}, {"code": "SDG_1041_NOC_RT", "freq": ["A"], "description": "SDG 10.4.1 labour income share"}, ], "social_protection_poverty": [ {"code": "SDG_0111_SEX_AGE_RT", "freq": ["A"], "description": "SDG 1.1.1 working poverty rate (%)"}, {"code": "SDG_0131_SEX_SOC_RT", "freq": ["A"], "description": "SDG 1.3.1 social protection coverage"}, ], "sdg_indicators": [ {"code": "SDG_0551_NOC_RT", "freq": ["A"], "description": "SDG 5.5.1 women in managerial positions"}, {"code": "SDG_0552_NOC_RT", "freq": ["A"], "description": "SDG 5.5.2 women in senior/middle management"}, {"code": "SDG_0811_SEX_AGE_RT", "freq": ["A"], "description": "SDG 8.1.1 GDP per employed person growth rate"}, {"code": "SDG_0852_SEX_AGE_RT", "freq": ["A", "Q"], "description": "SDG 8.5.2 unemployment rate"}, {"code": "SDG_0861_SEX_AGE_NB", "freq": ["A"], "description": "SDG 8.6.1 youth NEET rate"}, {"code": "SDG_0871_SEX_AGE_RT", "freq": ["A"], "description": "SDG 8.7.1 child labour rate"}, {"code": "SDG_0881_NOC_RT", "freq": ["A"], "description": "SDG 8.8.1 fatal occupational injuries"}, {"code": "SDG_0882_NOC_RT", "freq": ["A"], "description": "SDG 8.8.2 non-fatal occupational injuries"}, ], "country_groups": { "G7": G7_COUNTRIES, "G20": G20_COUNTRIES, "EU": EU_COUNTRIES, }, "dimension_notes": { "key_order": "REF_AREA.FREQ.MEASURE.SEX.CLASSIF1[.CLASSIF2]", "wildcard": "Omit a dimension or use ALL to wildcard all dimensions", "or_operator": "Use + between values, e.g. CAN+USA+GBR", "freq_codes": {"A": "Annual", "Q": "Quarterly", "M": "Monthly"}, "sex_codes": {"SEX_T": "Total", "SEX_M": "Male", "SEX_F": "Female"}, "common_age_codes": { "AGE_YTHADULT_YGE15": "15 and over", "AGE_YTHADULT_Y15-24": "Youth 15-24", "AGE_YTHADULT_YGE25": "Adults 25+", "_T": "Total (no age breakdown)", }, }, } return { "success": True, "data": indicators, "sector_codes_eco": { "ECO_ISIC4_TOTAL": "Total (all sectors)", "ECO_ISIC4_A": "Agriculture, forestry and fishing", "ECO_ISIC4_B": "Mining and quarrying", "ECO_ISIC4_C": "Manufacturing", "ECO_ISIC4_D": "Electricity, gas, steam supply", "ECO_ISIC4_E": "Water supply, sewerage, waste", "ECO_ISIC4_F": "Construction", "ECO_ISIC4_G": "Wholesale and retail trade", "ECO_ISIC4_H": "Transportation and storage", "ECO_ISIC4_I": "Accommodation and food service", "ECO_ISIC4_J": "Information and communication", "ECO_ISIC4_K": "Financial and insurance activities", "ECO_ISIC4_L": "Real estate activities", "ECO_ISIC4_M": "Professional, scientific and technical", "ECO_ISIC4_N": "Administrative and support services", "ECO_ISIC4_O": "Public administration and defence", "ECO_ISIC4_P": "Education", "ECO_ISIC4_Q": "Human health and social work", "ECO_ISIC4_R": "Arts, entertainment and recreation", "ECO_ISIC4_S": "Other service activities", }, "occupation_codes_ocu": { "OCU_ISCO08_TOTAL": "Total all occupations", "OCU_ISCO08_1": "Managers", "OCU_ISCO08_2": "Professionals", "OCU_ISCO08_3": "Technicians and associate professionals", "OCU_ISCO08_4": "Clerical support workers", "OCU_ISCO08_5": "Service and sales workers", "OCU_ISCO08_6": "Skilled agricultural workers", "OCU_ISCO08_7": "Craft and related trades workers", "OCU_ISCO08_8": "Plant and machine operators", "OCU_ISCO08_9": "Elementary occupations", "OCU_ISCO08_0": "Armed forces occupations", }, "status_codes_ste": { "STE_ICSE93_TOTAL": "Total", "STE_ICSE93_1": "Employees", "STE_ICSE93_2": "Employers", "STE_ICSE93_3": "Own-account workers", "STE_ICSE93_4": "Members of producers cooperatives", "STE_ICSE93_5": "Contributing family workers", "STE_ICSE93_6": "Workers not classifiable by status", }, "api_info": { "sdmx_base_url": SDMX_BASE_URL, "toc_url": TOC_BY_INDICATOR_URL, "toc_ref_area_url": TOC_BY_REF_AREA_URL, "authentication": "None required — open data", "rate_limits": "HTTP 413 returned when result set exceeds ~300,000 records; narrow the key", "formats": ["csv (text/csv Accept header)", "jsondata", "genericdata (XML)"], "user_guide": "https://webapps.ilo.org/ilostat-files/Documents/SDMX_User_Guide.pdf", "sdmx_user_guide_notice": "April 2024: base URL migrated from www.ilo.org/sdmx/rest to sdmx.ilo.org/rest", }, } # --------------------------------------------------------------------------- # CLI entry point (invoked by C++ Python bridge) # --------------------------------------------------------------------------- COMMANDS = { # Short aliases (preferred) "unemployment": "[countries] [frequency] [sex] [age_group] [start] [end]", "employment": "[countries] [frequency] [sex] [age_group] [start] [end]", "emp_to_pop": "[countries] [frequency] [sex] [age_group] [start] [end]", "lfpr": "[countries] [frequency] [sex] [age_group] [start] [end]", "wages": "[countries] [frequency] [wage_type] [sex] [currency] [start] [end]", "gender_wage_gap": "[countries] [frequency] [occupation] [start] [end]", "hours_of_work": "[countries] [frequency] [sex] [economic_act] [start] [end]", "labour_income_share": "[countries] [frequency] [start] [end]", "working_poverty": "[countries] [frequency] [sex] [age_group] [start] [end]", "emp_by_sector": "[countries] [frequency] [sex] [sector] [start] [end]", "emp_by_occupation": "[countries] [frequency] [sex] [occupation] [start] [end]", "emp_by_status": "[countries] [frequency] [sex] [status] [start] [end]", "informal_employment": "[countries] [frequency] [sex] [start] [end]", "social_protection": "[countries] [frequency] [sex] [start] [end]", "country_profile": " [start] [end]", "sdg_indicator": " [countries] [frequency] [start] [end]", "bulk_data": " [ref_area] [start] [end] [max_rows]", "search": " [language]", "dataflows": "(topic_prefix?)", "codelist": " [agency]", "toc": "[segment] [language] [search]", "data": " [key] [start] [end] [detail]", "countries": "(no args)", "available": "(no args)", # Verbose aliases (also supported) "list_dataflows": "(topic_prefix?)", "get_codelist": " [agency]", "get_table_of_contents": "[segment] [language] [search]", "get_data": " [key] [start] [end] [detail]", "get_unemployment": "[countries] [frequency] [sex] [age_group] [start] [end]", "get_employment": "[countries] [frequency] [sex] [age_group] [start] [end]", "get_employment_to_population": "[countries] [frequency] [sex] [age_group] [start] [end]", "get_labour_force_participation": "[countries] [frequency] [sex] [age_group] [start] [end]", "get_wages": "[countries] [frequency] [wage_type] [sex] [currency] [start] [end]", "get_gender_wage_gap": "[countries] [frequency] [occupation] [start] [end]", "get_hours_of_work": "[countries] [frequency] [sex] [economic_act] [start] [end]", "get_labour_income_share": "[countries] [frequency] [start] [end]", "get_working_poverty": "[countries] [frequency] [sex] [age_group] [start] [end]", "get_employment_by_sector": "[countries] [frequency] [sex] [sector] [start] [end]", "get_employment_by_occupation": "[countries] [frequency] [sex] [occupation] [start] [end]", "get_employment_by_status": "[countries] [frequency] [sex] [status] [start] [end]", "get_informal_employment": "[countries] [frequency] [sex] [start] [end]", "get_social_protection": "[countries] [frequency] [sex] [start] [end]", "get_country_profile": " [start] [end]", "get_sdg_indicator": " [countries] [frequency] [start] [end]", "get_bulk_data": " [ref_area] [start] [end] [max_rows]", "search_indicators": " [language]", "list_countries": "(no args)", "list_sex_codes": "(no args)", "list_age_codes": "(no args)", "list_economic_activity_codes": "(no args)", "list_occupation_codes": "(no args)", "available_indicators": "(no args)", } def _arg(args: List[str], index: int, default: Any = None) -> Any: """Safe list index access with default.""" try: val = args[index] return val if val else default except IndexError: return default def main(args: Optional[List[str]] = None) -> None: if args is None: args = sys.argv[1:] if not args: print(json.dumps({ "error": "No command provided.", "usage": "python ilostat_data.py [args...]", "commands": COMMANDS, }, indent=2)) sys.exit(1) command = args[0] rest = args[1:] wrapper = ILOStatWrapper() # Normalize short aliases to canonical names _ALIASES = { "unemployment": "get_unemployment", "employment": "get_employment", "emp_to_pop": "get_employment_to_population", "lfpr": "get_labour_force_participation", "wages": "get_wages", "gender_wage_gap": "get_gender_wage_gap", "hours_of_work": "get_hours_of_work", "labour_income_share": "get_labour_income_share", "working_poverty": "get_working_poverty", "emp_by_sector": "get_employment_by_sector", "emp_by_occupation": "get_employment_by_occupation", "emp_by_status": "get_employment_by_status", "informal_employment": "get_informal_employment", "social_protection": "get_social_protection", "country_profile": "get_country_profile", "sdg_indicator": "get_sdg_indicator", "bulk_data": "get_bulk_data", "search": "search_indicators", "dataflows": "list_dataflows", "codelist": "get_codelist", "toc": "get_table_of_contents", "data": "get_data", "countries": "list_countries", "available": "available_indicators", } command = _ALIASES.get(command, command) try: if command == "list_dataflows": result = wrapper.list_dataflows(topic_prefix=_arg(rest, 0)) elif command == "get_codelist": if not rest: result = {"error": "get_codelist requires "} else: result = wrapper.get_codelist( codelist_id = rest[0], agency = _arg(rest, 1, "ILO"), ) elif command == "get_table_of_contents": result = wrapper.get_table_of_contents( segment = _arg(rest, 0, "indicator"), language = _arg(rest, 1, "en"), search = _arg(rest, 2), ) elif command == "get_data": if not rest: result = {"error": "get_data requires "} else: result = wrapper.get_data( indicator_code = rest[0], key = _arg(rest, 1, "ALL"), start_period = _arg(rest, 2), end_period = _arg(rest, 3), detail = _arg(rest, 4, "dataonly"), ) elif command == "get_unemployment": result = wrapper.get_unemployment( countries = _arg(rest, 0, "ALL"), frequency = _arg(rest, 1, FREQ_ANNUAL), sex = _arg(rest, 2, "SEX_T"), age_group = _arg(rest, 3, "AGE_YTHADULT_YGE15"), start_period = _arg(rest, 4), end_period = _arg(rest, 5), ) elif command == "get_employment": result = wrapper.get_employment( countries = _arg(rest, 0, "ALL"), frequency = _arg(rest, 1, FREQ_ANNUAL), sex = _arg(rest, 2, "SEX_T"), age_group = _arg(rest, 3, "_T"), start_period = _arg(rest, 4), end_period = _arg(rest, 5), ) elif command == "get_employment_to_population": result = wrapper.get_employment_to_population_ratio( countries = _arg(rest, 0, "ALL"), frequency = _arg(rest, 1, FREQ_ANNUAL), sex = _arg(rest, 2, "SEX_T"), age_group = _arg(rest, 3, "AGE_YTHADULT_YGE15"), start_period = _arg(rest, 4), end_period = _arg(rest, 5), ) elif command == "get_labour_force_participation": result = wrapper.get_labour_force_participation( countries = _arg(rest, 0, "ALL"), frequency = _arg(rest, 1, FREQ_ANNUAL), sex = _arg(rest, 2, "SEX_T"), age_group = _arg(rest, 3, "AGE_YTHADULT_YGE15"), start_period = _arg(rest, 4), end_period = _arg(rest, 5), ) elif command == "get_wages": result = wrapper.get_wages( countries = _arg(rest, 0, "ALL"), frequency = _arg(rest, 1, FREQ_ANNUAL), wage_type = _arg(rest, 2, "monthly"), sex = _arg(rest, 3, "SEX_T"), currency = _arg(rest, 4, "CUR_TYPE_LCU"), start_period = _arg(rest, 5), end_period = _arg(rest, 6), ) elif command == "get_gender_wage_gap": result = wrapper.get_gender_wage_gap( countries = _arg(rest, 0, "ALL"), frequency = _arg(rest, 1, FREQ_ANNUAL), occupation = _arg(rest, 2, "OCU_ISCO08_TOTAL"), start_period = _arg(rest, 3), end_period = _arg(rest, 4), ) elif command == "get_hours_of_work": result = wrapper.get_hours_of_work( countries = _arg(rest, 0, "ALL"), frequency = _arg(rest, 1, FREQ_ANNUAL), sex = _arg(rest, 2, "SEX_T"), economic_act = _arg(rest, 3, "ECO_ISIC4_TOTAL"), start_period = _arg(rest, 4), end_period = _arg(rest, 5), ) elif command == "get_labour_income_share": result = wrapper.get_labour_income_share( countries = _arg(rest, 0, "ALL"), frequency = _arg(rest, 1, FREQ_ANNUAL), start_period = _arg(rest, 2), end_period = _arg(rest, 3), ) elif command == "get_working_poverty": result = wrapper.get_working_poverty( countries = _arg(rest, 0, "ALL"), frequency = _arg(rest, 1, FREQ_ANNUAL), sex = _arg(rest, 2, "SEX_T"), age_group = _arg(rest, 3, "AGE_YTHADULT_YGE15"), start_period = _arg(rest, 4), end_period = _arg(rest, 5), ) elif command == "get_employment_by_sector": result = wrapper.get_employment_by_sector( countries = _arg(rest, 0, "ALL"), frequency = _arg(rest, 1, FREQ_ANNUAL), sex = _arg(rest, 2, "SEX_T"), sector = _arg(rest, 3, "_T"), start_period = _arg(rest, 4), end_period = _arg(rest, 5), ) elif command == "get_employment_by_occupation": result = wrapper.get_employment_by_occupation( countries = _arg(rest, 0, "ALL"), frequency = _arg(rest, 1, FREQ_ANNUAL), sex = _arg(rest, 2, "SEX_T"), occupation = _arg(rest, 3, "_T"), start_period = _arg(rest, 4), end_period = _arg(rest, 5), ) elif command == "get_employment_by_status": result = wrapper.get_employment_by_status( countries = _arg(rest, 0, "ALL"), frequency = _arg(rest, 1, FREQ_ANNUAL), sex = _arg(rest, 2, "SEX_T"), status = _arg(rest, 3, "_T"), start_period = _arg(rest, 4), end_period = _arg(rest, 5), ) elif command == "get_informal_employment": result = wrapper.get_informal_employment( countries = _arg(rest, 0, "ALL"), frequency = _arg(rest, 1, FREQ_ANNUAL), sex = _arg(rest, 2, "SEX_T"), start_period = _arg(rest, 3), end_period = _arg(rest, 4), ) elif command == "get_social_protection": result = wrapper.get_social_protection_coverage( countries = _arg(rest, 0, "ALL"), frequency = _arg(rest, 1, FREQ_ANNUAL), sex = _arg(rest, 2, "SEX_T"), start_period = _arg(rest, 3), end_period = _arg(rest, 4), ) elif command == "get_country_profile": if not rest: result = {"error": "get_country_profile requires "} else: result = wrapper.get_country_profile( country = rest[0], start_period = _arg(rest, 1), end_period = _arg(rest, 2), ) elif command == "get_sdg_indicator": if not rest: result = {"error": "get_sdg_indicator requires "} else: result = wrapper.get_sdg_indicator( sdg_code = rest[0], countries = _arg(rest, 1, "ALL"), frequency = _arg(rest, 2, FREQ_ANNUAL), start_period = _arg(rest, 3), end_period = _arg(rest, 4), ) elif command == "get_bulk_data": if not rest: result = {"error": "get_bulk_data requires "} else: max_rows = _arg(rest, 4) result = wrapper.get_bulk_data( indicator_id = rest[0], ref_area = _arg(rest, 1), start_period = _arg(rest, 2), end_period = _arg(rest, 3), max_rows = int(max_rows) if max_rows else None, ) elif command == "search_indicators": if not rest: result = {"error": "search_indicators requires "} else: result = wrapper.search_indicators( query = rest[0], language = _arg(rest, 1, "en"), ) elif command == "list_countries": result = wrapper.list_countries() elif command == "list_sex_codes": result = wrapper.list_sex_codes() elif command == "list_age_codes": result = wrapper.list_age_codes() elif command == "list_economic_activity_codes": result = wrapper.list_economic_activity_codes() elif command == "list_occupation_codes": result = wrapper.list_occupation_codes() elif command == "available_indicators": result = wrapper.get_available_indicators_summary() else: result = { "error": f"Unknown command: {command}", "commands": COMMANDS, } print(json.dumps(result, indent=2, ensure_ascii=False)) except Exception as exc: print(json.dumps({ "error": str(exc), "traceback": traceback.format_exc(), }, indent=2)) sys.exit(1) if __name__ == "__main__": main()