API w systemach BO - jak udostępniać dane mediom i organizacjom

Q: API w systemach BO - jak udostępniać dane mediom i organizacjom?

Przewodnik po API dla Budżetu Obywatelskiego. Open data, integracje z mediami lokalnymi, formaty danych, autoryzacja, bezpieczeństwo i dobre praktyki z polskich miast.

Otwarte dane (open data) to standard nowoczesnej administracji publicznej. API w systemie Budżetu Obywatelskiego pozwala mediom, badaczom i organizacjom pozarządowym korzystać z danych w czasie rzeczywistym — tworzyć własne wizualizacje, analizować partycypację i monitorować proces. W Polsce z publicznych API korzysta już ponad 30 miast, a wymóg otwartości danych wynika wprost z ustawy o otwartych danych i ponownym wykorzystywaniu informacji sektora publicznego (2021).

Dlaczego API dla Budżetu Obywatelskiego jest ważne?

Transparentność procesu

Budżet Obywatelski opiera się na zaufaniu mieszkańców do procesu. Otwarte API buduje to zaufanie na kilku poziomach:

Dane dostępne dla każdego — nie trzeba składać wniosku o dostęp do informacji publicznej (art. 10 ustawy o dostępie do informacji publicznej)
Możliwość niezależnej weryfikacji — media i NGO mogą samodzielnie policzyć wyniki na podstawie surowych danych
Archiwum historyczne — API udostępnia dane z poprzednich edycji, umożliwiając analizę trendów
Eliminacja podejrzeń o manipulację — dane publiczne i weryfikowalne

Przykład z Gdańska: W edycji 2024 Gazeta Wyborcza Trójmiasto korzystała z API ARDVote do publikowania wyników głosowania w czasie rzeczywistym na portalu trojmiasto.pl. Publikacja wyników przez niezależne medium zwiększyła zaufanie do procesu — 78% ankietowanych uznało wyniki za wiarygodne (vs. 64% gdy wyniki publikował wyłącznie urząd).

Ekosystem wokół danych BO

Otwarte API tworzy ekosystem wykorzystania danych, który wykracza poza urząd miasta:

Użytkownik	Zastosowanie	Wartość dla BO
Media lokalne	Wizualizacje, rankingi, mapy, relacje na żywo	Promocja BO, wyższa frekwencja
Uczelnie i badacze	Analizy partycypacji, prace naukowe, porównania międzymiastowe	Wiedza o procesie, rekomendacje
NGO i watchdogi	Monitoring realizacji, raporty equity, kontrola społeczna	Zaufanie, rozliczalność
Startupy civic-tech	Aplikacje, dashboardy, boty informacyjne	Innowacja, dotarcie do nowych grup
Inne samorządy	Benchmarking, inspiracje, best practices	Podnoszenie standardów

Wymóg prawny — otwarte dane

Ustawa z dnia 11 sierpnia 2021 r. o otwartych danych i ponownym wykorzystywaniu informacji sektora publicznego nakłada na podmioty publiczne obowiązek udostępniania danych w formatach nadających się do maszynowego przetwarzania. Dane z Budżetu Obywatelskiego — jako informacja publiczna — podlegają tym przepisom.

Kluczowe wymagania:

Dane muszą być udostępniane w formacie otwartym (JSON, CSV, XML — nie PDF!)
Warunki ponownego wykorzystywania muszą być jasno określone
Dane osobowe muszą być usunięte lub zanonimizowane
Dostęp powinien być bezpłatny

Jakie dane udostępniać przez API?

Klasyfikacja danych — trzy poziomy dostępu

Poziom 1: Dane publiczne (bez ograniczeń)

Te dane powinny być dostępne bez rejestracji i bez klucza API:

Lista projektów — nazwa, opis, lokalizacja (adres + współrzędne GPS), kategoria, koszt szacunkowy
Status weryfikacji — dopuszczony do głosowania / odrzucony + uzasadnienie odrzucenia
Wyniki głosowania — liczba głosów na każdy projekt (po zakończeniu głosowania)
Statystyki zbiorcze — frekwencja ogólna, rozkład głosów po dzielnicach, demografie (zagregowane)
Dane historyczne — projekty i wyniki z poprzednich edycji BO
Status realizacji — w przygotowaniu / w trakcie / zrealizowany / opóźniony

Format: JSON (domyślny) + CSV (alternatywny)

Poziom 2: Dane rozszerzone (po rejestracji)

