# vero

> Finland's public income-tax records, tax years 2011 to 2024, as a keyless JSON/CSV API. One record per person per year: name, birth year, gender, region, earned and capital income, taxes, tax rate, refund or back tax, rank within the year. Source: Verohallinto's public income-tax data (laki verotustietojen julkisuudesta ja salassapidosta 1346/1999, 5 §), released to the media every November and compiled here from the published figures.

Base URL: https://vero.23signs.org. No authentication. CORS: any origin. Every JSON response carries `_links`; errors are RFC 9457 `application/problem+json`.

## Scope, read first

- Only people whose combined earned + capital income reached the year's extract threshold appear: 150 000 € (2011, 2012), 120 000 € (2013 to 2016), 100 000 € (2017 to 2022), 120 000 € (2023, 2024). A missing year means income under that line, not zero.
- A person is identified across years by `slug` = folded name (lowercase ASCII, hyphens) + `-` + birth year, e.g. `herlin-antti-juhani-1956`. A name change or a missing birth year splits a history.
- Names are surname first, as registered: "Herlin Antti Tapani".
- Regular assessment only; later corrections are not included. Age is counted in the tax year.
- Tax year 2025 becomes public 12 Nov 2026 and is added then.

## Endpoints

- GET /api/v1/search?name=<surname [firstname]>[&year=YYYY][&limit=1..50][&format=csv]: people whose name tokens start with every query token (surname first; falls back to the second word as surname). Grouped per person, each with `years[]`, `latest`.
- GET /api/v1/people/{slug}[?format=csv]: one person with every year they appear. 404 if the slug is not in the public data.
- GET /api/v1/top?year=YYYY&sort=total|earned|capital[&region=all|<code>|<name>][&gender=all|male|female][&limit=1..200][&format=csv]: the year's highest incomes. Defaults: latest year, sort total, whole country, limit 50.
- GET /api/v1/stats[?year=YYYY]: per-year aggregates (count, threshold, sums, medians, p90, gender, age buckets, regions, income bands with median tax rate and capital share, counts above 150k/200k/500k/1M, persistence at 150k), all-time top 50 by summed income, number of people present every year.
- GET /api/v1/dataset: years with counts and thresholds, regions (code, name), fields of the compact row, build time.

Static data, same origin, also public: /data/meta.json, /data/stats.json, /data/y/<year>.json (all rows of a year as compact arrays, sorted by total desc), /data/n/<xx>.json (all years for surnames whose folded form starts with xx), /data/top/<year>/<sort>/<region|all>/<all|m|f>.json.

## Record shape (JSON)

{ id, year, name, slug, birthYear, age, gender: "male"|"female"|null, region: {code, name}|null, rank,
  income: { total, earned, capital, capitalShare }, tax: { total, rate, state, municipal, refund, backTax, prepayments } }
Amounts are euros as integers; `rate` is the overall tax rate in percent.

## Documents

- OpenAPI 3.1: /openapi.yaml, /openapi.json
- Skill file: /SKILL.md
- API catalog (RFC 9727): /.well-known/api-catalog
- Catalog: /.well-known/ai-catalog.json
- Source and how it is built: /README.md

Unofficial, by 23signs (https://23signs.org). Questions and takedown requests: hello@23signs.org.