describe_catalog

{}

{
  "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"
    },
    {
      "source_id": "mdb_wards_2026",
      "name": "[FIXTURE] MDB Wards 2026",
      "publisher": "Municipal Demarcation Board (MDB)",
      "url": "https://www.demarcation.org.za/",
      "licence": "MDB custom terms",
      "commercial_use": "unclear",
      "attribution": "Source: Municipal Demarcation Board (MDB)",
      "retrieved_at": "2026-11-05",
      "dataset_version": "fixture-2026.11.05"
    },
    {
      "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"
    },
    {
      "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"
    },
    {
      "source_id": "osm_geofabrik_za",
      "name": "[FIXTURE] OpenStreetMap South Africa (Geofabrik) facility points",
      "publisher": "OpenStreetMap contributors; extract by Geofabrik GmbH",
      "url": "https://download.geofabrik.de/africa/south-africa-latest.osm.pbf",
      "licence": "ODbL-1.0",
      "commercial_use": "yes",
      "attribution": "© OpenStreetMap contributors. Data under the Open Database Licence (ODbL 1.0).",
      "retrieved_at": "2026-11-05",
      "dataset_version": "fixture-2026.11.05"
    },
    {
      "source_id": "treasury_municipal_finance",
      "name": "[FIXTURE] National Treasury Municipal Money",
      "publisher": "National Treasury",
      "url": "https://municipaldata.treasury.gov.za/api/cubes",
      "licence": "National Treasury Municipal Money Terms of Use v1.0",
      "commercial_use": "unclear",
      "attribution": "National Treasury, Municipal Money (municipalmoney.gov.za)",
      "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.",
    "Licence note (mdb_wards_2026): MDB custom terms; commercial use 'unclear'. Served only as derived aggregates with attribution: Source: Municipal Demarcation Board (MDB)",
    "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",
    "Licence note (treasury_municipal_finance): National Treasury Municipal Money Terms of Use v1.0; commercial use 'unclear'. Served only as derived aggregates with attribution: National Treasury, Municipal Money (municipalmoney.gov.za)"
  ],
  "dataset_version": "fixture-2026.11.05",
  "metrics": [
    {
      "id": "population_total",
      "label": "Total population",
      "description": "Estimated resident population of the area for a year, from WorldPop 100 m gridded population summed over the area polygon. Use for \"how many people live in X\".",
      "unit": "people",
      "kind": "count",
      "spatial_aggregation": "sum",
      "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": [
        "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."
      ]
    },
    {
      "id": "population_density_km2",
      "label": "Population density",
      "description": "Estimated people per square kilometre (population_total / area_km2). A ratio: combining several areas uses the area-weighted mean, which equals total people / total area.",
      "unit": "people/km2",
      "kind": "ratio",
      "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": [
        "Derived from a modelled population estimate divided by polygon area.",
        "Density over a large rural municipality hides strong local variation."
      ]
    }
  ],
  "geographies": [
    {
      "area_type": "province",
      "label": "Province",
      "id_format": "prov:<code>",
      "example": "prov:WC"
    },
    {
      "area_type": "district",
      "label": "District / metropolitan municipality",
      "id_format": "dm:<code>",
      "example": "dm:DC1"
    }
  ],
  "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
  },
  "how_to": [
    "1. resolve_location('<place>') to get an area_id (never guess ids).",
    "2. query_metrics(metrics=[...], area_ids=[...], year_from, year_to)."
  ]
}