NAV
JSON

Municipal Money API Documentation

The Municipal Money API publishes the financial information of South African municipalities in a machine-friendly format.

All municipalities must regularly submit financial information to National Treasury who, in partnership with Code for South Africa, make it available to the public through this API.

What data is available

The financial data is very similar to that made available on National Treasury’s website in PDF reports and Excel spreadsheets and generally called Section 71 information. It is described further below and includes:

The data is available for all metro, district and local municipalities.

Where is the data from

The data is composed of the Section 71 submissions from municipalities to the Treasury's Local Government database. The submissions take the shape of return forms in Excel Spreadsheets provided by Treasury to help municipalities validate the data and supply it in a consistent format. It can be helpful to look at the forms to understand the data better.

The data where Amount Type is Audited Actual are audit outcomes as stated by the Auditor General and submitted by the municipality to the Local Government database. National Treasury does extensive verification to ensure that the audit outcomes submitted to the database matches the audited Annual Financial Statements as issued by the Auditor General.

Verifying the data

The treasury publishes quarterly reports based on the municipalities' Section 71 submissions as well as well as reports on municipality financial health using standard indicators based on this data.

It can be useful to verify numbers retrieved from the API against these published reports. This verifies both a correct understanding of how to use the API, and that the API supplies reliable information. When doing so, it is important to be aware that the reports are based on a snapshot of the data at the point in time where they are generated, while the API could contain amended numbers if a municipality updated their submission. The Treasury's reports also fall back to pre-audited and then budget values if audited values are not available at the time of publication. Generally the API can be expected to match the treasury's publications so if one value doesn't match, try checking the same field for other periods and other municipalities to ensure the correct field is being compared. If that is the case, one can investigate further why a specific field doesn't match - perhaps because of the reasons mentioned here.

Export CSV

You can export a subset of the data as CSV if you want to explore that offline. As you explore the data of a cube, you can download the entire dataset matching your current filters showing only the columns you have selected. Once you've narrowed down what you want, click the Download CSV button.

Datasets

Aged Creditor Analysis - aged_creditor

Explore this dataset

Analysis of creditors aggregated by age of debt. Does not include individual creditors.

Submitted to National Treasury using return forms: AC, ACA.

Items

CodeItemComposition
0100 Bulk Electricity
0200 Bulk Water
0300 PAYE deductions
0400 VAT (output less input)
0500 Pensions / Retirement deductions
0600 Loan repayments
0700 Trade Creditors
0800 Auditor General
0900 Other
1000 Total sum(0100, 0200, 0300, 0400, 0500, 0600, 0700, 0800, 0900)
TP01 Top 1 Creditor
TP02 Top 2 Creditor
TP03 Top 3 Creditor
TP04 Top 4 Creditor
TP05 Top 5 Creditor
TP06 Top 6 Creditor
TP07 Top 7 Creditor
TP08 Top 8 Creditor
TP09 Top 9 Creditor
TP10 Top 10 Creditor
TOT Total sum(TP01, TP02, TP03, TP04, TP05, TP06, TP07 TP08 TP09, TP10)

Dimensions and their attributes

Amount Type Whether this figure is actual, budgeted, audited etc.
Code amount_type.code string
Label amount_type.label string
Financial Period The period this figure corresponds to, e.g. the month number of a month within the financial year, or the calendar year end of a financial year.
Period financial_period.period integer
Financial Year The calendar year falling at the end of the financial year
Year End financial_year_end.year integer
Item
Code item.code string Code used by the treasury
Composition item.composition string The composition of this item. Indicates how this item is composed of other items in this cube for the same mnuicipality, financial year and period, and amount type using item codes.
Label item.label string
Position in Return Form item.position_in_return_form integer The position of this item in the Section 71 Return form - useful for sorting line items to be ordered as they are in the return form to group related items and place them below the section headings and above section totals.
Return Form Structure item.return_form_structure string What structural role this line item has in the return form
Municipality Municipality demarcation details
Demarcation Code demarcation.code string Municipality code assigned by the Municipal Demarcation Board
Name demarcation.label string
Period Length The lenfth of the period this figure corresponds to
Length period_length.length string

Aged Debtor Analysis - aged_debtor

Explore this dataset

Analysis of debtors by age of debt. Does not include individual debtors.

Submitted to National Treasury using return forms: AD, ADA.

Items

