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. 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).
| 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:
{
"area_ids": [
"saps:vredendal",
"saps:clanwilliam",
"saps:vanderbijlpark"
],
"metrics": [
"crime_count:murder"
]
}Response:
{
"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 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. |