Dostęp po zarejestrowaniu konta i uzyskaniu klucza API:

Szczegółowe statystyki głosowania — rozkład w czasie (głosy per godzina/dzień), kanały głosowania
Dane geograficzne — heat mapa głosów (zagregowana, nie indywidualna), rozkład terytorialny
Historia zmian projektów — modyfikacje opisu, statusu, kosztorysu (audit log)
Dane o realizacji — harmonogram, wykonawca, postęp prac, koszty faktyczne vs. planowane

Format: JSON + GeoJSON (dane geograficzne)

Poziom 3: Dane chronione (NIGDY publicznie)

Te dane NIE mogą być udostępniane przez API — ochrona na mocy RODO:

Dane osobowe głosujących — imię, nazwisko, PESEL, adres
Powiązanie głos-mieszkaniec — kto na co głosował (tajność głosowania)
Dane wnioskodawców bez ich zgody — numer telefonu, email
Logi bezpieczeństwa — próby manipulacji, dane sesji
Surowe dane IP — adresy IP głosujących

Architektura API — projektowanie od podstaw

REST API — rekomendowana architektura

REST (Representational State Transfer) to najczęściej stosowany styl architektoniczny dla API publicznych. Dla systemu BO rekomendujemy następującą strukturę:

Endpointy podstawowe:

GET /api/v1/editions                    — lista edycji BO (2020, 2021, ..., 2025)
GET /api/v1/editions/{year}/projects    — lista projektów w danej edycji
GET /api/v1/projects/{id}               — szczegóły konkretnego projektu
GET /api/v1/editions/{year}/results     — wyniki głosowania
GET /api/v1/editions/{year}/statistics  — statystyki zbiorcze
GET /api/v1/districts                   — lista dzielnic/osiedli z pulami budżetowymi
GET /api/v1/categories                  — lista kategorii projektów

Endpointy rozszerzone (po autoryzacji):

GET /api/v1/editions/{year}/statistics/timeline   — głosy w czasie
GET /api/v1/editions/{year}/statistics/geo         — rozkład geograficzny
GET /api/v1/projects/{id}/history                  — historia zmian
GET /api/v1/projects/{id}/realization              — status realizacji

Formaty danych

Format	Zastosowanie	Content-Type	Kiedy używać
JSON	Domyślny format	application/json	Aplikacje webowe, mobilne
CSV	Eksport tabelaryczny	text/csv	Analiza w Excel, R, Python
GeoJSON	Dane geograficzne	application/geo+json	Mapy, GIS
XML	Legacy integracje	application/xml	Starsze systemy urzędowe

Przykładowa odpowiedź API — projekt BO

{
  "project_id": "BO2025-GDA-0142",
  "edition": 2025,
  "title": "Plac zabaw przy ul. Kwiatowej - Wrzeszcz Górny",
  "description": "Budowa nowoczesnego placu zabaw z elementami sensorycznymi...",
  "category": "infrastruktura_rekreacyjna",
  "district": {
    "id": "wrzeszcz-gorny",
    "name": "Wrzeszcz Górny",
    "budget_pool": 850000
  },
  "location": {
    "address": "ul. Kwiatowa, Gdańsk",
    "lat": 54.3753,
    "lng": 18.5987,
    "parcel_id": "0262.0015.0042"
  },
  "cost_estimated": 285000,
  "cost_actual": null,
  "status": "approved",
  "verification": {
    "formal": "passed",
    "substantive": "passed",
    "date": "2025-08-15"
  },
  "votes": 1247,
  "rank": 3,
  "is_winner": true,
  "realization": {
    "status": "in_progress",
    "start_date": "2026-03-01",
    "estimated_end": "2026-06-30",
    "contractor": "ABC Budowa Sp. z o.o.",
    "progress_percent": 45
  },
  "submitter": {
    "type": "individual",
    "name": null
  },
  "created_at": "2025-06-10T14:30:00Z",
  "updated_at": "2026-03-15T09:00:00Z",
  "_links": {
    "self": "/api/v1/projects/BO2025-GDA-0142",
    "votes": "/api/v1/projects/BO2025-GDA-0142/votes",
    "history": "/api/v1/projects/BO2025-GDA-0142/history",
    "edition": "/api/v1/editions/2025"
  }
}

Paginacja i filtrowanie

Przy setkach projektów, API musi obsługiwać efektywne paginowanie i filtrowanie:

