spendinggovua_api

Browser-backed FastAPI service and web UI for extracting reports from spending.gov.ua by EDRPOU, date range, and report form.

The project uses Playwright + Chromium instead of direct requests/curl, because the portal often blocks or breaks plain HTTP clients and headless scraping.

Features

• search reports for one EDRPOU or a batch of EDRPOU codes
• filter by year, date range, report type name, or report type id
• summarize which report forms exist across a group of organizations
• export raw JSON report payloads into ZIP archives
• render individual reports as readable HTML tables
• generate PDF versions of individual reports
• batch-export all available Form 2 reports for a predefined EDRPOU list

API

• GET /
• GET /health
• GET /api/catalog/{edrpou}
• POST /api/reports/search
• POST /api/report-types/summary
• GET /api/reports/{edrpou}/{report_id}/html
• GET /api/reports/{edrpou}/{report_id}/pdf
• POST /api/reports/export/zip

Local Run

uv venv
.venv\Scripts\activate
uv pip install -e .
python -m playwright install chromium
uvicorn spendinggovua_api.main:app --reload

After startup:

• UI: http://127.0.0.1:8000/
• Swagger: http://127.0.0.1:8000/docs
• OpenAPI JSON: http://127.0.0.1:8000/openapi.json

Package Usage

After installation, two CLI commands are available:

spendinggovua-api
spendinggovua-form2-export

You can also run the API as a module:

python -m spendinggovua_api

Build The Package

uv build

Artifacts are written to dist/.

Examples

Search reports:

{
  "edrpous": ["43861328", "02125473"],
  "report_types": ["Форма № 2"],
  "date_from": "2021-01-01",
  "date_to": "2025-12-31",
  "include_details": false
}

Summarize available forms:

{
  "edrpous": ["43861328", "02125473", "02071033"]
}

Single report HTML and PDF:

/api/reports/43861328/1701610529/html
/api/reports/43861328/1701610529/pdf

ZIP Export

POST /api/reports/export/zip returns:

• manifest.json in the archive root
• one folder per EDRPOU
• index.json and report files when reports were found
• no_reports.json when no reports matched the filters
• error.json when the source portal failed for that EDRPOU

Example request:

{
  "edrpous": ["43861328", "02125473"],
  "report_types": ["Форма № 2"],
  "include_details": true,
  "latest_only_per_edrpou": false
}

HTML and PDF Rendering

For a concrete reportId, the service can build:

• HTML with the report header and table layout
• PDF generated by Chromium from the same HTML

This is useful when you need a readable document instead of only raw JSON cells.

Batch Form 2 Archive

To build one archive with all available Form 2 reports for the predefined EDRPOU list:

.venv\Scripts\python scripts\export_form2_html_zip.py

The script writes the resulting ZIP archive to output/.

Delivery Bundle

To assemble the package artifacts, GitHub description draft, Dockerfile, and the batch Form 2 archive into one distributable ZIP:

.venv\Scripts\python scripts\build_delivery_bundle.py

The resulting bundle is written to release/.

License

This project is distributed under the MIT License. See LICENSE.

Important: the MIT license applies to the source code in this repository. It does not automatically change the legal status of data or content obtained from spending.gov.ua, which may be subject to separate terms or source licensing.

Project Layout

• spendinggovua_api/main.py - FastAPI app and HTTP routes
• spendinggovua_api/spending_client.py - browser-backed access to spending.gov.ua
• spendinggovua_api/report_render.py - HTML rendering for report pages
• spendinggovua_api/zip_export.py - ZIP archive builder for JSON exports
• spendinggovua_api/batch_export.py - reusable batch export helper for Form 2 archives
• spendinggovua_api/static/index.html - web UI
• spendinggovua_api/static/app.js - frontend logic
• spendinggovua_api/static/app.css - frontend styling
• scripts/export_form2_html_zip.py - convenience script for the batch Form 2 archive
• Dockerfile - container runtime setup