CodeItemComposition
1100 Debtors Age Analysis By Income Source
1200 Trade and Other Receivables from Exchange Transactions - Water
1300 Trade and Other Receivables from Exchange Transactions - Electricity
1400 Receivables from Non-exchange Transactions - Property Rates
1500 Receivables from Exchange Transactions - Waste Water Management
1600 Receivables from Exchange Transactions - Waste Management
1700 Receivables from Exchange Transactions - Property Rental Debtors
1810 Interest on Arrear Debtor Accounts
1820 Recoverable unauthorised, irregular or fruitless and wasteful Expenditure
1900 Other
2000 Total By Income Source sum(1200, 1300, 1400, 1500, 1600, 1700, 1810, 1820, 1900)
2100 Debtors Age Analysis By Customer Group
2200 Organs of State
2300 Commercial
2400 Households
2500 Other
2600 Total By Customer Group sum(2200, 2300, 2400, 2500)

Dimensions and their attributes

Amount Type Whether this figure is actual, budgeted, audited etc.
Code amount_type.code string
Label amount_type.label string
Customer Group Debtor organs of state
Code customer_group.code string Code used by treasury
Financial Period The period this figure corresponds to, e.g. the month number of a month within the financial year, or the calendar year end of a financial year.
Period financial_period.period integer
Financial Year The calendar year falling at the end of the financial year
Year End financial_year_end.year integer
Item
Code item.code string Code used by treasury
Composition item.composition string The composition of this item. Indicates how this item is composed of other items in this cube for the same mnuicipality, financial year and period, and amount type using item codes.
Label item.label string
Position in Return Form item.position_in_return_form integer The position of this item in the Section 71 Return form - useful for sorting line items to be ordered as they are in the return form to group related items and place them below the section headings and above section totals.
Return Form Structure item.return_form_structure string What structural role this line item has in the return form
Municipality Municipality demarcation details
Demarcation Code demarcation.code string Municipality code assigned by the Municipal Demarcation Board
Name demarcation.label string
Period Length The length of the period this figure corresponds to
Length period_length.length string

Audit Opinions - audit_opinions

Outcomes of financial statement audits from the Auditor General.

Dimensions and their attributes

Financial Year The calendar year falling at the end of the financial year
Year End financial_year_end.year integer
Municipality Municipality demarcation details
Demarcation Code demarcation.code string Municipality code assigned by the Municipal Demarcation Board
Name demarcation.label string
Opinion
Auditor General's Report URL opinion.report_url string
Code opinion.code string
Label opinion.label string

Balance Sheet - bsheet

Explore this dataset

Statement of Financial Position. The assets, liabilities and capital of a municipality at a specific point in time.

Submitted to National Treasury using return forms: BS, BSR, BSAC, BSA.

Items

CodeItemComposition
0100 COMMUNITY WEALTH / EQUITY
0110 Community Wealth
0600 Housing Development Fund
0300 Reserves
0500 Accumulated Surplus/(Deficit)
0680 Minorities Interests
0690 Total Community Wealth / Equity sum(0600, 0300, 0500, 0680)
0700 Non-Current Liabilities
0900 Borrowing
0910 Non-Current Provisions
1000 Total Non-Current Liabilities sum(0900, 0910)
2300 Current Liabilities
2400 Consumer Deposits
2500 Provisions
2600 Creditors
2610 Conditional Grants and Receipts
2700 Bank Overdraft
2800 Borrowing
1600 Total Current Liabilities sum(2400, 2500, 2600, 2610, 2700, 2800)
1650 Total Net Assets and Liabilities sum(0690 1000, 1600)
1100 ASSETS
1200 Non-Current Assets
1300 Property Plant and Equipment
1400 Non-Current Investments
1500 Long-term Receivables
1401 Investment Property
1402 Investment in Associate
1403 Agricultural
1404 Biological
1405 Intangible
1406 Other Non-Current Assets
2900 Total Non-Current Assets sum(1300, 1400, 1500, 1401, 1402, 1403, 1404, 1405, 1406)
1700 Current Assets
2200 Call Investment Deposits
1900 Inventory
2000 Consumer Debtors
2010 Other Debtors
2100 Current Portion Of Long-Term Receivables
1800 Cash
2150 Total Current Assets sum(2200, 1900, 2000, 2010, 2100, 1800)
3000 Total Assets sum(2900, 2150)

Dimensions and their attributes

Amount Type Whether this figure is actual, budgeted, audited etc.
Code amount_type.code string
Label amount_type.label string
Financial Period The period this figure corresponds to, e.g. the month number of a month within the financial year or the calendar year end of a financial year.
Period financial_period.period integer
Financial Year The calendar year falling at the end of the financial year
Year End financial_year_end.year integer
Item
Code item.code string Code used by treasury
Composition item.composition string The composition of this item. Indicates how this item is composed of other items in this cube for the same mnuicipality, financial year and period, and amount type using item codes.
Label item.label string
Position in Return Form item.position_in_return_form integer The position of this item in the Section 71 Return form - useful for sorting line items to be ordered as they are in the return form to group related items and place them below the section headings and above section totals.
Return Form Structure item.return_form_structure string What structural role this line item has in the return form
Municipality Municipality demarcation details
Demarcation Code demarcation.code string Municipality code assigned by the Municipal Demarcation Board
Name demarcation.label string
Period Length The length of the period this figure corresponds to
Length period_length.length string

