get_data
Retrieve time-series observations from ABS datasets by applying plain-English filters and date ranges. Returns data as records, series, or CSV for analysis.
Instructions
Query an ABS dataflow and return observations.
Pass filters and/or a period range — unfiltered queries on large dataflows can return tens of thousands of observations.
Curated dataflows accept plain-English filter keys and values that
are translated to SDMX codes server-side. For example, on LF:
{"region": "nsw", "measure": "unemployment_rate"} resolves to
SDMX key M13.3.1599.20.1.M with hidden-dim defaults auto-applied.
Examples: # NSW unemployment monthly for 2024 resp = await get_data( "LF", filters={"region": "nsw", "measure": "unemployment_rate"}, start_period="2024", end_period="2024-12", ) # → resp.records[0]: period='2024-01', value=4.8, unit='Percent'
# Multi-state comparison
resp = await get_data(
"LF",
filters={"region": ["nsw","vic","qld"], "measure": "unemployment_rate"},
start_period="2024",
format="csv",
)
# → resp.csv contains 36 rows (3 states × 12 months)
# Australia quarterly CPI annual change
resp = await get_data(
"CPI",
filters={"region": "australia", "measure": "change_year"},
start_period="2020",
)When to use: - You want observations over a time range (use latest() for the most-recent only) - You want a multi-state or multi-measure comparison via list filters - You want a CSV for downstream charting / spreadsheet tools
Returns: DataResponse with records (list of {period, value, dimensions, unit}), unit (when homogeneous), period bounds, the resolved query echo, the ABS source URL, and the CC-BY 4.0 attribution string.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| format | No | Response shape. 'records' (default): flat list of observations. 'series': observations grouped by dimension key for chart-friendly shapes. 'csv': returns the table as a CSV string in the `csv` field with records empty. | records |
| filters | No | Dimension filters. For curated dataflows: plain-English keys and values, e.g. {'region': 'nsw', 'measure': 'unemployment_rate'}. For raw dataflows: SDMX dimension IDs and codes. Pass a list as the value to query multiple values for a dimension. Whitespace is stripped; empty list / empty value rejected with a hint. | |
| dataset_id | Yes | ABS dataflow ID like 'LF', 'CPI'. Use search_datasets to discover. | |
| end_period | No | Inclusive end period. Same format as start_period. | |
| start_period | No | Inclusive start period. Format follows the dataflow's cadence: annual 'YYYY' (e.g. '2020'), monthly 'YYYY-MM' (e.g. '2024-03'), quarterly 'YYYY-Q1', half-yearly 'YYYY-S1', daily 'YYYY-MM-DD'. An int year (e.g. 2024) is also accepted and treated as 'YYYY'. URL-unsafe characters (?, &, /, etc.) are rejected at the boundary. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| csv | No | ||
| unit | No | ||
| query | No | ||
| stale | No | ||
| period | No | ||
| source | No | Australian Bureau of Statistics | |
| abs_url | Yes | Click-through URL for this dataset's source page. abs-mcp legacy name — prefer source_url (canonical) for new code. Both fields are populated identically. | |
| records | No | ||
| row_count | No | Number of observation rows in records. | |
| dataset_id | Yes | ||
| source_url | Yes | Canonical click-through URL. Same value as abs_url; both populated for backward compat. | |
| attribution | No | Data sourced from the Australian Bureau of Statistics and licensed under Creative Commons Attribution 4.0 International (CC BY 4.0). https://www.abs.gov.au/about/copyright-and-creative-commons | |
| dataset_name | Yes | ||
| retrieved_at | Yes | ||
| stale_reason | No | ||
| truncated_at | No | ||
| server_version | No |