Hyppää pääsisältöön

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.

Aineisto

Sähköisen arkiston aineisto karttuu suoraan toimitus- ja kirjaamistuotantojärjestelmistä sekä vanhaa paperiaineistoa digitoimalla. Sähköisessä arkistossa on keväällä 2017 noin 5,3 miljoonaa asiakirjaa ja 300 000 erillistä karttaa. Aineiston määrä kasvaa koko ajan.

Maanmittaustoimitusasiakirjat löytyvät sähköisestä arkistosta kattavasti vuodesta 1998 alkaen. Vanhempaa aineistoa sähköisestä arkistosta löytyy aina isojaosta, 1700-luvulta alkaen. Vanhaa aineistoa (vuotta 1998 vanhempaa) on digitoitu sähköiseen arkistoon tarveperusteisesti. Kaiken kaikkiaan MML:n koko paperisesta maanmittaustoimitusarkistosta on digitoitu arviolta 5 %. Arkistossa on n. 2,5 miljoonaa toimitusasiakirja- ja karttatiedostoa.

Kiinteistöjen kirjaamisasiakirjoja MML:n paperiarkistossa on vuodesta 1993 alkaen. Vanhemmat aineistot on luovutettu Arkistolaitokselle. Kirjaamisasiakirjat ovat kattavasti sähköisessä arkistossa vuoden 2013 toukokuusta alkaen. Vanhempaa aineistoa (1993-2013) digitoidaan sähköiseen arkistoon tarveperusteisesti. Kirjaamisasiakirjoja MML:n arkistossa on n. 2,5 miljoonaa.

Asiakirjat on järjestetty sähköiseen arkistoon maanmittaustoimitus- tai kirjaamisasiakohtaisesti. 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 digitoitu. Rajapinta palauttaa ensivaiheessa arkistokansion metatiedot sekä asiakirjojen kuvailutiedot, mikäli 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 vanhan rekisteritiedon perusteella, jota ylläpidettiin vuosikymmenien kuluessa paikallisesti vaihtelevilla menettelyillä. Tämän vuoksi metatiedoissa on poikkeuksia, jotka voivat aiheuttaa epäonnistuneita hakuja, vaikka aineiston 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

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.

  • 17:4
  • 17 ISOJAKO
  • 337-1
  • 204:2001:1
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

Arkistoasiakirjojen kyselypalvelu (REST) Versio 4.0, 12/2023

Arkistoasiakirjojen kyselypalvelu (REST) Versio 1.0, 3/2017 

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öä.