Aura

Suomalaisen avoimen datan discovery- ja ymmärryspalvelu

Dokumentaatio · What's New · Datasettikatalogi · Dataformaatit · Datalähteet

7 200+ datasettiä · 17 000+ resurssia · 370+ organisaatiota · ~2 TB avointa dataa

30 datalähteestä: avoindata.fi, SYKE, HRI, Tilastokeskus, LUKE, Digitraffic, Digitransit, Finap/NAP, FMI, Paikkatietoikkuna, Suomi.fi-koodistot, Overture Maps, GTK, Traficom, Metsäkeskus, MML, Väylävirasto, Valtiokonttori, Ruokavirasto, THL Sotkanet, STUK, LIPAS, PaItuli, Vaalirahoitusvalvonta, Lajitietokeskus, Kuntien paikkatiedot (36 kuntaa) ym.

Aura kyntää suomalaisen avoimen datan esiin piilostaan ja tekee sen ymmärrettäväksi. Palvelu toimii MCP-serverinä tekoälyille sekä avoimena web-palveluna ihmisille.

Aura — kyntöaura kääntää maan pintaan piiloutuneen esiin. Aura on myös valon kehä auringon tai kuun ympärillä — hohde joka tekee näkyväksi sen mikä muuten jää piiloon. Samalla tavalla tämä työkalu tuo esiin Suomen avoimen datan ja antaa sille näkyvyyden.

Mitä Aura tekee?

• Aggregoi metadatan 30 avoimen datan lähteestä
• Normalisoi CKAN, PxWeb, OData, WFS, OpenAPI ja GTFS -formaatit yhtenäiseen muotoon
• Tekee hakukelpoiseksi — FTS5-täystekstihaku luonnollisella kielellä
• Arvioi datakoon — jokaiselle datasetille arvioitu koko
• Laatupisteyttää — automaattinen laadun arviointi neljällä dimensiolla
• Rikastaa joukkoistamalla — MCP-sessiot kerryttävät tietoa dataseteistä
• Tunnistaa skeemoja — päättelee kenttänimet ja tyypit esikatselusta
• Palvelee tekoälyjä MCP-serverin kautta (Claude, GPT, jne.)
• Mahdollistaa reaaliaikakyselyt — agentti voi hakea dataa suoraan rajapinnoista (Digitraffic, PxWeb, WFS, OData ym.)

Vaatimukset

• Python 3.11+ — tarkista: python3 --version
• pip tai uv pakettien asennukseen
• git repon kloonaamiseen

SQLite tulee Python 3.11:n mukana (FTS5-tuki sisäänrakennettu). Erillistä SQLite-asennusta ei tarvita.

Valinnainen:

• MML API-avain — Maanmittauslaitoksen aineistoihin (ks. Rajausaineistot)

Käyttöönotto

Claude Code (toimii sellaisenaan)

Auran repo sisältää .mcp.json-tiedoston, joka konfiguroi MCP-serverin automaattisesti. Ei tarvitse tehdä mitään ylimääräistä:

git clone https://github.com/trotor/aura.git
cd aura
python3 -m venv .venv
source .venv/bin/activate
pip install -e .

claude   # Aura MCP-server käynnistyy automaattisesti

Claude Code tunnistaa .mcp.json:n ja käynnistää serverin taustalle. Voit heti kysyä: "Mitä avoimia datasettejä Helsingin kaupunki tarjoaa?"

Claude Desktop

Lisää Auran MCP-server Clauden asetustiedostoon:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "aura": {
      "command": "/polku/aura/.venv/bin/python",
      "args": ["-m", "aura.cli", "serve"]
    }
  }
}

Korvaa /polku/aura kloonatun repon absoluuttisella polulla. Käytä virtuaaliympäristön Pythonia (.venv/bin/python).

Cursor

Lisää .cursor/mcp.json projektin juureen tai globaalisti ~/.cursor/mcp.json:

{
  "mcpServers": {
    "aura": {
      "command": "/polku/aura/.venv/bin/python",
      "args": ["-m", "aura.cli", "serve"]
    }
  }
}

Windsurf

Lisää ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "aura": {
      "command": "/polku/aura/.venv/bin/python",
      "args": ["-m", "aura.cli", "serve"]
    }
  }
}

Muu MCP-yhteensopiva työkalu

Aura on standardi MCP-server. Mikä tahansa työkalu joka tukee MCP-protokollaa voi käyttää Auraa. Käynnistyskomento:

/polku/aura/.venv/bin/python -m aura.cli serve

Tai uv:llä ilman erillistä asennusta:

uv --directory /polku/aura run aura serve

Komentorivityökalu

