get_provenance
Where a metric comes from: publisher, licence, retrieval date, dataset version, method and lineage.
Where a metric comes from: publisher, licence, retrieval date, dataset version, method and lineage. Free (does not count against your plan).
Counts against your plan: no, free. Read-only: yes, nothing you send is stored or changes any data.
Inputs
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
metric_id | string | yes | none | Metric id, e.g. 'rainfall_annual_mm' or 'crime_count:murder' |
Caps
No row or area caps apply: the response is a fixed-size summary.
Response
Every response also carries citations, caveats and dataset_version (Citations).
| Field | Type | Description |
|---|---|---|
citations | object[] | |
caveats | string[] | |
dataset_version | string | |
metric | object | |
lineage | string[] | |
sources | object[] |
metric
| Field | Type | Description |
|---|---|---|
id | string | |
label | string | |
description | string | |
unit | string | |
kind | string | |
spatial_aggregation | string | |
native_geographies | string[] | |
allowed_geographies | string[] | |
time_grain | string | |
time_rollups | object | |
period_format | string | |
first_period | string | |
last_period | string | |
available_ids | string[] | Concrete ids for metric families |
family_members | object[] | |
caveats | string[] |
sources[] (each item)
| Field | Type | Description |
|---|---|---|
source_id | string | |
name | string | |
publisher | string | |
url | string | |
licence | string | |
commercial_use | string | |
attribution | string | |
retrieved_at | string | |
dataset_version | string |
metric.family_members[] (each item)
| Field | Type | Description |
|---|---|---|
id | string | |
label | string | |
is_aggregate | boolean | SAPS roll-up category: never add it to its component offences |
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.
Where a rainfall metric comes from
Request:
{
"metric_id": "rainfall_annual_mm"
}Response: (lists shortened)
{
"citations": [
{
"source_id": "chirps_rainfall",
"name": "[FIXTURE] CHIRPS v3.0 Monthly Rainfall",
"publisher": "Climate Hazards Center, UC Santa Barbara",
"url": "https://www.chc.ucsb.edu/data/chirps3",
"licence": "CC-BY-4.0",
"commercial_use": "yes",
"attribution": "Funk et al., CHIRPS v3.0, Climate Hazards Center, UCSB.",
"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.",
"Satellite-derived estimate (CHIRPS ~5 km grid), averaged over the area; not a rain-gauge reading.",
"rainfall_annual_mm values are modelled or satellite estimates."
],
"dataset_version": "fixture-2026.11.05",
"metric": {
"id": "rainfall_annual_mm",
"label": "Annual rainfall",
"description": "Total rainfall in the calendar year (mm), averaged over the area. Areas combine by area-weighted mean, never by adding.",
"unit": "mm",
"kind": "mean",
"spatial_aggregation": "area_weighted_mean",
"native_geographies": [
"ward",
"local_municipality",
"district",
"province"
],
"allowed_geographies": [
"ward",
"local_municipality",
"district",
"province"
],
"time_grain": "year",
"time_rollups": {},
"period_format": "YYYY",
"first_period": "2020",
"last_period": "2025",
"available_ids": [],
"family_members": [],
"caveats": [
"Satellite-derived estimate (CHIRPS ~5 km grid), averaged over the area; not a rain-gauge reading."
]
},
"lineage": [
"Raw files from Climate Hazards Center, UC Santa Barbara are retrieved by the ingest job and stored unchanged with retrieval date and checksum.",
"Cleaned and conformed to the MDB 2026 ward/municipality/province and SAPS precinct geography in DuckDB (transform/).",
"Stored in gold `fact` at native geography ['ward', 'local_municipality', 'district', 'province'] (methods: zonal_mean).",
"Served by the semantic layer: combining areas uses area_weighted_mean."
],
"sources": [
{
"source_id": "chirps_rainfall",
"name": "[FIXTURE] CHIRPS v3.0 Monthly Rainfall",
"publisher": "Climate Hazards Center, UC Santa Barbara",
"url": "https://www.chc.ucsb.edu/data/chirps3",
"licence": "CC-BY-4.0",
"commercial_use": "yes",
"attribution": "Funk et al., CHIRPS v3.0, Climate Hazards Center, UCSB.",
"retrieved_at": "2026-11-05",
"dataset_version": "fixture-2026.11.05"
}
]
}Provenance in this example: source chirps_rainfall, licence “CC-BY-4.0”, 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 |
|---|---|
{"metric_id": "no_such_metric"} | UNKNOWN_METRIC: Unknown metric 'no_such_metric'. Fix: Use one of ['population_total', 'population_density_km2', 'rainfall_monthly_mm', 'rainfall_annual_mm', 'crime_count:{category}', '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']. Call describe_catalog for details. |