GET /api/v1/editions/2025/projects?
    district=wrzeszcz-gorny&
    category=infrastruktura&
    status=approved&
    min_votes=100&
    sort=votes_desc&
    page=1&
    per_page=20

Parametry filtrowania:

district — filtr po dzielnicy/osiedlu
category — filtr po kategorii projektu
status — filtr po statusie (submitted, approved, rejected, winner)
min_cost, max_cost — zakres kosztowy
min_votes, max_votes — zakres głosów (tylko po zakończeniu głosowania)
sort — sortowanie (votes_desc, cost_asc, title_asc, date_desc)
page, per_page — paginacja (domyślnie 20 wyników na stronę, max 100)

Nagłówki odpowiedzi paginacji:

X-Total-Count: 847
X-Page: 1
X-Per-Page: 20
X-Total-Pages: 43
Link: </api/v1/projects?page=2>; rel="next"

Autoryzacja i limity — ochrona API

Trzy poziomy dostępu

Poziom	Klucz API	Dostęp	Rate limit	Cel
Publiczny	Nie wymagany	Dane podstawowe	100 req/h per IP	Mieszkańcy, szybki wgląd
Zarejestrowany	API key (darmowy)	Dane rozszerzone	1000 req/h	Media, badacze, NGO
Partner	API key + umowa	Pełne dane + webhook	10 000 req/h	Integracje, civic-tech

Proces rejestracji klucza API

Formularz online: nazwa organizacji/osoby, cel wykorzystania danych, email kontaktowy
Automatyczne wygenerowanie klucza API (UUID v4)
Email z kluczem + linkiem do dokumentacji
Monitoring użycia — dashboard z liczbą zapytań, endpointami, błędami

Rate limiting — implementacja

Algorytm: Token bucket (standard) — 1000 tokenów, uzupełnianie 1000/h.

Nagłówki rate limit w odpowiedzi:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 847
X-RateLimit-Reset: 2025-10-15T19:00:00Z

Przekroczenie limitu → HTTP 429 Too Many Requests:

{
  "error": "rate_limit_exceeded",
  "message": "Przekroczono limit zapytań. Spróbuj ponownie po 19:00.",
  "retry_after": 1800
}

Integracja z mediami lokalnymi — praktyczne formaty

Widget embeddowalny, który media mogą osadzić na swoich portalach:

<iframe
  src="https://bo.gdansk.pl/embed/results/2025"
  width="100%" height="500"
  frameborder="0"
  title="Wyniki głosowania BO Gdańsk 2025">
</iframe>

Opcje customizacji widgetu:

?district=wrzeszcz — filtr po dzielnicy
?theme=dark — ciemny motyw (dla portali z ciemnym tłem)
?limit=10 — top 10 projektów
?live=true — aktualizacja co 5 minut podczas głosowania

Przykład wdrożenia: Portal trojmiasto.pl osadził widget wyników BO Gdańsk na stronie głównej podczas głosowania — 12 000 odsłon dziennie, wzrost świadomości o BO wśród czytelników portalu.

Feed RSS/Atom — powiadomienia o zmianach

Kanały RSS pozwalają mediom automatycznie śledzić zmiany w procesie BO:

GET /api/v1/feed/rss — główny feed
GET /api/v1/feed/rss?type=new_projects — nowe projekty
GET /api/v1/feed/rss?type=status_changes — zmiany statusów
GET /api/v1/feed/rss?type=results — wyniki głosowania
GET /api/v1/feed/rss?type=realization — postępy realizacji

Zastosowanie: Dziennikarze portali lokalnych subskrybują feed “status_changes” i automatycznie otrzymują powiadomienie, gdy projekt zmieni status z “w weryfikacji” na “odrzucony” — materiał na artykuł.

Webhook — powiadomienia push dla partnerów

Dla partnerów z umową, system może wysyłać powiadomienia push o kluczowych wydarzeniach:

POST https://partner.example.com/bo-webhook
{
  "event": "voting_started",
  "edition": 2025,
  "data": {
    "start_date": "2025-09-29",
    "end_date": "2025-10-12",
    "projects_count": 612,
    "url": "https://bo.gdansk.pl/glosuj"
  },
  "timestamp": "2025-09-29T00:00:01Z"
}

Dostępne eventy:

projects_submission_opened — otwarcie naboru projektów
projects_submission_closed — zamknięcie naboru
verification_completed — zakończenie weryfikacji
voting_started — start głosowania
voting_ended — koniec głosowania
results_published — publikacja wyników
realization_update — zmiana statusu realizacji projektu

