71point4 > Projects > South African council on cities data codebook

Developing a codebook of common indicators for South African cities

South African Cities Network (SACN)


Data Documentation Initiative, Integrated Development Plans, Built Environment Performance Plans, Service Delivery Budget Implementation Plans, National Treasury MFMA Circular 88, Stats SA surveys and periodic publications, AGSA, Department of Basic Education, Department of Energy


Designed a codebook in human and machine readable format

Developed a user guide for easy maintenance of codebook

Analysed data availability and requirements across SACN member cities

Developed and refined SACN city performance indicators


The objective of the project was to develop a codebook of common indicators for South African Cities that

  • Synthesizes the data needs of the cities, national and provincial government, and the South African Council on Cities Data;
  • Is characterized by indicators that cover all city reporting requirements and reinforce our understanding of urban development;
  • Contains detailed metadata that conforms with the open data format and affords full comprehension of each indicator, its sub-components, and its relation to the development and planning environment;
  • Assesses and compares the availability of data across cities to identify areas for improved data collection and management.


The first phase of the project involved the development of a database containing available city-level indicators. These include indicators that cities report on themselves (e.g. by way of their SDBIP, IDP, and BEPP publications) and indicators reported on by other entities (e.g. Stats SA population figures, National Treasury’s Local Government Database, and Department of Basic Education’s EMIS database).

In the second phase, this database of available indicators was compared to indicator reporting requirements as contained in National Treasury’s MFMA Circular 88 and the SACN’s State of Cities Report. This comparison was used to identify gaps in the availability of city-level data.

The third phase of the project required the collection of any outstanding metadata related to the indicators. This metadata included definitions, calculations notes and formulas, and data custodian contact information to enable access to the data going forward.

The last phase of the project concerned the development of the codebook in human and machine-readable formats. These characteristics facilitates the integration of the codebook into the South African Cities Open Data Alamanac  whilst still enabling its use as a standard document. To achieve these objectives, the team developed an automated codebook pipeline in R, producing both a JSON and PDF version of  the codebook as well as a codebook user guide to enable easy additions and updates going forward.


This project equipped the team with an in-depth understanding of the data ecosystem within which cities operate including what city-level data is curated by the private and public sector, which frameworks govern cities’ reporting processes, and what performance indicators cities are required to report on.