# query_metrics

> Get aggregated, cited metric values for up to 25 areas (max 200 rows).

Get aggregated, cited metric values for up to 25 areas (max 200 rows). Values are at the metric's native geography; means and ratios are never summed.

**Counts against your plan:** yes, one call. **Read-only:** yes, nothing you send is stored or changes any data.

## Inputs

| Name | Type | Required | Default | Description |
|---|---|---|---|---|
| `metrics` | `string[]` | yes | none | 1-5 metric ids from describe_catalog, e.g. ['population_total', 'crime_count:murder'] |
| `area_ids` | `string[]` | yes | none | 1-25 area_ids from resolve_location |
| `year_from` | `integer` | no | none | First year (financial years start in this year). Default: latest available |
| `year_to` | `integer` | no | none | Last year (inclusive) |
| `time_grain` | `"native" / "year"` | no | `"native"` | 'year' aggregates monthly metrics to annual totals |
| `combine_areas` | `boolean` | no | `false` | Return one combined value per period across the areas (sum for counts, area-weighted mean for means/ratios). Areas must share a type. |

## Caps

| Cap | Value |
|---|---|
| Metrics per call | 5 |
| Areas per call | 25 |
| Rows per call | 200 |

Your plan can set lower caps. See [Plans and limits](/docs/limits). A request over a cap is refused with `LIMIT_EXCEEDED`; nothing is truncated silently.

## Response

Every response also carries `citations`, `caveats` and `dataset_version` ([Citations](/docs/citations)).

| Field | Type | Description |
|---|---|---|
| `citations` | `object[]` |  |
| `caveats` | `string[]` |  |
| `dataset_version` | `string` |  |
| `rows` | `object[]` |  |
| `row_count` | `integer` |  |
| `request` | `object` |  |
| `limits` | `object` |  |

**`rows[]`** (each item)

| Field | Type | Description |
|---|---|---|
| `metric_id` | `string` |  |
| `area_id` | `string` |  |
| `area_name` | `string` |  |
| `area_type` | `string` |  |
| `period` | `string` |  |
| `value` | `number` |  |
| `unit` | `string` |  |
| `is_estimate` | `boolean` |  |
| `method` | `string` |  |
| `source_ids` | `string[]` | Sources behind this value (see citations) |
| `n_periods` | `integer` | Native periods aggregated into this row |
| `n_areas` | `integer` | Native areas aggregated into this row |

**`request`**

| Field | Type | Description |
|---|---|---|
| `year_from` | `integer` |  |
| `year_to` | `integer` |  |
| `metrics` | `string[]` |  |
| `area_ids` | `string[]` |  |
| `time_grain` | `"native" / "year"` |  |
| `combine_areas` | `boolean` |  |

## Examples

> **Fixture data**
>
> These responses were produced by the real tool against the synthetic test dataset (`fixture-2026.11.05`), so the numbers are illustrative, not real statistics. Production responses cite the real sources.

### Population of one municipality in one year

Request:

```json
{
  "metrics": [
    "population_total"
  ],
  "area_ids": [
    "lm:WC011"
  ],
  "year_from": 2025,
  "year_to": 2025
}
```

Response:

```json
{
  "citations": [
    {
      "source_id": "worldpop_population",
      "name": "[FIXTURE] WorldPop Constrained Population 100 m (R2025A)",
      "publisher": "WorldPop, University of Southampton",
      "url": "https://www.worldpop.org/",
      "licence": "CC-BY-4.0",
      "commercial_use": "yes",
      "attribution": "WorldPop (www.worldpop.org), University of Southampton. CC BY 4.0.",
      "retrieved_at": "2026-11-05",
      "dataset_version": "fixture-2026.11.05"
    }
  ],
  "caveats": [
    "FIXTURE DATA: these numbers are synthetic test values, not real statistics. Do not use them for decisions.",
    "Modelled estimate (WorldPop constrained gridded population), not a census count.",
    "Zonal sum of 100 m cells; small wards can be off by a few percent at boundaries.",
    "population_total values are estimates (method: zonal_sum)."
  ],
  "dataset_version": "fixture-2026.11.05",
  "rows": [
    {
      "metric_id": "population_total",
      "area_id": "lm:WC011",
      "area_name": "Matzikama",
      "area_type": "local_municipality",
      "period": "2025",
      "value": 21270.0,
      "unit": "people",
      "is_estimate": true,
      "method": "zonal_sum",
      "source_ids": [
        "worldpop_population"
      ],
      "n_periods": 1,
      "n_areas": 1
    }
  ],
  "row_count": 1,
  "request": {
    "year_from": 2025,
    "year_to": 2025,
    "metrics": [
      "population_total"
    ],
    "area_ids": [
      "lm:WC011"
    ],
    "time_grain": "native",
    "combine_areas": false
  },
  "limits": {
    "max_metrics_per_call": 5,
    "max_areas_per_call": 25,
    "max_rows_per_call": 200,
    "compare_areas_min": 2,
    "compare_areas_max": 5,
    "max_location_candidates": 5
  }
}
```