Capital Acquisition - capital

Explore this dataset

Purchase, repair and renewal of capital assets.

Submitted to National Treasury using return forms: CA, CAR, CAA, CAAA.

Items

CodeItemComposition
0100 INFRASTRUCTURE
0300 Roads, Pavements, Bridges & Storm Water
0400 Water Reservoirs & Reticulation
0500 Car Parks, Bus Terminals and Taxi Ranks
0600 Electricity Reticulation
0700 Sewerage Purification & Reticulation
0800 Housing
0900 Street Lighting
1000 Refuse sites
1100 Gas
1200 Other
1300 Sub-total Infrastructure sum(0300, 0400, 0500, 0600, 0700, 0800, 0900, 1000, 1100, 1200)
1400 COMMUNITY
1500 Establishment of Parks & Gardens
1600 Sportsfields
1700 Community Halls
1800 Libraries
1900 Recreational Facilities
2000 Clinics
2100 Museums & Art Galleries
2200 Other
2300 Sub-total Community sum(1500, 1600, 1700, 1800, 1900, 2000, 2100, 2200)
2310 HERITAGE ASSETS
2311 Heritage Assets
2312 Sub-total Heritage Assets 2311
2320 INVESTMENT PROPERTIES
2321 Investment Properties
2322 Sub-total Investment Properties 2321
2400 OTHER ASSETS
2500 Other motor vehicles
2600 Plant & equipment
2700 Office equipment
2800 Abattoirs
2900 Markets
3000 Airports
3100 Security Measures
3110 Civic Land and Buildings
3120 Other Land and Buildings
3200 Other
3300 Sub-total Other Assets sum(2500, 2600, 2700, 2800, 2900, 3000, 3100, 3110, 3120, 3200)
3400 SPECIALISED VEHICLES
3500 Refuse
3600 Fire
3700 Conservancy
3800 Ambulances
3900 Buses
4000 Sub-total Specialised Vehicles sum(3500, 3600, 3700, 3800, 3900)
4010 AGRICULTURAL ASSETS
4011 Agricultural Assets
4012 Sub-total Agricultural Assets 4011
4020 BIOLOGICAL ASSETS
4021 Biological Assets
4022 Sub-total Biological Assets 3021
4030 INTANGIBLES
4031 Intangibles
4032 Sub-total Intangibles 4031
4100 TOTAL sum(1300, 2300, 2312, 2322, 3300, 4000, 4012, 4022, 4032)
4200 SOURCE OF FINANCE
4300 External Loans
4400 Asset Financing Reserve
4500 Surplus Cash
4600 Public contributions/ donations
4700 National Government Transfers and Grants
4701 Provincial Government Transfers and Grants
4702 District Municipality Transfers and Grants
4703 Other Transfers and Grants
4800 Leases
5000 Other
5100 TOTAL FINANCING sum(4300, 4400, 4500, 4600, 4700, 4701, 4702, 4703, 4800, 5000)

Dimensions and their attributes

Amount Type Whether this figure is actual, budgeted, audited etc.
Code amount_type.code string
Label amount_type.label string
Financial Period The period this figure corresponds to, e.g. the month number of a month within the financial year or the calendar year end of a financial year.
Period financial_period.period integer
Financial Year The calendar year falling at the end of the financial year
Year End financial_year_end.year integer
Function Function of government classification adapted from International Monetary Fund's Government Financial Statistics manual.
Code function.code string Code used by treasury
Label function.label string
Item
Code item.code string Code used by treasury
Composition item.composition string The composition of this item. Indicates how this item is composed of other items in this cube for the same mnuicipality, financial year and period, and amount type using item codes.
Label item.label string
Position in Return Form item.position_in_return_form integer The position of this item in the Section 71 Return form - useful for sorting line items to be ordered as they are in the return form to group related items and place them below the section headings and above section totals.
Return Form Structure item.return_form_structure string What structural role this line item has in the return form
Municipality Municipality demarcation details
Demarcation Code demarcation.code string Municipality code assigned by the Municipal Demarcation Board
Name demarcation.label string
Period Length The length of the period this figure corresponds to
Length period_length.length string

Cash Flow - cflow

Explore this dataset

The movement of cash into and out of the municipality.

Submitted to National Treasury using return forms: CFB, CFR, CFA, CFAA.

Items