Dokumentacja API — jak ją dobrze napisać

Elementy dobrej dokumentacji

Dokumentacja API dla systemu BO powinna zawierać:

Getting started — szybki start: jak uzyskać klucz, pierwsze zapytanie, interpretacja odpowiedzi
Autentykacja — jak i gdzie podać klucz API (nagłówek Authorization: Bearer <key>)
Endpointy — opis każdego endpointu z parametrami, przykładami i typami danych
Kody błędów — lista kodów HTTP i komunikatów błędów (400, 401, 403, 404, 429, 500)
Limity — rate limity per poziom dostępu
Sandbox — środowisko testowe z danymi fikcyjnymi (nie produkcyjnymi!)
Changelog — historia zmian API (wersjonowanie, deprecation notices)
Przykłady — gotowe snippety w Python, JavaScript, cURL

Narzędzia: OpenAPI/Swagger (standard branżowy), Postman (kolekcje), Redoc (generator dokumentacji)

Wersjonowanie API

API systemu BO powinno być wersjonowane, aby zmiany nie psuły istniejących integracji:

Wersja w URL: /api/v1/projects, /api/v2/projects
Polityka: Nowa wersja minimum 6 miesięcy przed wycofaniem starej
Deprecation header: Sunset: Sat, 01 Jan 2027 00:00:00 GMT

Przykłady wykorzystania API w praktyce

Media lokalne

Portal trojmiasto.pl (Gdańsk):

Interaktywna mapa projektów BO na portalu
Tabela wyników aktualizowana co 5 minut podczas głosowania
Automatyczne powiadomienia o wynikach (webhook → artykuł)
Porównanie edycji BO (wykresy z danych API)

Gazeta Wyborcza (Kraków):

Ranking dzielnic wg frekwencji
Infografiki z danymi BO (kategorie, koszty, trendy)
Artykuły “data journalism” oparte na analizie API

Badacze i uczelnie

Uniwersytet Jagielloński (projekt badawczy “Partycypacja 2.0”):

Analiza korelacji frekwencji BO z dochodem na mieszkańca per dzielnica
Porównanie preferencji projektowych w 10 polskich miastach
Publikacja w “Samorząd Terytorialny” (miesięcznik naukowy)

SGH Warszawa:

Model predykcyjny: jakie projekty mają szansę wygrać (na podstawie danych historycznych)
Analiza equity terytorialnego — czy BO jest sprawiedliwy przestrzennie?

Organizacje społeczne

Fundacja Batorego:

Monitoring realizacji zwycięskich projektów BO w 10 miastach
Raport roczny “Stan Budżetów Obywatelskich” oparty na danych API
Rekomendacje dla samorządów

Stowarzyszenie Klon/Jawor:

Mapa BO w Polsce — wizualizacja budżetów obywatelskich we wszystkich miastach
Porównanie kwot, frekwencji i kategorii projektów

Civic-tech

Mój Samorząd (aplikacja mobilna):

Agregacja danych BO z wielu miast w jednej aplikacji
Powiadomienia push o głosowaniu w mieście użytkownika
Porównanie “jak głosuje moja dzielnica vs. inne”

Bezpieczeństwo API — co chronić

Zagrożenia specyficzne dla API BO

Zagrożenie	Opis	Zabezpieczenie
Scraping danych osobowych	Próba wyciągnięcia danych wnioskodawców	Anonimizacja, brak danych osobowych w API
DDoS	Przeciążenie API requestami	Rate limiting, WAF, CDN
Injection	Wstrzyknięcie kodu przez parametry	Walidacja inputów, prepared statements
Enumeration	Zgadywanie ID projektów/głosów	UUID zamiast sekwencyjnych ID
Nieuprawniony dostęp	Dostęp do danych rozszerzonych bez klucza	Autoryzacja, monitoring

API publiczne powinno obsługiwać CORS, aby widgety i aplikacje frontendowe mogły pobierać dane:

Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET, OPTIONS
Access-Control-Allow-Headers: Authorization, Content-Type

Uwaga: Dla endpointów z danymi rozszerzonymi (poziom 2 i 3) CORS powinien być ograniczony do zarejestrowanych domen partnerów.

Bezpieczeństwo ARDVote: Otwarte API wymaga solidnych zabezpieczeń. Poznaj szczegóły ochrony danych w ARDVote — szyfrowanie AES-256, autoryzacja dostępu, zgodność z RODO i WCAG 2.1 AA.

