# compare_areas

> Compare 2-5 areas on up to 5 metrics: value, rank among them (1 = highest) and the national percentile among all areas of the same type.

Compare 2-5 areas on up to 5 metrics: value, rank among them (1 = highest) and the national percentile among all areas of the same type.

**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 |
|---|---|---|---|---|
| `area_ids` | `string[]` | yes | none | 2-5 area_ids of the same type |
| `metrics` | `string[]` | yes | none | 1-5 metric ids |
| `year` | `integer` | no | none | Year to compare. Default: latest year with data for every area |

## Caps

| Cap | Value |
|---|---|
| Areas per call (min) | 2 |
| Areas per call (max) | 5 |
| Metrics per call | 5 |

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` |  |
| `comparisons` | `object[]` |  |

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

| Field | Type | Description |
|---|---|---|
| `metric_id` | `string` |  |
| `unit` | `string` |  |
| `period` | `string` |  |
| `area_type` | `string` |  |
| `spatial_aggregation` | `string` |  |
| `entries` | `object[]` |  |

**`comparisons.entries[]`** (each item)

| Field | Type | Description |
|---|---|---|
| `area_id` | `string` |  |
| `area_name` | `string` |  |
| `value` | `number` |  |
| `rank` | `integer` | 1 = highest value among the compared areas |
| `national_percentile` | `number` | 0-100: share of all areas of this type nationally with a lower value |
| `n_peers` | `integer` |  |

## 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.

### Three police stations on one metric

Request:

```json
{
  "area_ids": [
    "saps:vredendal",
    "saps:clanwilliam",
    "saps:vanderbijlpark"
  ],
  "metrics": [
    "crime_count:murder"
  ]
}
```

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.",
    "national_percentile ranks each area among all areas of the same type in the loaded data for that period (100 = highest).",
    "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",
  "comparisons": [
    {
      "metric_id": "crime_count:murder",
      "unit": "count",
      "period": "FY2024/25",
      "area_type": "police_station",
      "spatial_aggregation": "sum",
      "entries": [
        {
          "area_id": "saps:vredendal",
          "area_name": "Vredendal",
          "value": 14.0,
          "rank": 2,
          "national_percentile": 75.0,
          "n_peers": 5
        },
        {
          "area_id": "saps:clanwilliam",
          "area_name": "Clanwilliam",
          "value": 9.0,
          "rank": 3,
          "national_percentile": 50.0,
          "n_peers": 5
        },
        {
          "area_id": "saps:vanderbijlpark",
          "area_name": "Vanderbijlpark",
          "value": 61.0,
          "rank": 1,
          "national_percentile": 100.0,
          "n_peers": 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 |
|---|---|
| `{"area_ids": ["saps:vredendal"], "metrics": ["crime_count:murder"]}` | `INVALID_ARGUMENT: area_ids: List should have at least 2 items after validation, not 1. Fix: Correct the compare_areas arguments. 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}. Call describe_catalog to see valid metrics and geographies.` |