Suomiatlas MCP-palvelin

MCP (Model Context Protocol) -palvelin, jonka kautta tekoälyavustaja voi kysyä Suomiatlaksen dataa suoraan: "kuinka monta ihmistä asuu Toukolassa?", "paljonko asunto maksaa Töölössä?", "onko ilma puhdasta Vantaalla?". Data kattaa noin 3000 postinumeroaluetta ja 308 kuntaa.

Yhdistä ilman asennusta

Palvelin on käytettävissä osoitteessa https://suomiatlas.com/api/mcp Streamable HTTP -yhteydellä. Claude Codessa riittää yksi komento; muissa asiakasohjelmissa lisää sama osoite HTTP-tyyppisenä palvelimena.

--header-rivi on valinnainen. Ilman sitä saat ilmaisversion, joka vastaa kaikkiin yllä mainittuihin kysymyksiin; avaimella käytössäsi on tilisi Pro-sisältö tai aluepassi.

claude mcp add --transport http suomiatlas https://suomiatlas.com/api/mcp \
  --header "Authorization: Bearer sk_live_..."

Muut asiakasohjelmat

Jos asiakasohjelmassa ei ole komentoa palvelimen lisäämiseen, lisää sama osoite käsin asetustiedostoon HTTP-tyyppisenä palvelimena.

Authorization-rivi on valinnainen: ilman sitä käytössä on ilmaisversio.

{
  "mcpServers": {
    "suomiatlas": {
      "type": "http",
      "url": "https://suomiatlas.com/api/mcp",
      "headers": { "Authorization": "Bearer sk_live_..." }
    }
  }
}

API-avain

Luo avain kirjautuneena Suomiatlaksessa kohdasta API-avaimet. Avain näytetään kerran; sen jälkeen näet vain alkuosan. Voit mitätöidä avaimen milloin tahansa.

Avain kulkee aina Authorization-otsakkeessa, ei evästeessä. Sillä pääsee lukemaan tilisi Pro-sisältöä, mutta sillä ei voi luoda tai mitätöidä avaimia eikä muuttaa tiliä.

curl -X POST https://suomiatlas.com/api/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -H 'Authorization: Bearer sk_live_...' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Mitä ilmaisversio jättää pois

Kun jokin tieto on maksumuurin takana, vastauksessa on locked-kenttä joka kertoo mikä puuttuu ja miksi. Tieto on olemassa — sitä ei vain palauteta. Avustaja osaa näin sanoa "tämä vaatii Pron" sen sijaan että väittäisi dataa puuttuvaksi tai kuvaisi kolmen vuoden pätkää koko kehityksenä.

{
  "summary": "Espoo: latest median sale prices - Two-room apartment: 3718 EUR/m2 (2025).",
  "data": { "latestHousingPrices": [ ... ] },
  "tier": "free",
  "locked": [
    {
      "field": "housingPriceSeries",
      "reason": "Housing price history for a municipality requires a Suomiatlas Pro subscription. The data exists - it is withheld, not missing.",
      "upgrade": "https://suomiatlas.com/hinnat"
    }
  ]
}

Esimerkki: onko lähellä uimarantaa?

Kysymykseen "onko Kalliossa tai sen lähellä uimahallia tai uimarantaa?" avustaja vastaa yhdellä kutsulla: get_nearby_places withinKm-arvolla (enintään 5 km) palauttaa alueen omat kohteet ja sen rajasta enintään niin kaukana olevat, lähin ensin, etäisyyksineen.

Etäisyys on linnuntietä alueen rajasta, alueen sisällä 0 km — ei kävely- tai matka-aika. inArea kertoo, kuuluuko kohde itse alueeseen.

get_nearby_places {"place": "00530", "categories": ["swimming_pool", "beach"], "withinKm": 2}