Checklist wdrożenia API dla BO

Przed uruchomieniem

Zdefiniuj trzy poziomy dostępu (publiczny, zarejestrowany, partner)
Zaimplementuj rate limiting (token bucket)
Zanonimizuj wszystkie dane osobowe
Przygotuj dokumentację (OpenAPI/Swagger)
Wdrożone testy automatyczne (contract tests)
Zaimplementuj monitoring (uptime, latency, błędy)

Po uruchomieniu

Opublikuj API na dane.gov.pl (portal otwartych danych)
Powiadom media lokalne o dostępności API
Skontaktuj się z lokalnymi uczelniami (potencjalni użytkownicy)
Monitoruj usage patterns — kto korzysta, jak często, jakie endpointy
Zbieraj feedback od użytkowników API (formularz, GitHub issues)

Podsumowanie

API dla Budżetu Obywatelskiego to:

Wymóg prawny — ustawa o otwartych danych nakazuje udostępnianie informacji publicznej w formatach maszynowych
Transparentność — otwarte dane budują zaufanie do procesu i umożliwiają niezależną weryfikację
Ekosystem — media, badacze, NGO i civic-tech tworzą wartość dodaną wokół danych BO
Standard nowoczesnej administracji — 30+ polskich miast już udostępnia dane BO przez API

Poznaj API ARDVote →

API w systemach BO - jak udostępniać dane mediom i organizacjom

Dlaczego API dla Budżetu Obywatelskiego jest ważne?

Transparentność procesu

Ekosystem wokół danych BO

Wymóg prawny — otwarte dane

Jakie dane udostępniać przez API?

Klasyfikacja danych — trzy poziomy dostępu

Poziom 1: Dane publiczne (bez ograniczeń)

Poziom 2: Dane rozszerzone (po rejestracji)

Poziom 3: Dane chronione (NIGDY publicznie)

Architektura API — projektowanie od podstaw

REST API — rekomendowana architektura

Formaty danych

Przykładowa odpowiedź API — projekt BO

Paginacja i filtrowanie

Autoryzacja i limity — ochrona API

Trzy poziomy dostępu

Proces rejestracji klucza API

Rate limiting — implementacja

Integracja z mediami lokalnymi — praktyczne formaty

Widget wyników na żywo

Feed RSS/Atom — powiadomienia o zmianach

Webhook — powiadomienia push dla partnerów

Dokumentacja API — jak ją dobrze napisać

Elementy dobrej dokumentacji

Wersjonowanie API

Przykłady wykorzystania API w praktyce

Media lokalne

Badacze i uczelnie

Organizacje społeczne

Civic-tech

Bezpieczeństwo API — co chronić

Zagrożenia specyficzne dla API BO

Checklist wdrożenia API dla BO

Przed uruchomieniem

Po uruchomieniu

Podsumowanie

Powiązane artykuły

Dlaczego API dla Budżetu Obywatelskiego jest ważne?

Transparentność procesu

Ekosystem wokół danych BO

Wymóg prawny — otwarte dane

Jakie dane udostępniać przez API?

Klasyfikacja danych — trzy poziomy dostępu

Poziom 1: Dane publiczne (bez ograniczeń)

Poziom 2: Dane rozszerzone (po rejestracji)

Poziom 3: Dane chronione (NIGDY publicznie)

Architektura API — projektowanie od podstaw

REST API — rekomendowana architektura

Formaty danych

Przykładowa odpowiedź API — projekt BO

Paginacja i filtrowanie

Autoryzacja i limity — ochrona API

Trzy poziomy dostępu

Proces rejestracji klucza API

Rate limiting — implementacja

Integracja z mediami lokalnymi — praktyczne formaty

Widget wyników na żywo

Feed RSS/Atom — powiadomienia o zmianach

Webhook — powiadomienia push dla partnerów

Dokumentacja API — jak ją dobrze napisać

Elementy dobrej dokumentacji

Wersjonowanie API

Przykłady wykorzystania API w praktyce

Media lokalne

Badacze i uczelnie

Organizacje społeczne

Civic-tech

Bezpieczeństwo API — co chronić

Zagrożenia specyficzne dla API BO

CORS (Cross-Origin Resource Sharing)

Checklist wdrożenia API dla BO

Przed uruchomieniem

Po uruchomieniu

Podsumowanie

Powiązane artykuły