source .venv/bin/activate

# Hae datasettejä
aura search "väestö helsinki"
aura search "joukkoliikenne"

# Tilastot ja lähteet
aura stats
aura sources

# Päivitä data
aura harvest              # kaikki lähteet
aura harvest avoindata.fi  # yksittäinen lähde
aura harvest --list        # listaa saatavilla olevat
aura refresh              # harvest + laatupisteet + health + skeema
aura infer-schemas        # päättele kenttätyypit esikatselusta

# Rikastukset
aura export-enrichments -o contributions/omat.json
aura import-enrichments contributions/*.json

Huom: Tietokanta (data/aura.db) tulee repon mukana valmiina — ei tarvitse harvestoida erikseen.

MCP-työkalut

Haku ja selaus:

Alueanalyysi:

Laatu:

Rikastus ja tutkimus:

Hallinta:

Rajapintojen suora käyttö agentissa

Aura ei ole pelkkä hakemisto — tekoälyagentti voi hakea dataa suoraan rajapinnoista käyttäjän puolesta. Kun käyttäjä kysyy esimerkiksi junan aikataulua, agentti etsii Aurasta oikean rajapinnan ja kyselee sitä reaaliajassa.

Esimerkkejä

Junaliikenne:

"Moneltako IC147 saapuu Kuopioon tänään?"

Agentti etsii Aurasta Digitraffic rata-API:n ja hakee aikataulun: rata.digitraffic.fi/api/v1/trains/2026-03-30/147

Tilastot:

"Mikä on Tampereen väkiluku?"

Agentti löytää Tilastokeskuksen PxWeb-taulun ja kyselee sen query_data-työkalulla.

Sää:

"Mikä on lämpötila Helsingissä?"

Agentti hakee Ilmatieteen laitoksen WFS-rajapinnasta reaaliaikahavainnon.

Tuetut rajapintatyypit

Huom: Osa rajapinnoista (Digitransit GraphQL, MML OGC API) vaatii API-avaimen. Agentti ohjaa rekisteröitymiseen tarvittaessa.

Datalähteet

Katso täydellinen datasettikatalogi: docs/CATALOG.md
Katso lähteiden tekniset tiedot: docs/SOURCES.md
Katso tuetut dataformaatit: docs/formats.md

Osallistuminen

Auraan voi osallistua monella tavalla — myös ilman koodaamista.

Rikasta dataa (helpoin tapa)

Jokaisella Aura MCP -sessiolla kertyy arvokasta tietoa dataseteistä: mitä kenttiä data sisältää, miten sitä haetaan, millainen laatu on. Tämä tieto voidaan tallentaa pysyvästi enrich()-työkalulla.

MCP-session aikana tekoäly voi kutsua enrich()-työkalua automaattisesti:

"Tutki Ruokaviraston peltolohkorekisterin sisältö ja tallenna löydökset."

AI tutkii datasetin, löytää kentät ja metatiedot, ja kutsuu:

enrich("ruokavirasto-peltolohkorekisteri-2024", "data_fields",
       '["lohko_id", "kasvilaji", "pinta_ala_ha"]', confidence="high")
enrich("ruokavirasto-peltolohkorekisteri-2024", "keywords",
       '["maatalous", "CAP", "tukialue"]')

Kontribuoi rikastuksia muille:

aura export-enrichments -o contributions/omat-rikastukset.json
git add contributions/
git commit -m "data: enrich Ruokaviraston datasettejä"
# Avaa pull request

Tuetut rikastuskentät:

Lisää uusia datalähteitä

Katso CONTRIBUTING.md ohjeet uuden harvesterin luomiseen.

Raportoi ja ehdota

Avaa issue GitHubissa.

Projektirakenne

aura/
├── src/aura/               # Pääpaketti
│   ├── server.py           # MCP-server (FastMCP)
│   ├── database.py         # SQLite + FTS5 + enrichments
│   ├── models.py           # Pydantic-tietomallit
│   ├── search.py           # Hakutoiminnot ja muotoilu
│   ├── cli.py              # Komentorivityökalu
│   └── harvesters/         # Datalähteiden keräimet (29 kpl)
├── data/
│   ├── aura.db             # SQLite-tietokanta (osa repoa)
│   └── boundaries/         # Rajausaineistot GeoPackage (gitignore)
├── contributions/          # Jaetut rikastukset (JSON)
├── scripts/migrations/     # Tietokantamigraatiot
├── docs/                   # Dokumentaatio
└── tests/                  # Testit

Tietokanta

SQLite + FTS5 -täystekstihaku. Tietokanta on osa git-repoa — ei tarvitse harvestoida erikseen.

Git LFS — data/aura.db tallennetaan Git LFS:llä repon koon hallitsemiseksi. Kloonaaminen vaatii git lfs:n:

brew install git-lfs   # macOS
git lfs install        # kerran per kone
git clone https://github.com/trotor/aura.git  # LFS-tiedostot haetaan automaattisesti

Skeemamuutokset hoidetaan migraatiojärjestelmällä (scripts/migrations/). Migraatiot ajetaan automaattisesti init_db():n yhteydessä — tietokanta ei nollaudu päivityksessä.

Maantieteellinen kattavuus ja rajausaineistot

Aura tallentaa jokaiselle datasetille geographical_coverage-kentän, joka kertoo minkä alueen dataa datasetti sisältää. Tieto tulee pääasiassa harvestoinnin yhteydessä.

Nykytila

Arvot tulevat eri lähteistä:

• avoindata.fi — API palauttaa kaupunkien ja alueiden nimet
• Kuntien paikkatiedot — 36 kuntaa omalla geographical_coverage-arvolla
• Staattiset harvestarit — konfiguraatiossa (esim. Overture Maps → ["Maailma"])
• Muut — oletusarvo ["Suomi"]

Rajausaineistot

Paikallisina rajausaineistoina käytetään GeoPackage-tiedostoja data/boundaries/-kansiossa. Kansio on gitignoressa — aineistot ladataan erikseen. Lähde: Kapsi.fi (MML:n avoin data, CC BY 4.0).

# Lataa kaikki rajausaineistot yhdellä komennolla (~40 MB)
bash scripts/download_boundaries.sh

Skripti on idempotentti — ohittaa jo ladatut tiedostot.

Karttalehtijako (TM35)

MML:n karttalehtijako kattaa koko Suomen ETRS-TM35FIN (EPSG:3067) -koordinaatistossa. 7 hierarkiatasoa:

Kuntajako (hallinnolliset rajat)

MML:n hallinnolliset aluejaot: 308 kuntaa, 19 maakuntaa, 23 hyvinvointialuetta, Suomen raja. Kaksi mittakaavaa: 1:1M (yleiskäyttö) ja 1:10k (tarkka geometria).

Kiinteistörajat

Kiinteistörajat haetaan MML:n rajapintapalvelusta (liian suuria lokaaliin tallennukseen).

MML API-avain

MML:n OGC API Processes -tiedostopalvelu vaatii ilmaisen API-avaimen. Kapsi.fi-peili toimii ilman avainta, mutta muihin MML-aineistoihin avain tarvitaan:

1. Rekisteröidy: https://omatili.maanmittauslaitos.fi/user/new/avoimet-rajapintapalvelut
2. Luo API-avain OmaTili-palvelussa
3. Tallenna .env-tiedostoon: MML_API_KEY=avaimesi

Hakusuodatin

region-suodatin MCP-työkaluissa:

search("joukkoliikenne", region="Helsinki")     # kaupunkitaso
search("ympäristödata", region="Uusimaa")        # maakuntataso → laajentuu kuntiin
search("palvelut", region="33100")               # postinumero → kunta

Hierarkkinen haku: haettaessa maakunnalla palautetaan myös maakunnan kuntien aineistot. Viitetaulut (308 kuntaa, 3 784 postinumeroa) mahdollistavat alueen tunnistuksen.

Kehitys

source .venv/bin/activate
pip install -e ".[dev]"

pytest              # testit
ruff check src/     # lintteri
mypy src/           # tyypintarkistus

Katso CONTRIBUTING.md tarkemmat ohjeet.

Versiointi

Semantic Versioning 2.0.0 · What's New · VERSIONING.md · CHANGELOG.md

Aura etäpalveluna

Aura toimii tällä hetkellä paikallisena palveluna — jokainen käyttäjä ajaa oman instanssinsa. Etsimme organisaatiota, joka haluaisi tarjota Auran keskitettynä etäpalveluna: remote MCP -palvelin, johon kuka tahansa voisi yhdistää AI-assistenttinsa.

Teknisesti palvelu on kevyt — SQLite-kanta, Python-prosessi ja ajastettu harvestointi. Koodi on MIT-lisenssillä vapaasti käytettävissä.

Tämä sopisi erityisesti taholle, jonka tehtävänä on edistää suomalaisen datan löydettävyyttä: tutkimusinfrastruktuurin ylläpitäjä, avoimen datan edistäjä, julkishallinnon digitalisaatiotaho tai kirjasto- ja arkistosektori.

Kiinnostuitko? Lue lisää ja ota yhteyttä (issue #130)

Lisenssi

MIT