top_n
Rank dataset measures by highest or lowest value for the most recent period, returning only the top or bottom N rows to avoid processing full time series.
Instructions
Return the N rows with the largest (or smallest) value of a measure.
Ranks across the most-recent available period only (uses lastNObservations=1 under the hood) so the result is a clean "top N entities at the latest period" view — not noisy historical highs.
This is the most common agent workflow: "show me the top 10 X by Y". Without this tool, an agent would call get_data, receive the full time series, and then sort/slice locally — wasting tokens and turns. top_n does the rank server-side and returns only the requested rows.
Examples: # 5 states with the highest current unemployment rate top_n("LF", "unemployment_rate", n=5)
# 10 GCCSAs with the largest populations
top_n("ABS_ANNUAL_ERP_ASGS2021", "estimated_resident_population",
n=10, filters={"region_type": "gccsa"})
# 3 industries with the lowest wage growth
top_n("WPI", "wage_price_index", n=3, direction="bottom")Returns:
DataResponse with at most n records, sorted by measure value
in the requested direction. Other fields (period, unit, attribution)
match a regular get_data call.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| n | No | How many top (or bottom) rows to return. | |
| filters | No | Optional additional dimension filters, same shape as get_data. Do NOT include the 'measure' key here — that is supplied via the `measure` parameter. | |
| measure | Yes | Plain-English measure key to rank by — one of the curated measure values for this dataflow. Use the describe endpoint or describe tool to see available measures. | |
| direction | No | 'top' returns the N rows with the LARGEST measure values (highest unemployment_rate, biggest population, etc.). 'bottom' returns the SMALLEST. | top |
| dataset_id | Yes | ABS dataflow ID. Must be a curated dataflow with a 'measure' dimension. Use the list-curated endpoint or list tool to enumerate. |
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 |