Provenance in this example: source `worldpop_population`, licence “CC-BY-4.0”, retrieved 2026-11-05, dataset_version `fixture-2026.11.05`.

### A count rolled up to a province (murders, financial year 2024/25)

Request:

```json
{
  "metrics": [
    "crime_count:murder"
  ],
  "area_ids": [
    "prov:WC"
  ],
  "year_from": 2024,
  "year_to": 2024
}
```

Response:

```json
{
  "citations": [
    {
      "source_id": "saps_crime_stats",
      "name": "[FIXTURE] SAPS Crime Statistics",
      "publisher": "South African Police Service (SAPS)",
      "url": "https://www.saps.gov.za/services/crimestats.php",
      "licence": "SAPS website copyright (no open licence)",
      "commercial_use": "unclear",
      "attribution": "Source: South African Police Service, Crime Statistics",
      "retrieved_at": "2026-11-05",
      "dataset_version": "fixture-2026.11.05"
    }
  ],
  "caveats": [
    "FIXTURE DATA: these numbers are synthetic test values, not real statistics. Do not use them for decisions.",
    "Counts are crimes recorded by SAPS (reported to police), not victimisation; under-reporting varies by crime type and place.",
    "Native geography is the SAPS police station precinct, which does not align with ward or municipal boundaries.",
    "Do not add roll-up categories to their component categories.",
    "crime_count:murder for province is a sum of native police_station values.",
    "Licence note (saps_crime_stats): SAPS website copyright (no open licence); commercial use 'unclear'. Served only as derived aggregates with attribution: Source: South African Police Service, Crime Statistics"
  ],
  "dataset_version": "fixture-2026.11.05",
  "rows": [
    {
      "metric_id": "crime_count:murder",
      "area_id": "prov:WC",
      "area_name": "Western Cape",
      "area_type": "province",
      "period": "FY2024/25",
      "value": 25.0,
      "unit": "count",
      "is_estimate": false,
      "method": "rollup_sum",
      "source_ids": [
        "saps_crime_stats"
      ],
      "n_periods": 1,
      "n_areas": 3
    }
  ],
  "row_count": 1,
  "request": {
    "year_from": 2024,
    "year_to": 2024,
    "metrics": [
      "crime_count:murder"
    ],
    "area_ids": [
      "prov:WC"
    ],
    "time_grain": "native",
    "combine_areas": false
  },
  "limits": {
    "max_metrics_per_call": 5,
    "max_areas_per_call": 25,
    "max_rows_per_call": 200,
    "compare_areas_min": 2,
    "compare_areas_max": 5,
    "max_location_candidates": 5
  }
}
```

Provenance in this example: source `saps_crime_stats`, licence “SAPS website copyright (no open licence)”, retrieved 2026-11-05, dataset_version `fixture-2026.11.05`.

## Errors

Errors read `<CODE>: <what went wrong>. Fix: <how to fix it>`. Shared codes are on the [Tool reference](/docs/tools) page.

| Request | Error |
|---|---|
| `{"metrics": ["no_such_metric"], "area_ids": ["lm:WC011"]}` | `UNKNOWN_METRIC: Unknown metric 'no_such_metric'. Fix: Use one of ['population_total', 'population_density_km2', 'rainfall_monthly_mm', 'rainfall_annual_mm', 'osm_school_count', 'osm_hospital_count', 'osm_clinic_count', 'osm_pharmacy_count', 'osm_police_station_count', 'osm_fuel_station_count', 'osm_supermarket_count', 'operating_revenue', 'operating_expenditure', 'property_rates_revenue', 'property_rates_revenue_per_capita', 'capital_budget', 'audit_outcome', 'unauthorised_irregular_fruitless_wasteful', 'cash_coverage_months', 'debtor_collection_rate'] or a family member such as ['crime_count:burglary_residential', 'crime_count:common_assault', 'crime_count:contact_crime', 'crime_count:murder']. Call describe_catalog for the full list.` |
| `{"metrics": ["population_total"], "area_ids": ["lm:NOPE"]}` | `UNKNOWN_AREA: Unknown area_id(s): ['lm:NOPE']. Fix: Call resolve_location with a place name to get valid area_ids (formats: prov:WC, dm:DC1, lm:WC011, ward:10101001, saps:<slug>).` |
| `{"metrics": ["population_total"], "area_ids": ["lm:WC011"], "year_from": 2026, "year_to": 2020}` | `INVALID_ARGUMENT: year_from (2026) is after year_to (2020). Fix: Swap them or pass a single year in both.` |