CodeItemComposition
3000 Cash Receipts by Source
3010 Property rates
3020 Property rates - penalties & collection charges
3030 Service charges - electricity revenue
3040 Service charges - water revenue
3050 Service charges - sanitation revenue
3060 Service charges - refuse revenue
3070 Service charges - other
3080 Rental of facilities and equipment
3090 Interest earned - external investments
3100 Interest earned - outstanding debtors
3110 Dividends received
3120 Fines
3130 Licences and permits
3140 Agency services
3150 Transfer receipts - operational
3160 Other revenue
3170 Cash Receipts by Source sum(3010, 3020, 3030, 3040, 3050, 3060, 3070, 3080, 3090, 3100, 3110, 3120, 3130, 3140, 3150, 3160)
3180 Other Cash Flows/Receipts by Source
3190 Transfer receipts - capital
3200 Contributions recognised - capital & Contributed assets
3210 Proceeds on disposal of PPE
3220 Short term loans
3230 Borrowing long term/refinancing
3240 Increase (decrease) in consumer deposits
3250 Decrease (Increase) in non-current debtors
3260 Decrease (increase) other non-current receivables
3270 Decrease (increase) in non-current investments
3280 Total Cash Receipts by Source sum(3190, 3200, 3210, 3220, 3230, 3240, 3250, 3260, 3270, 3170)
4000 Cash Payments by Type
4010 Employee related costs
4020 Remuneration of councillors
4030 Collection costs
4040 Interest paid
4050 Bulk purchases - Electricity
4060 Bulk purchases - Water & Sewer
4070 Other materials
4080 Contracted services
4090 Grants and subsidies paid - other municipalities
4100 Grants and subsidies paid - other
4110 General expenses
4120 Cash Payments by Type sum(4010, 4020, 4030, 4040, 4050, 4060, 4070, 4080, 4090, 4100, 4110)
4130 Other Cash Flows/Payments by Type
4140 Capital assets
4150 Repayment of borrowing
4160 Other Cash Flows/Payments
4170 Total Cash Payments by Type sum(4140, 4150, 4160, 4120)
4180 Net Increase/(Decrease) in Cash Held 3280 - 4170
4190 Cash/cash equivalents at the month/year begin:
4200 Cash/cash equivalents at the month/year end: 4180 + 4190
0200 Add : Receipts
1700 - Capital payments
1600 - Cash and creditor payments
2400 Closing Balance
0800 - Consumer deposits
2100 - Consumer deposits repaid
0400 - External loans received
1900 - External loans repaid
0500 - Grants and subsidies
1000 - Insurance claims
1800 - Investments made
0700 - Investments redeemed
1400 Less : Payments
0100 Opening Cash Balance
1200 - Other
2200 - Other payments
0600 - Public donations
0900 - Receipts from long-term debtors
0300 - Revenue receipts (incl consumer debtors)
1500 - Salaries wages and allowances
2000 - Statutory Payments (incl VAT)
1100 - Statutory Receipts (incl VAT)
2300 Sub-Total (Payments)
1300 Sub-Total (Receipts)

Dimensions and their attributes

Amount Type Whether this figure is actual, budgeted, audited etc.
Code amount_type.code string
Label amount_type.label string
Financial Period The period this figure corresponds to, e.g. the month number of a month within the financial year or the calendar year end of a financial year.
Period financial_period.period integer
Financial Year The calendar year falling at the end of the financial year
Year End financial_year_end.year integer
Item
Code item.code string Code used by treasury
Composition item.composition string The composition of this item. Indicates how this item is composed of other items in this cube for the same mnuicipality, financial year and period, and amount type using item codes.
Label item.label string
Position in Return Form item.position_in_return_form integer The position of this item in the Section 71 Return form - useful for sorting line items to be ordered as they are in the return form to group related items and place them below the section headings and above section totals.
Return Form Structure item.return_form_structure string What structural role this line item has in the return form
Municipality Municipality demarcation details
Demarcation Code demarcation.code string Municipality code assigned by the Municipal Demarcation Board
Name demarcation.label string
Period Length The length of the period this figure corresponds to
Length period_length.length string

Conditional Grants - conditional_grants

Details of grants received from national government.

Submitted to National Treasury using return forms: Form for each grant.

Dimensions and their attributes

Amount Type Whether this figure is actual, budgeted, audited etc.
Code amount_type.code string
Label amount_type.label string
Financial Period The period this figure corresponds to, e.g. the month number of a month within the financial year or the calendar year end of a financial year.
Period financial_period.period integer
Financial Year The calendar year falling at the end of the financial year
Year End financial_year_end.year integer
Grant
Code grant.code string
Label grant.label string
Municipality Municipality demarcation details
Demarcation Code demarcation.code string Municipality code assigned by the Municipal Demarcation Board
Name demarcation.label string
Period Length The length of the period this figure corresponds to
Length period_length.length string