{
  "summary": "Within 2 km of Kallio (Helsinki) (00530): nearest swimming pool Urheiluhallit Kallio / Helsingin urheilutalo / Uimahalli (0.03 km); nearest beach Mustikkamaan uimaranta (1.25 km).",
  "data": {
    "withinKm": 2,
    "nearby": {
      "swimming_pool": {
        "countWithin": 5,
        "nearest": [
          { "name": "Urheiluhallit Kallio / Helsingin urheilutalo / Uimahalli", "distanceKm": 0.03, "postalCode": "00510", "inArea": false },
          ...
        ]
      },
      "beach": { "countWithin": 2, "nearest": [ ... ] }
    }
  }
}

Työkalut

Työkalu	Mihin vastaa
`search_places`	nimen tunnistus koodiksi — "mitä Töölöä tarkoitat?"
`get_place_stats`	"kuinka monta asuu Toukolassa tai Akaassa?", "paljonko asunto maksaa Töölössä?"
`get_place_history`	"ovatko asuntojen hinnat nousseet Espoossa?" — aikasarja, laskettu suunta ja alueen 1/5/10 vuoden kehitysmittarit
`get_air_quality`	"onko ilma puhdasta Vantaalla?" — mitatut arvot WHO- ja EU-rajoihin verrattuna
`get_nearby_places`	"mitä Kalliossa on lähellä?" — joukkoliikenteen pysäkit, päiväkodit, koulut, korkea-asteen ja ammatilliset oppilaitokset, terveys- ja lääkäriasemat, apteekit, ruokakaupat, kirjastot, uimahallit ja uimarannat postinumeroalueella tai muutaman kilometrin päässä siitä
`compare_areas`	jopa 12 postinumeroalueen vertailu rinnakkain
`rank_areas`	"missä Suomessa on korkeimmat tulot?" — koko maa, kunta tai maakunta; myös rikollisuus ja puhtain ilma kunnittain
`find_similar_areas`	"missä muualla on samanlaista kuin täällä?"
`list_variables`	mittarien luettelo ja kunkin mittarin vuodet
`get_area_report`	PDF-raportin latauslinkki yhdelle postinumeroalueelle (vaatii Pron tai aluepassin)

Ilmainen ja Pro

Ominaisuus	Ilmainen	Pro
Väkiluku, tulot, koulutus, työllisyys	kaikki	kaikki
Asuntojen hinnat (uusin vuosi)	kyllä	kyllä
Rikollisuus ja ilmanlaatu	kyllä	kyllä
Lähipaikat (pysäkit ja palvelut)	kyllä	kyllä
Historia	3 vuotta	koko aineisto (2010–)
Asuntojen hintakehitys	ei	koko aikasarja (2009–)
Sijoituslistat	10 riviä	100 riviä
Alueiden vertailu	2 aluetta	12 aluetta
Yhdistelmäpisteiden erittely	vain kokonaispisteet	kaikki osatekijät

Kokeile itse

Suomiatlas-kartta — sama data selaimessa, ilman asennusta
OpenAPI-kuvaus — sama rajapinta koneluettavana sopimuksena, ilman avainta

Tilastot ovat CC BY 4.0 -lisenssillä. Lähteet: Tilastokeskus (Paavo, rikollisuus, asuntojen kauppahinnat) ja Ilmatieteen laitos (ilmanlaatu). Lähipaikoilla on omat lisenssinsä: pysäkit ovat Digitransitin avointa dataa (CC BY 4.0), päiväkodit tulevat Suomi.fi-palvelutietovarannosta (CC0 1.0), palvelut OpenStreetMapista (© OpenStreetMapin tekijät, ODbL 1.0) ja uimahallit ja uimarannat LIPAS-tietokannasta (Jyväskylän yliopisto, Lipas Liikuntapaikat.fi, CC BY 4.0). Mainitse alkuperäinen julkaisija kun käytät tietoja; /api/v1/license kertoo, miten lähipaikkojen tietokanta on koottu.