Query ILOSTAT observations
ilostat_query_indicatorFetch observations for up to 3 ILOSTAT datasets per call, filtered by reference area or area group, sex, breakdown codes (classif1, classif2), source, and period; datasets past the first 3 come back as remaining_dataset_ids for another call. Rows keep their source, observation status, decoded notes, and a basis — reported, modelled_estimate, or projection — and the response echoes every filter applied, including the best-source default. Codes are checked against ILOSTAT's dictionaries before the request is sent: ilostat_list_reference lists valid codes and ilostat_describe_indicator lists the codes a dataset actually uses. A result larger than the inline preview is staged in full as a df_ dataframe for SQL through ilostat_dataframe_describe and ilostat_dataframe_query when this deployment enables dataframes. A request with no filters at all is refused when the dataset exceeds the row ceiling, and a filtered request that still exceeds it is refused with guidance to narrow it.
Tool call template
Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"dataset_ids": "<dataset_ids>"
},
"name": "ilostat_query_indicator"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| sex | No | Sex codes SEX_T, SEX_M, SEX_F, SEX_O; T/M/F/O and total/both/male/female/other are accepted. | |
| time | No | One exact period: YYYY (on a quarterly or monthly dataset, every period of that year), YYYYQn, or YYYYMmm; 2024-Q2, 2024 Q2, and 2025-03 are normalized. Not combinable with time_from, time_to, or latest_only. | |
| sources | No | Source codes (e.g. BA:453); ilostat_list_reference topic sources with ref_area lists an area's sources. Without source_selection, setting sources switches it to all, since a secondary source matches nothing under best. | |
| time_to | No | Last year (YYYY), not before time_from. | |
| classif1 | No | Codes of the first breakdown (e.g. AGE_YTHADULT_YGE15); case-insensitive. ilostat_describe_indicator lists the codes a dataset uses. | |
| classif2 | No | Codes of the second breakdown, for datasets that have one; case-insensitive. ilostat_describe_indicator lists them. | |
| ref_areas | No | Reference areas (up to 300): ISO3 country codes (USA) or X-coded aggregates (X01 World); case-insensitive, ILO_GEO_ forms accepted. Aggregates need a dataset with has_aggregates true. Omit for every area. | |
| time_from | No | First year (YYYY); upstream filters by year only. | |
| area_group | No | X01 for every country, an ILO region or subregion, or a World Bank income group (X06, X56, X02, …); expands to its member countries, unioned with ref_areas. ilostat_list_reference topic area_groups lists the codes. | |
| dataset_ids | Yes | Dataset IDs, up to 100 — an indicator code plus _A, _Q, or _M (UNE_DEAP_SEX_AGE_RT_A), as ilostat_search_indicators returns them. Case-insensitive; a DF_ prefix (the SDMX dataflow form) is stripped, a bare indicator code resolves when it has one frequency, an element holding + or , joined IDs is split, and duplicates are dropped. Every ID is checked; the first 3 distinct datasets are queried and the rest come back as remaining_dataset_ids for another call. | |
| latest_only | No | Only each series' latest period — a series is one dataset, reference area, sex, classif1, and classif2 code — with every row at that period (one per source under source_selection all or secondary; the latest quarter or month on sub-annual datasets); combines with time_from/time_to. When the request's full history is too large or too slow to read in one call, it falls back to the latest period per area and dataset, which can miss a series that ends earlier; applied_filters.latest_mode says which ran, and the notice says so. time_from or classif1 narrow it back under; sex or fewer ref_areas alone may still read too much and fall back. | |
| source_selection | No | best (default): the preferred source per area and period; all: secondary sources too, each row flagged best_source; secondary: secondary sources only. Defaults to all when sources is set. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| cap | No | Inline preview budget, in serialized characters. | |
| rows | No | Inline preview rows; the staged dataframe holds every row when the result is larger. | |
| error | No | Present when the call failed. Absent on success. | |
| shown | No | Rows returned inline. | |
| legend | No | Labels for every code in rows. | |
| notice | No | Datasets left for another call, a latest_only fallback to the latest period per area and dataset, filters that could not narrow a dataset, a unit the structure service could not supply, why nothing matched, where the full result is staged, or why reading stopped early. | |
| summary | No | Summary over every row read, not just the preview. | |
| datasets | No | The queried datasets, in request order. | |
| dataframe | No | The staged dataframe holding the full result; present only when staged. | |
| row_count | No | Rows the request returned — exact unless reading stopped early at the inline preview (summary.complete false), when it counts the rows read. | |
| truncated | No | True when reading stopped at the inline preview and more rows exist. | |
| attribution | No | Citation to keep with any use of the data. | |
| applied_filters | No | Every parameter sent upstream, defaults included. | |
| remaining_dataset_ids | No | Requested datasets past the first 3, as canonical IDs in request order; not fetched in this call. Pass them as dataset_ids with the same filters to get them. Absent when every requested dataset was queried. |