Tekninen kuvaus Arkistoasiakirjojen kyselypalvelu (REST)
Yhteys palvelun ja asiakkaan välillä on SSL-suojattu (Secure Socket Layer, HTTPS-protokolla). Palveluun pitää kirjautua sisään antamalla käyttäjätunnus ja salasana. Käytössä on HTTP Basic Authentication -tunnistus, jonka on oltava mukana jokaisessa pyynnössä. Arkistoasiakirjojen kyselypalvelu (rest) kerää hakuihin liittyviä tilasto- ja laskutustietoja palvelupyyntöjen perusteella käyttäjätunnuksittain jaoteltuna.
Palvelu on käytettävissä ma - su klo 00.15 - 23.15.
Loppukäyttäjien lokitus
Arkistoasiakirjojen kyselypalvelun (REST) palvelinjärjestelmässä tallennetaan lokeihin tietoa myös asiakassovelluksessa tunnistetusta loppukäyttäjästä, mikäli asiakassovellus välittää rajapintapalvelulle loppukäyttäjää identifioivan tunnisteen kunkin rajapintapyynnön yhteydessä.
Teknisesti rajapintapalvelun kutsuissa tunniste tulee välittää HTTP-standardin mukaisena Request Header-kenttänä nimeltään "enduserid" ja jonka arvon tulee olla merkkijono (välilyönnit ei sallittuja, pituus max. 60 merkkiä). Muutoin merkkijonon sisältö voi olla asiakassovelluksen määrittämä, mutta kuitenkin siten, että tarvittaessa tunnisteen perusteella on selvitettävissä loppukäyttäjä asiakassovelluksen ylläpitäjän toimesta.
Yleistä lisätietoa HTTP:n Request Header-kentistä: https://developer.mozilla.org/en-US/docs/Glossary/Request_header
Lokitietojen siirron toimivuus on hyvä varmistaa ottamalla yhteyttä Maanmittauslaitokseen osoitteeseen verkkopalvelut@maanmittauslaitos.fi
Lisäksi lokitietoja tulee säilyttää kuuden vuoden ajan, jonka jälkeen ne tulee poistaa.
Aineistot ja tuotteet
Aineisto
Sähköisen arkiston aineisto karttuu toimitus- ja kirjaamistuotantojärjestelmistä sekä vanhaa paperiaineistoa digitoimalla. Sähköisessä arkistossa on syksyllä 2025 noin 7 miljoonaa asiakirjaa ja 600 000 erillistä karttaa.
Maanmittaustoimitusten asiakirjojen muodostuminen alkaa 1700-luvulta. Aineistoa löytyy sähköisestä arkistosta kattavasti vuodesta 1998 alkaen. Tätä vanhempaa aineistoa digitoidaan sähköiseen arkistoon tarveperusteisesti. Kaikkiaan paperisesta maanmittausarkistosta on digitoitu arviolta 11 %. Sähköisessä arkistossa on noin 7,6 miljoonaa maanmittaustoimitusten asiakirja- ja karttatiedostoa.
Kiinteistöjen kirjaamisarkistot alkavat Maanmittauslaitoksessa vuodesta 1993. Tätä vanhemmat aineistot on luovutettu Kansallisarkistolle. Lainhuutopäätökset on digitoitu kattavasti vuodesta 2010 ja toukokuusta 2013 eteenpäin kirjaamisarkisto on kokonaan sähköinen. Vanhempaa aineistoa digitoidaan tarveperusteisesti. Kirjaamisasiakirjoja on sähköisessä arkistossa noin 10 miljoonaa.
Asiakirjat on järjestetty sähköiseen arkistoon asiakohtaisesti. Yksi toimitus tai kirjaamisasia muodostaa yhden ns. arkistokansion sähköisessä arkistossa. Sähköisestä arkistosta löytyy arkistokansio kaikista MML:n paperiarkistoon arkistoiduista toimituksista ja kirjaamisasioista. Kansio löytyy vaikka aineistoa ei olisi vielä digitoitu. Rajapinta palauttaa ensivaiheessa arkistokansion metatiedot sekä asiakirjojen kuvailutiedot, jos asiakirjat ovat sähköisessä arkistossa. Näiden tietojen perusteella käyttäjä voi valita, mitä asiakirjoja hän haluaa katsella.
Vanha arkistoaineisto on järjestetty sähköiseen arkistoon historiallisen rekisteritiedon perusteella, jota ylläpidettiin paikallisesti vaihtelevilla menettelyillä. Ajallisen ja paikallisen vaihtelun vuoksi metatiedoissa on poikkeuksia, jotka voivat aiheuttaa epäonnistuneita hakuja, vaikka aineisto olisi sähköisessä arkistossa. Näissä tapauksissa käyttäjät voivat olla yhteydessä Maanmittauslaitoksen asiakaspalveluun.
Rajapinnan käyttö edellyttää Kiinteistötietojen kyselypalvelujen OGC API Features ja REST käyttöä. Rajapintaa kutsutaan arkistokansion arkistoviitteellä ja kuntakoodilla tai arkistokansion asianumerolla, jotka saadaan Kiinteistötietojen kyselypalveluista.
Palvelun skeemat
| Tuote | Skeema |
| Arkistoasian ja asikirjojen metatiedot | http://xml.nls.fi/XML/Schema/sovellus/ARKKIrest/asiakasdokumentaatio/versionhallinta/1.0/Skeema/TietopalveluhaunTulos.xsd |
Kyselyt ja esimerkit
Arkistoasian ja asiakirjojen metatiedot
XML-rakenne pyydetään palvelusta HTTPS/GET-protokollaan perustuvalla kyselyllä. Kyselyyn sisältyvät parametrit, joiden mukaista tietoa haetaan.
Hakuparametrit
| Nimi | Aineisto | Esim. |
| Arkistoviite ja kuntakoodi | Maanmittaustoimitukset vuoden 2004 loppuun |
Arkistoviitteen muoto voi vaihdella. Esim.
|
| Arkistoviite ja vakiotu kuntakoodi 999 | Kirjaamisasiakirjat 4/2013 asti | esim. 715:2001:lh:2856 |
| Arkistoviite | Maanmittaustoimituset 2005 alkaen | Vakioitu muoto esim. MMLm/949/33/2009 |
| Arkistoviite | Kirjaamisasiat 5/2013 alkaen | Vakioitu muoto esim. MML/55569/70/2014 |
Esimerkiksi maanmittaustoimituksen arkistoasian ja asiakirjojen metatiedot, arkistoviite: 337-1, kuntakoodi: 105.
https://arkkitp.nls.fi/ArkkiTP/v1/case/xml?archiveId=337-1&municipalityId=105
Esimerkkitiedosto vastauksesta
Esimerkiksi maanmittaustoimituksen arkistoasian ja asiakirjojen metatiedot, arkistoviite: 17 ISOJAKO, kuntakoodi: 090
https://arkkitp.nls.fi/ArkkiTP/v1/case/xml?archiveId=17 ISOJAKO&municipalityId=090
Esimerkkitiedosto vastauksesta
Esimerkiksi maanmittaustoimituksen arkistoasian ja asiakirjojen metatiedot, arkistoviite: 204:2001:1, kuntakoodi:204
https://arkkitp.nls.fi/ArkkiTP/v1/case/xml?archiveId=204:2001:1&municipalityId=204
Esimerkkitiedosto vastauksesta
Esimerkiksi kiinteistöjen kirjaamisasian ja asiakirjojen metatiedot, arkistoviite: 715:2001:lh:2856, vakioitu kuntakoodi: 999
https://arkkitp.nls.fi/ArkkiTP/v1/case/xml?archiveId=715:2001:lh:2856&municipalityId=999
Esimerkkitiedosto vastauksesta
Esimerkiksi maanmittaustoimituksen arkistoasian ja asiakirjojen metatiedot, muodoltaan vakioitu arkistoviite: MMLm/949/33/2009
https://arkkitp.nls.fi/ArkkiTP/v1/case/xml?nativeidentifier=MMLm/949/33/2009
Esimerkkitiedosto vastauksesta
Esimerkiksi kiinteistöjen kirjaamisasian ja asiakirjojen metatiedot, muodoltaan vakioitu arkistoviite: MML/55569/70/2014
https://arkkitp.nls.fi/ArkkiTP/v1/case/xml?nativeidentifier=MML/55569/70/2014
Esimerkkitiedosto vastauksesta
Arkistoasiakirja
Arkistoasiakirja pyydetään palvelusta HTTPS/GET-protokollaan perustuvalla kyselyllä.
Hakuparametrit
| Nimi | Aineisto | Esim |
| AsiakirjanNumero | 30548387 |
Esimerkiksi arkistoasiakirja, ID-numero 6776693
https://arkkitp.nls.fi/ArkkiTP/v1/File?documentNumber=6776693
Versiohallinta
Arkistoasiakirjojen kyselypalvelu (REST) Versio 4.0, 12/2023
Arkistoasiakirjojen kyselypalvelu (REST) Versio 1.0, 3/2017
Virheiden hallinta
Palveluun kytkeytymiseen tai saatavuuteen sekä tietoliikenteeseen liittyvistä virhetilanteista palautetaan asiakassovellukselle virheilmoitus HTTP-virhekoodeina. Mm. seuraavat virhekoodit voivat tulla kyseeseen:
| Virhekoodi | HTTP-tunnus | Selitys |
| 400 | Bad Request | Hakupyyntö tai sen parametrit ovat virheellisiä. |
| 401 | Unauthorized | Palvelu ei hyväksy asiakassovelluksen välittämää käyttäjätunnistetta. |
| 403 | Forbidden | Käyttäjälle ei ole oikeuksia tuotteeseen |
| 500 | Internal Server Error | Pyyntöä käsiteltäessä tapahtunut jokin odottamaton virhetilanne. |
| 503 | Service Unavailable | Palvelussa on liikaa ruuhkaa tai samalla käyttäjällä on liian monta samanaikaista pyyntöä. |