Portal da Transparência SP: a research skill for São Paulo state data

TL;DR

• The skill is a Python CLI, standard library only, covering every section of the menu of transparencia.sp.gov.br: the structured APIs, the sections that have none, and the systems of origin behind them.
• Ten areas have a structured API: expenses, contracts, bids, sanctions, agreements, amendments, payroll, per diems, outsourced staff and works plus interns.
• The rest are navigation and download sections — planning and budget, revenue through Power BI and Sigeo, investments as PDF/XLSX/CSV, governance, social participation, reports, open data through CKAN, and stalled works through Pentaho.
• Every answer comes with the source system, because the same number exists in Contratos.gov, Sigeo, SIAF or CKAN and the difference between them is what usually confuses the reading.

What it is and who it is for

Portal da Transparência SP is a research skill for the São Paulo state transparency portal, with a Python CLI that uses only the standard library.

It is for the journalist, the analyst and the curious citizen who need a number from the portal and have no idea which of the ten areas it lives in, whether there is an API, or which system of origin produced it. It is also for the person who has already downloaded a CSV and found that the total does not match the page.

The quick commands

S=scripts/sp.py
python3 $S catalogo                 # inventory of areas and endpoints
python3 $S combos obras             # filter options for one area
python3 $S buscar obras --param situacao="Em execução"
python3 $S exportar despesas --tipo csv --param anoExercicio=2024
python3 $S dados-abertos --q transparencia --rows 5
python3 $S self-check               # checks plus live smoke test

The first command is the one to run before anything else: catalogo is an inventory of areas and endpoints, so you can see what has an API before writing a query.

What it covers

Ten areas have a structured API: expenses, contracts, bids, sanctions, agreements, amendments, payroll, per diems, outsourced staff, and works plus interns.

The sections without an API are handled as navigation and downloads: planning and budget, revenue through Power BI and Sigeo, investments as PDF, XLSX and CSV reports, public governance, social participation, reports, open data through CKAN, and stalled works through Pentaho at the TCE.

The README also names the systems of origin, which is the part that turns a number into evidence: Contratos.gov, Sigeo and FlexCons, SIAF and SIAFIC, e-Sanções and SICAF, GMS, Power BI and the TCE.

The 2026 snapshot

The README describes the data as covering 2020 through 2026, with per-diems data for 2026, payroll up to July 2026, and 2026 investment data in the Finance portal. That matters because a total that looks wrong often has a date boundary, not an arithmetic error.

What is inside the repository

SKILL.md holds the routing and the answer rules; references/catalogo.md is the inventory by section with URLs and systems; references/apis.md holds the body contracts per area, the combo endpoints and the known limits; references/paineis.md covers the Power BI, Sigeo, TCE and download panels.

Tests

python3 scripts/sp.py self-check   # offline plus live smoke test on /Sancoes/Buscar

The CI workflow runs the self-check on every push, which is what keeps a live-endpoint skill honest — a portal changes and the check is what tells you before a user does.

When to use it, when not to

Use it when you need a reproducible query across sections you do not know, when you need to know which system produced a figure, or when you want the same answer twice from a CLI rather than a manual click path.

Do not use it as an official portal or as a replacement for one, and do not assume the CLI covers what the portal renders in a chart — the README separates the two, and for totals, charts, hierarchies, documents and details outside the JSON, you follow the portal in the browser.

Sources

1. Portal da Transparência SP — repository — areas with API, sections without, systems of origin, commands, references and tests quoted above.
2. README.md — quick usage, coverage, references, license (MIT).

Project page: Portal da Transparência SP

The skill is MIT-licensed. For the Paraná portal, see the Portal da Transparência PR skill, and for the federal portal, the Portal da Transparência skill.

FAQ

Does it need an API key? The README documents the structured APIs of the ten areas and does not mention a required key; it also names which sections have no API at all.

Which areas have a structured API? Expenses, contracts, bids, sanctions, agreements, amendments, payroll, per diems, outsourced staff, works, and interns.

Can it read revenue? Revenue is one of the sections without an API: it goes through Power BI and Sigeo, and the README points to the panel reference.

How do I know a number is current? Check the area and the date in the README's 2026 snapshot, and follow the source system named for each area.