Demarcation Changes - demarcation_changes

Changes to municipality demarcation where at least one municipality was disestablished or newly-established

Dimensions and their attributes

New Demarcation Transition Code new_code_transition.code string The change that occurred to the new municipality for this particular demarcation change.
Date The date the change took place
Date date.date date
New demarcation New municipality demarcation details
Demarcation Code new_demarcation.code string Municipality code assigned by the Municipal Demarcation Board
Old demarcation Old municipality demarcation details
Old Demarcation Transition Code old_code_transition.code string The change that occurred to the old municipality for this particular demarcation change.
Old demarcation Old municipality demarcation details
Demarcation Code old_demarcation.code string Municipality code assigned by the Municipal Demarcation Board

Income and Expenditure - incexp

Explore this dataset

Statement of Financial Performance. How a municipality has spent money and received income.

Submitted to National Treasury using return forms: OSB, OSR, OSA, OSAA.

Items

CodeItemComposition
0100 OPERATING REVENUE
0200 Property Rates
0300 Property Rates - Penalties And Collection Charges
0400 Service Charges
0700 Rent Of Facilities And Equipment
0800 Interest Earned - External Investments
1000 Interest Earned - Outstanding Debtors
1100 Dividends Received
1300 Fines
1400 Licenses and Permits
1500 Agency Services
1600 Transfers Recognised - Operating
1610 Transfers Recognised - Capital
1700 Other Revenue
1800 Gain On Disposal Of Property, Plant & Equipment
1900 Total Operating Revenue Generated sum(0200, 0300, 0400, 0700, 0800, 1000, 1100, 1300, 1400, 1500, 1600, 1610, 1700, 1800)
2000 Less Revenue Foregone
2100 Total Direct Operating Revenue 1900 - 2000 or 1900 + 2000 depending on the sign on 2000 such that 2100 < 1900
2200 INTERNAL TRANSFERS – (must net out with corresp. items under
2300 Interest Received - Internal Loans
2500 Internal Recoveries (Activity Based Costing Etc)
2600 Dividends Received - Internal (From Municipal Entities)
2700 Total Indirect Operating Revenue sum(2300, 2500, 2600)
2800 Total Operating Revenue sum(2100, 2700)
2900 OPERATING EXPENDITURE
3000 Employee Related Costs - Wages & Salaries
3100 Employee Related Costs - Social Contributions
3200 Less Employee Costs Capitalised
3300 Less Employee Costs Allocated To Other Operating Items
3400 Remuneration Of Councillors
3500 Debt Impairment
3600 Collection Costs
3700 Depreciation and Asset Impairment
3900 Interest Expense - External Borrowings
4000 Redemption Payments - External Borrowings (Gamap To Remove)
4100 Bulk Purchases
4110 Other Materials
4200 Contracted Services
4300 Grants and Subsidies
4400 Other Expenditure
4500 Loss On Disposal Of Property, Plant & Equipment
4550 Contributions To/(From) Provisions
4600 Total Direct Operating Expenditure sum(3000, 3100, 3200, 3300, 3400, 3500, 3600, 3700, 3900, 4000, 4100, 4110, 4200, 4300, 4400, 4500, 4550)
4700 INTERNAL TRANSFERS - (must net out with corresp. items under
4800 Interest - Internal Borrowings
5000 Internal Charges (Activity Based Costing Etc)
5010 Contributed Assets
5100 Total Indirect Operating Expenditure sum(4800, 5000, 5010)
5200 Total Operating Expenditure sum(4600, 5100)
5300 SURPLUS
5400 Operating Surplus / (Deficit) - Total Revenue Less Total Exp 2800 - 5200 or 2800 + 5200 depending on the sign on 5200 such that 5400 < 2800
5500 Taxation
5600 Operating Surplus / (Deficit) - After Tax 5400 - 5500 or 5400 + 5500 depending on the sign on 5500 such that 5600 < 5400
5800 Cross Subsidisation
6600 Plus Interests In Entities Not Wholly Owned
5900 Surplus / (Deficit) After Tax, Cross Subsidies & Share Of As sum(5600, 5800, 6600)
6200 OTHER ADJUSTMENTS AND TRANSFERS
5700 Dividends Paid (Municipal Entities Only)
6210 Asset Financing Reserve (Afr)
6220 Housing Development Fund
6230 Depreciation Reserve Ex Afr
6240 Depreciation Reserve Ex Govt Grants
6250 Depreciation Reserve Ex Donations And Contributions
6260 Self-Insurance Reserve
6270 Revaluation Reserve
6280 Other
6700 Change To Unappropriated Surplus / (Accumulated Deficit) sum(5900, 5700, 6210, 6220, 6230, 6240, 6250, 6260, 6270, 6280)

Dimensions and their attributes

Amount Type Whether this figure is actual, budgeted, audited etc.
Code amount_type.code string
Label amount_type.label string
Financial Period The period this figure corresponds to, e.g. the month number of a month within the financial year or the calendar year end of a financial year.
Period financial_period.period integer
Financial Year The calendar year falling at the end of the financial year
Year End financial_year_end.year integer
Government Function Function of government classification adapted from International Monetary Fund's (IMF) Government Financial Statistics (GFS) manual
Category Label function.category_label string
Code function.code string Code used by treasury
Label function.label string
Subcategory Label function.subcategory_label string
Item
Code item.code string Code used by treasury
Composition item.composition string The composition of this item. Indicates how this item is composed of other items in this cube for the same mnuicipality, financial year and period, and amount type using item codes.
Label item.label string
Position in Return Form item.position_in_return_form integer The position of this item in the Section 71 Return form - useful for sorting line items to be ordered as they are in the return form to group related items and place them below the section headings and above section totals.
Return Form Structure item.return_form_structure string What structural role this line item has in the return form
Municipality Municipality demarcation details
Demarcation Code demarcation.code string Municipality code assigned by the Municipal Demarcation Board
Name demarcation.label string
Period Length The lenfth of the period this figure corresponds to
Length period_length.length string

Municipalities - municipalities

General information about the municipality including its geographic location and contact details provided to the National Treasury

Dimensions and their attributes

Municipality
Category municipality.category string
Demarcation Code municipality.demarcation_code string
Fax Number municipality.fax_number string
Long Name municipality.long_name string
MIIF Category municipality.miif_category string
Name municipality.name string
Parent Municipality Code municipality.parent_code string
Phone Number municipality.phone_number string
Postal Address part 1 municipality.postal_address_1 string
Postal Address part 2 municipality.postal_address_2 string
Postal Address part 3 municipality.postal_address_3 string
Province Code municipality.province_code string
Province Name municipality.province_name string
Street Address part 1 municipality.street_address_1 string
Street Address part 2 municipality.street_address_2 string
Street Address part 3 municipality.street_address_3 string
Street Address part 4 municipality.street_address_4 string
URL municipality.url string

Municipal Officials - officials

Names and contact information for high level municipality staff

Dimensions and their attributes

Contact Details
Email Address contact_details.email_address string
Fax Number contact_details.fax_number string
Name contact_details.name string
Phone Number contact_details.phone_number string
Title contact_details.title string
Municipality
Demarcation Code municipality.demarcation_code string
Role
Role role.role string

Repairs and Maintenance - repmaint

Explore this dataset

Money spent on repairs and maintenance of assets.

Items

CodeItemComposition
5001 Employee Related Costs
5002 Other Materials
5003 Contracted Services
5004 Other Expenditure
5005 Total Repairs and Maintenance Expenditure sum(5001, 5002, 5003, 5004)

Dimensions and their attributes

Amount Type Whether this figure is actual, budgeted, audited etc.
Code amount_type.code string
Label amount_type.label string
Financial Period The period this figure corresponds to, e.g. the month number of a month within the financial year or the calendar year end of a financial year.
Period financial_period.period integer
Financial Year The calendar year falling at the end of the financial year
Year End financial_year_end.year integer
Item
Code item.code string Code used by treasury
Composition item.composition string The composition of this item. Indicates how this item is composed of other items in this cube for the same mnuicipality, financial year and period, and amount type using item codes.
Label item.label string
Position in Return Form item.position_in_return_form integer The position of this item in the Section 71 Return form - useful for sorting line items to be ordered as they are in the return form to group related items and place them below the section headings and above section totals.
Return Form Structure item.return_form_structure string What structural role this line item has in the return form
Municipality Municipality demarcation details
Demarcation Code demarcation.code string Municipality code assigned by the Municipal Demarcation Board
Name demarcation.label string
Period Length The length of the period this figure corresponds to
Length period_length.length string

Unauthorised, Irregular, Fruitless and Wasteful Expenditure - uifwexp

Explore this dataset

Specific expenditure amounts from audited financial results, recorded in the notes to the annual financial statements.

Items

CodeItemComposition
fruitless Fruitless and Wasteful Expenditure
irregular Irregular Expenditure
unauthorised Unauthorised Expenditure

Dimensions and their attributes

Financial Year The calendar year falling at the end of the financial year
Year End financial_year_end.year integer
Item
Code item.code string 'unauthorised', 'irregular' or 'fruitless' which stands for Fruitless and Wasteful
Label item.label string
Municipality Municipality demarcation details
Demarcation Code demarcation.code string Municipality code assigned by the Municipal Demarcation Board
Name demarcation.label string

Using the API

The API endpoint is http://municipaldata.treasury.gov.za/api

The API only supports GET requests. Successful responses have response code 200 and are in JSON format.

How the API works

The API is a simple OLAP-style interface.

Each dataset (income and expenditure, balance sheet, etc.) is called a cube. You can think of a cube as a simple (but very big) spreadsheet. Each fact in the cube is a row in our spreadsheet that has dimensions and measures. Dimensions are labels such as municipality, year, month or function code. Measures are monetary amounts in South African Rands.

You can use the API to list available cubes and get metadata about a cube that describes its attributes and values. You can also use the API to filter or cut, sort and aggregate facts in a cube.

The API is very similar to a pivot table in a spreadsheet. It lets you slice, dice and aggregate values to make sense of a vast amount of information.

Pagination

Pagination is important to make sure the client and server handle a mangeable amount of data at a time. The result of a query may be broken up into multiple pages. By default, a maximum of 10 000 items are returned per page. The response includes information on the page size, current page, and total number of results to assist with pagination. If the page size is smaller than the total_fact_count or total_cell_count of a given query (depending on the kind of query), you might want to request the remaining pages and collect the results client-side.

{
  "page": 2,
  "page_size": 100,
  "total_member_count": 152,
  ...
}
    

You can paginate through results using these query parameters:

Parameter Default Description
pagesize 10000 Maximum number of items per page.
page 1 The page number to fetch, starting with page 1.

Cut (filter)

...
"cell": [
  {
    "ref": "item.code",
    "value": "3010",
    "operator": ":"
  },
  {
    "ref": "municipality.code",
    "value": "BUF",
    "operator": ":"
  },
],
"cells": [
  {
    "item.code": "3010",
    "amount.sum": 6256185,
    "financial_period.period": 8
  },
...
    

Use the parameter cut with values key:value to restrict values to a subset of the cube. This is called cutting the cube into cells. Separate multiple cuts with vertical bar e.g. cut=item.code:"3010"|municipality.code:"BUF"

String values must be quoted with double quotes

GET /cubes/<name>/facts?cut=item.code:"3010"|municipality.code:"BUF"

Key Type Example value
dimension.attribute integer 11
string "BUF"

Sorting

Use the parameter order to sort the returned values. Separate multiple sorting dimensions with comma e.g. order=financial_year_end.year:desc,amount_type.code:asc

The results will be primarily sorted according to the first argument; within that, it is sorted according to the second argument, etc. That means it's equivalent to a stable sort performed in reverse order of the arguments.

Queries on Cubes

List Cubes

GET https://municipaldata.treasury.gov.za/api/cubes

(loading...)

Lists all available cubes (datasets).

Get a Cube's Model

GET https://municipaldata.treasury.gov.za/api/cubes/<name>/model

GET https://municipaldata.treasury.gov.za/api/cubes/incexp/model

GET /cubes/incexp/model
{
  "status": "ok",
  "model": {
    "description": "a.k.a. Financial Performance. Financial obligations in and out.",
    "update_cycle": "quarter",
    "last_updated": "2016-06",
    "dimensions": {
      "function": {
        "description": "Function",
        "hierarchy": "function",
        "key_attribute": "code",
        "key_ref": "function.code",
        "cardinality": 55,
        "label_attribute": "desc",
        "cardinality_class": "medium",
        "label_ref": "function.desc",
        "label": "Function",
        "attributes": {
          "code": {
            "column": "function_cde",
            "ref": "function.code",
            "type": "string",
            "description": "some description",
            "label": "Code"
          },
          "desc": {
            "column": "function_desc",
            "ref": "function.desc",
            "type": "string",
            "description": "some description",
            "label": "Description"
          }
        },
        "ref": "function"
      },
      ...
    

Returns a description of the cube. The metadata includes attributes, measures, dimensions, aggregates etc.

update_cycle indicates how frequently you can expect later data and corrections in this dataset

last_updated is a partial ISO 8601 date indicating the date of the latest update. E.g. 2016-06 means the financial year 2015-2016 4th Quarter updates have been applied, which happen some time after it's actually 2016-06. Note that due to the time it takes to verify and submit data, the latest data in a given dataset lags behind that dataset's date.

List Facts

GET /cubes/incexp/facts?pagesize=2
{
  "total_fact_count": 463171,
  "status": "ok",
  "page": 1,
  "fields": [
    "period_length.length",
    "financial_year_end.year",
    "financial_period.period",
    "function.desc",
    "function.code",
    "amount_type.desc",
    "amount_type.code",
    "incexp.desc",
    "incexp.code",
    "demarcation.desc",
    "demarcation.code",
    "amount"
  ],
  "cell": [],
  "page_size": 2,
  "order": [],
  "data": [
    {
      "financial_year_end.year": 2015,
      "amount_type.code": "ACT",
      "amount": null,
      "incexp.code": "1500",
      "amount_type.desc": "Actual",
      "demarcation.desc": "Buffalo City",
      "function.code": "191",
      "incexp.desc": "Agency Services",
      "period_length.length": "month",
      "demarcation.code": "BUF",
      "function.desc": "Budget & Treasury Office/Not Required",
      "financial_period.period": "01"
    },
    {
      "financial_year_end.year": 2015,
      "amount_type.code": "ACT",
      "amount": null,
      "incexp.code": "1500",
      "amount_type.desc": "Actual",
      "demarcation.desc": "City of Cape Town",
      "function.code": "191",
      "incexp.desc": "Agency Services",
      "period_length.length": "month",
      "demarcation.code": "CPT",
      "function.desc": "Budget & Treasury Office/Not Required",
      "financial_period.period": "01"
    }
  ]
}
    

GET https://municipaldata.treasury.gov.za/api/cubes/<name>/facts

GET https://municipaldata.treasury.gov.za/api/cubes/incexp/facts?pagesize=5

Get individual entries from a cube in a non-aggregated form.

Query String Parameters

Parameter Default Description
cut See filters (cut)
page See pagination
pagesize See pagination
order See sorting
format json Determines whether output is in json or csv format.

List Members

GET /cubes/incexp/members/demarcation?pagesize=3
{
  "status": "ok",
  "page": 1,
  "fields": [
    "demarcation.desc",
    "demarcation.code"
  ],
  "cell": [],
  "page_size": 10000,
  "total_member_count": 3,
  "data": [
    {
      "demarcation.code": "BUF",
      "demarcation.desc": "Buffalo City"
    },
    {
      "demarcation.code": "CPT",
      "demarcation.desc": "City of Cape Town"
    },
    {
      "demarcation.code": "JHB",
      "demarcation.desc": "City of Johannesburg"
    },
  ],
  "order": []
}
    

GET https://municipaldata.treasury.gov.za/api/cubes/<name>/members/<member_name>

GET https://municipaldata.treasury.gov.za/api/cubes/incexp/members/demarcation

GET https://municipaldata.treasury.gov.za/api/cubes/incexp/members/demarcation.label

GET https://municipaldata.treasury.gov.za/api/cubes/incexp/members/demarcation?cut=financial_year_end.year:2016

Get distinct values for a given member (dimension) of a cube. For example, all the suppliers in a procurement dataset.

URL Parameters

Parameter Description
name Name of the cube
member_name Name of of a dimension or attribute

Query String Parameters

Parameter Default Description
cut See filters (cut)
page See pagination
pagesize See pagination
order See sorting
format json Determines whether output is in json or csv format.

Aggregating Facts

GET /api/cubes/incexp/aggregate

{
  "cell": [],
  "status": "ok",
  "page_size": 10000,
  "attributes": [],
  "total_cell_count": 1,
  "cells": [
    {
      "amount.sum": 17427626659163,
      "_count": 463171
    }
  ],
  "order": [],
  "aggregates": [
    "_count",
    "amount.sum"
  ],
  "page": 1,
  "summary": {
    "amount.sum": 17427626659163,
    "_count": 463171
  }
}
    

GET https://municipaldata.treasury.gov.za/api/cubes/<name>/aggregate

GET https://municipaldata.treasury.gov.za/api/cubes/incexp/aggregate?drilldown=demarcation.code|demarcation.label|item.code|item.label|item.return_form_structure&cut=financial_year_end.year:2015|amount_type.code:AUDA|financial_period.period:2015|demarcation.code:"TSH"&aggregates=amount.sum

GET https://municipaldata.treasury.gov.za/api/cubes/incexp/aggregate?drilldown=demarcation.code|demarcation.label|item.code|item.label|function.code|function.label|item.return_form_structure&cut=financial_year_end.year:2015|amount_type.code:AUDA|financial_period.period:2015|demarcation.code:"TSH"|item.code:"2800";"5200"&aggregates=amount.sum

Returns aggregate views of the facts in a cube.

Query String Parameters

Parameter Default Description
cut See filters (cut)
aggregates _count and the sum of each measure. Aggregates to include. Cube Measure refs followed by .sum are currently supported, separated by |
drilldown none Drilldowns to aggregate by. Dimension attribute refs separated by |
page See pagination
pagesize See pagination
order See sorting
format json Determines whether output is in json or csv format.

Best Practises

For the best possible experience using the API, follow these best practises:

Getting Help

You can get help with the API at helpdesk@municipalmoney.gov.za

Fork me on GitHub