Tekninen kuvaus

Palvelu tarjoaa OGC API Processes -kyselyrajapinnan Maanmittauslaitoksen eri aineistoille. Rajapintapalvelu perustuu vahvistettuun OGC API - Processes - Part 1: Core -standardiin.

Rajapintapalvelu tarjotaan maksuttomana ja Maanmittauslaitoksen avoimen rajapintapalvelun käyttöehtojen mukaisesti. Rajapinnan käyttö vaatii API-avaimen liittämistä pyyntöihin. Ohjeet tähän löydät sivulta Ohje API-avaimen käyttöön.

Rajapintapalvelu on saatavilla osoitteesta: https://beta-paikkatieto.maanmittauslaitos.fi/tiedostopalvelu/ogcproc/v1/

Video OGC API Processes -standardista ja palvelun käytöstä (englanniksi).

Aineistot ja tuotteet

Beta-vaiheessa palvelusta on saatavilla seuraavat aineistot:

Aineisto	Tiedostoformaatti	Hakutavat / Geometriat
Hallinnolliset aluejaot, rasteri	PNG	Hakugeometria : Koko Suomi Aineistosta on ladattavissa vuosiversiot vuodesta 2012 alkaen.
Hallinnolliset aluejaot, vektori	GPKG, GML, SHAPE	Hakugeometria : Koko Suomi Aineistosta on ladattavissa vuosiversiot vuodesta 2012 alkaen.
Karttalehtijako	SHAPE	Hakugeometria : Koko Suomi
Kiinteistörekisterikartta, rasteri	PNG	Hakugeometria: Karttalehtinumero
Kiinteistörekisterikartta, vektori	SHAPE, GML	Hakugeometria: Karttalehtinumero (Tulossa myöhemmin: Koko Suomi, BBOX, Polygon)
Kiintopisteet	GPKG	Hakugeometriat: Koko Suomi, BBOX, Polygon
Korkeusmalli 2 m	TIFF	Hakugeometriat: Karttalehtinumero, BBOX, Polygon
Korkeusmalli 10 m	TIFF	Hakugeometriat: Karttalehtinumero
Korkeusvyöhykkeet	TIFF	Hakugeometria : Koko Suomi, karttalehtinumero
Laserkeilausaineisto	LAZ	Hakugeometria: Karttalehtinumero
Maastokartta, vektori	SHAPE	Hakugeometriat: Koko Suomi, karttalehtinumero
Maastokartta, rasteri	PNG	Hakugeometriat: Koko Suomi, karttalehtinumero
Maastotietokanta	GPKG	Hakugeometriat: Kuntatunnus, BBOX, Polygon Aineisto on ladattavissa eri teemoissa: maastotietokanta_kaikki, maasto, tieliikenne, vesiliikenne, raideliikenne, johtoverkosto, hydrografia, rakennukset, korkeussuhteet, suojelukohteet, hallinnollinen_jaotus Teemajaon tarkempi kuvaus Kuntatunnuksien ja nimien vastaavuus (Tilastokeskus)
Maastotietokanta (Ei sisällä korkeussuhteita)	GPKG	Hakugeometria: Koko Suomi
Maastotietokannan korkeussuhteet	GPKG	Hakugeometria: Koko Suomi
Nimistö	GML	Hakugeometria: Koko Suomi
Ortoilmakuva	JPEG2000	Hakugeometria: Karttalehtinumero
Rinnevarjoste	TIFF	Hakugeometriat: Koko Suomi, karttalehtinumero
Taustakartta, rasteri	PNG	Hakugeometriat: Koko Suomi, karttalehtinumero

Palvelu tukee beta-vaiheessa ainoastaan koordinaattijärjestelmää ETRS-TM35FIN (eli EPSG:3067).

Kyselyt ja esimerkit

Kehitettäessä OGC API Processes -asiakassovelluksia kannattaa ensin tutustua viralliseen standardiin.

OGC API Processes -rajapinta on ns. itseohjautuva. Rajapinnan vastauksissa olevat linkit ohjaavat käyttäjää eteenpäin uusien pyyntöjen muodostamisessa.

Aloitussivu:

https://beta-paikkatieto.maanmittauslaitos.fi/tiedostopalvelu/ogcproc/v1/

Prosessilistan avulla käyttäjä voi selata eri prosesseja ja niiden kuvauksia:

https://beta-paikkatieto.maanmittauslaitos.fi/tiedostopalvelu/ogcproc/v1/processes

Yksittäisen prosessin kuvauksessa kuvataan mm. käynnistysparametrit ja niihin liittyvät mahdolliset rajoitukset. Prosessin kuvaus on saatavilla esimerkiksi osoitteessa:

https://beta-paikkatieto.maanmittauslaitos.fi/tiedostopalvelu/ogcproc/v1/processes/maastotietokanta_bbox

Prosessikuvauksen avulla käyttäjä voi muodostaa lopulta prosessin käynnistävän execution-kyselyn esimerkiksi:

https://beta-paikkatieto.maanmittauslaitos.fi/tiedostopalvelu/ogcproc/v1/processes/maastotietokanta_bbox/execution

Kyselyparametrit execution-kyselylle annetaan http post -sanomalla.

Esimerkki http post -sanomasta:

{
  "id": "maastotietokanta_bbox",
  "inputs": {
    "boundingBoxInput": [24316,6603329,736001,7802433],
    "themeInput": "maastotietokanta_kaikki",
    "fileFormatInput": "GPKG"
  }
}

Execution-kyselyn jälkeen rajapinta palauttaa linkin prosessin käynnistämään uniikkiin työhön.

Esimerkki execution-kyselyn vastauksesta:

{
  "jobID" : "1c612b7e-aa3f-43cb-bfb9-ce707b83184f",
  "status" : "accepted",
  "message" : "Job accepted",
  "progress" : 0,
  "create" : "2022-03-08T10:02:15.095+0200",
  "link" : {
    "href" : "https://beta-paikkatieto.maanmittauslaitos.fi/tiedostopalvelu/ogcproc/v1/jobs/1c612b7e-aa3f-43cb-bfb9-ce707b83184f",
    "rel" : "self",
    "type" : "application/json",
    "title" : "this document"
  }
}

Työn etenemistä voi seurata työn uniikista linkistä, tässä tapauksessa linkistä

https://beta-paikkatieto.maanmittauslaitos.fi/tiedostopalvelu/ogcproc/v1/jobs/1c612b7e-aa3f-43cb-bfb9-ce707b83184f

Kyselyn vastauksena saadaan myös työn status. Työn eri statuksia ovat:

accepted = työ hyväksytty ja odottaa käsittelyä
running = työ käynnissä (progress -prosenttilukema kertoo työn edistymisen tilanteen)
successful = työ valmis
failed = työ epäonnistunut
dismissed = työ keskeytetty

Esimerkki onnistuneesti tehdyn työn status-kyselyn vastauksesta:

{
  "jobID" : "1c612b7e-aa3f-43cb-bfb9-ce707b83184f",
  "status" : "successful",
  "message" : "successfully executed job",
  "progress" : 100,
  "create" : "2022-03-08T10:02:15.095+0200",
  "link" : {
    "href" : "https://beta-paikkatieto.maanmittauslaitos.fi/tiedostopalvelu/ogcproc/v1/jobs/1c612b7e-aa3f-43cb-bfb9-ce707b83184f/results/",
    "rel" : "self",
    "type" : "application/json",
    "title" : "this document"
  }
}

Onnistuneen työn status-kyselyn vastauksessa palautetaan linkki results-kyselyyn, jonka avulla käyttäjä saa linkit ladattaviin tiedostoihin.

Esimerkki results-kyselyn vastauksesta:

{
  "uuid" : "1c612b7e-aa3f-43cb-bfb9-ce707b83184f",
  "jobDescription" : {
    "id" : "maastotietokanta_bbox",
    "inputs" : {
      "boundingBoxInput" : [ 317000.124, 6822000.091, 327300.003, 6822300.598 ],
      "themeInput" : "maastotietokanta_kaikki",
      "fileFormatInput" : "GPKG"
    }
  },
  "processId" : "maastotietokanta_bbox",
  "status" : "successful",
  "progress" : 100,
  "jobCreateTime" : "2022-03-08T10:02:15.095+0200",
  "statusMessage" : "successfully executed job",
  "owner" : "default",
  "results" : [ {
    "path" : "https://beta-paikkatieto.maanmittauslaitos.fi/tiedostopalvelu/dl/v1/1c612b7e-aa3f-43cb-bfb9-ce707b83184f/maastotietokanta_kaikki.gpkg",
    "format" : "GPKG",
    "crs" : "etrs-tm35fin",
    "mimeType" : "application/geopackage+vnd.sqlite3",
    "length" : "7766016"
  }, {
    "zipPath" : "https://beta-paikkatieto.maanmittauslaitos.fi/tiedostopalvelu/dl/v1/uncompressed/1c612b7e-aa3f-43cb-bfb9-ce707b83184f"
  } ]
}

Results-kyselyn vastauksessa on latauslinkkien lisäksi myös tiedot kyselyparametreista ja niiden arvoista sekä tiedot tiedostojen metatiedoista. Metatietoja on tarjolla eri laajuudella aineistokohtaisesti. Tapauksissa, jossa kysely muodostaa usean latauslinkin, voidaan tiedostot joko ladata erikseen erillisinä tiedostoina tai tiedostot voidaan ladata myös zip-pakattuna kaikki kerrallaan.

Versiohallinta

BETA-julkaisu 5.4.2022

Esimerkkejä

Esimerkkejä prosessien käynnistämisistä

maastotietokanta_koko_suomi

Execution-kyselyn osoite:

https://beta-paikkatieto.maanmittauslaitos.fi/tiedostopalvelu/ogcproc/v1/processes/maastotietokanta_koko_suomi/execution

Http post -sanoma:

{
  "id": "maastotietokanta_koko_suomi",
  "inputs": { 
  "fileFormatInput":"GPKG"
   }
}

maastotietokanta_kunta

Execution-kyselyn osoite:

https://beta-paikkatieto.maanmittauslaitos.fi/tiedostopalvelu/ogcproc/v1/processes/maastotietokanta_kunta/execution

Http post -sanoma:

{
   "id": "maastotietokanta_kunta",
   "inputs": {
   "municipalityInput": "235",
   "fileFormatInput": "GPKG",
   "themeInput": "maastotietokanta_kaikki"
   }
}

maastotietokanta_bbox

Execution-kyselyn osoite:

https://beta-paikkatieto.maanmittauslaitos.fi/tiedostopalvelu/ogcproc/v1/processes/maastotietokanta_bbox/execution

Http post -sanoma:

{
  "id": "maastotietokanta_bbox",
  "inputs": {
    "boundingBoxInput": [317000.124,6822000.091,327300.003,6822300.598],
    "themeInput": "maastotietokanta_kaikki",
    "fileFormatInput": "GPKG"
  }
}

maastotietokanta_polygon

Execution-kyselyn osoite:

https://beta-paikkatieto.maanmittauslaitos.fi/tiedostopalvelu/ogcproc/v1/processes/maastotietokanta_polygon/execution

Http post -sanoma:

{ 
 "id": "maastotietokanta_polygon", 
 "inputs": { 
 "polygonInput": [[312801,6826721],[329601,6826001],[336353,6823457],[333121,6820065],[315745,6819953],[312801,6826721]],
 "themeInput": "tieliikenne",
 "fileFormatInput": "GPKG"
 }
}

laserkeilausaineisto_05_karttalehti

Execution-kyselyn osoite:

https://beta-paikkatieto.maanmittauslaitos.fi/tiedostopalvelu/ogcproc/v1/processes/laserkeilausaineisto_05_karttalehti/execution

Http post -sanoma:

{ 
    "id": "laserkeilausaineisto_05_karttalehti",
    "inputs": { "mapSheetInput": ["M3342B4"],
    "fileFormatInput": "LAZ",
    "dataSetInput": "Uusin"
    }
}

korkeusmalli_2m_karttalehti

Execution-kyselyn osoite:

https://beta-paikkatieto.maanmittauslaitos.fi/tiedostopalvelu/ogcproc/v1/processes/korkeusmalli_2m_karttalehti/execution

Http post -sanoma:

{
  "id": "korkeusmalli_2m_karttalehti",
  "inputs": {
    "mapSheetInput":  ["M3342B","M3342C","M3342D","M3342E"],    
    "fileFormatInput": "TIFF"
  }
}

korkeusmalli_2m_bbox

Execution-kyselyn osoite:

https://beta-paikkatieto.maanmittauslaitos.fi/tiedostopalvelu/ogcproc/v1/processes/korkeusmalli_2m_bbox/execution

Http post -sanoma:

{
  "id": "korkeusmalli_2m_bbox",
  "inputs": {
    "boundingBoxInput": [385396,6672568,389620,6677160],
    "fileFormatInput": "TIFF"
  }
}

korkeusmalli_2m_polygon

Execution-kyselyn osoite:

https://beta-paikkatieto.maanmittauslaitos.fi/tiedostopalvelu/ogcproc/v1/processes/korkeusmalli_2m_polygon/execution

Http post -sanoma:

{
  "id": "korkeusmalli_2m_polygon",
  "inputs": {
    "polygonInput": [[385208,6675957],[386884,6675726],[387216,6674842],[386292,6674318],[385424,6674746],[385208,6675957]],
    "fileFormatInput": "TIFF"
  }
}

korkeusmalli_10m_karttalehti

Execution-kyselyn osoite:

https://beta-paikkatieto.maanmittauslaitos.fi/tiedostopalvelu/ogcproc/v1/processes/korkeusmalli_10m_karttalehti/execution

Http post -sanoma:

{
"id": "korkeusmalli_10m_karttalehti",
"inputs":

{ "mapSheetInput": ["M3342","L5221"], "fileFormatInput": "TIFF" }
}

korkeussuhteet_koko_suomi

Execution-kyselyn osoite:

https://beta-paikkatieto.maanmittauslaitos.fi/tiedostopalvelu/ogcproc/v1/processes/korkeussuhteet_koko_suomi/execution

Http post -sanoma:

{
  "id": "korkeussuhteet_koko_suomi",
  "inputs": {
    "fileFormatInput":"GPKG"
    }
  }
}

karttalehtijako_koko_suomi

Execution-kyselyn osoite:

https://beta-paikkatieto.maanmittauslaitos.fi/tiedostopalvelu/ogcproc/v1/processes/karttalehtijako_koko_suomi/execution

Http post -sanoma:

{
"id": "karttalehtijako_koko_suomi",
"inputs":

{ "fileFormatInput":"ESRI shapefile", "dataSetInput":"kaikki" }

}

rinnevarjoste_512m_koko_suomi

Execution-kyselyn osoite:

https://beta-paikkatieto.maanmittauslaitos.fi/tiedostopalvelu/ogcproc/v1/processes/rinnevarjoste_512m_koko_suomi/execution

Http post -sanoma:

{
"id": "rinnevarjoste_512m_koko_suomi",
"inputs":

{ "fileFormatInput":"TIFF", "dataSetInput":"hila_512m" }

}

rinnevarjoste_karttalehti

Execution-kyselyn osoite:

https://beta-paikkatieto.maanmittauslaitos.fi/tiedostopalvelu/ogcproc/v1/processes/rinnevarjoste_karttalehti/execution

Http post -sanoma:

{
"id": "rinnevarjoste_karttalehti",
"inputs":

{ "mapSheetInput":["N3413"], "fileFormatInput":"TIFF", "dataSetInput":"rinnevarjoste_8m" }
}

korkeusvyohykkeet_512m_koko_suomi

Execution-kyselyn osoite:

https://beta-paikkatieto.maanmittauslaitos.fi/tiedostopalvelu/ogcproc/v1/processes/korkeusvyohykkeet_512m_koko_suomi/execution

Http post -sanoma:

{
"id": "korkeusvyohykkeet_512m_koko_suomi",
"inputs":

{ "fileFormatInput":"TIFF", "dataSetInput":"hila_512m" }

}

korkeusvyohykkeet_karttalehti

Execution-kyselyn osoite:

https://beta-paikkatieto.maanmittauslaitos.fi/tiedostopalvelu/ogcproc/v1/processes/korkeusvyohykkeet_karttalehti/execution

Http post -sanoma:

{
"id": "korkeusvyohykkeet_karttalehti",
"inputs":

{ "mapSheetInput": ["M3","M5"], "fileFormatInput": "TIFF", "dataSetInput": "korkeusvyohykkeet_64m" }
}

hallinnolliset_aluejaot_rasteri_koko_suomi

Execution-kyselyn osoite:

https://beta-paikkatieto.maanmittauslaitos.fi/tiedostopalvelu/ogcproc/v1/processes/hallinnolliset_aluejaot_rasteri_koko_suomi/execution

Http post -sanoma:

{
"id": "hallinnolliset_aluejaot_rasteri_koko_suomi",
"inputs":

{ "fileFormatInput":"PNG", "dataSetInput":"kuntajako_4500k", "yearInput":0 }

}

hallinnolliset_aluejaot_vektori_koko_suomi

Execution-kyselyn osoite:

https://beta-paikkatieto.maanmittauslaitos.fi/tiedostopalvelu/ogcproc/v1/processes/hallinnolliset_aluejaot_vektori_koko_suomi/execution

Http post -sanoma:

{
"id": "hallinnolliset_aluejaot_vektori_koko_suomi",
"inputs":

{ "fileFormatInput":"kaikki", "dataSetInput":"kuntajako_4500k", "yearInput":0 }

}

maastokartta_vektori_koko_suomi

Execution-kyselyn osoite:

https://beta-paikkatieto.maanmittauslaitos.fi/tiedostopalvelu/ogcproc/v1/processes/maastokartta_vektori_koko_suomi/execution

Http post -sanoma:

{
"id": "maastokartta_vektori_koko_suomi",
"inputs":

{ "fileFormatInput":"ESRI shapefile", "dataSetInput":"maastokartta_1000k" }

}

maastokartta_vektori_karttalehti

Execution-kyselyn osoite:

https://beta-paikkatieto.maanmittauslaitos.fi/ogc/v1/processes/maastokartta_vektori_karttalehti/execution

Http post -sanoma:

{
"id": "maastokartta_vektori_karttalehti",
"inputs":

{ "fileFormatInput":"ESRI shapefile", "dataSetInput":"maastokartta_vektori_100k", "mapSheetInput":["M53"] }

}

maastokartta_rasteri_koko_suomi

Execution-kyselyn osoite:

https://beta-paikkatieto.maanmittauslaitos.fi/tiedostopalvelu/ogcproc/v1/processes/maastokartta_rasteri_koko_suomi/execution

Http post -sanoma:

{
"id": "maastokartta_rasteri_koko_suomi",
"inputs":

{ "fileFormatInput":"PNG", "dataSetInput":"maastokartta_rasteri_4500k" }
}

maastokartta_rasteri_karttalehti

Execution-kyselyn osoite:

https://beta-paikkatieto.maanmittauslaitos.fi/ogc/v1/processes/maastokartta_rasteri_karttalehti/execution

Http post -sanoma:

{
"id": "maastokartta_rasteri_karttalehti",
"inputs":

{ "fileFormatInput":"PNG", "dataSetInput":"maastokartta_rasteri_20k_taustavari", "mapSheetInput":["M5321L"] }

}

nimisto_koko_suomi

Execution-kyselyn osoite:

https://beta-paikkatieto.maanmittauslaitos.fi/tiedostopalvelu/ogcproc/v1/processes/nimisto_koko_suomi/execution

Http post -sanoma:

{
"id": "nimisto_koko_suomi",
"inputs":

{ "fileFormatInput":"GML", "dataSetInput":"paikat" }

}

taustakartta_rasteri_koko_suomi

Execution-kyselyn osoite:

https://beta-paikkatieto.maanmittauslaitos.fi/tiedostopalvelu/ogcproc/v1/processes/taustakartta_rasteri_koko_suomi/execution

Http post -sanoma:

{
"id": "taustakartta_rasteri_koko_suomi",
"inputs":

{ "fileFormatInput":"PNG", "dataSetInput":"taustakartta_rasteri_8000k" }
}

ortoilmakuva_karttalehti

Execution-kyselyn osoite:

https://beta-paikkatieto.maanmittauslaitos.fi/tiedostopalvelu/ogcproc/v1/processes/ortoilmakuva_karttalehti/execution

Http post -sanoma:

{
"id": "ortoilmakuva_karttalehti",
"inputs":

{ "mapSheetInput":["L3311B"], "fileFormatInput":"JPEG2000", "yearInput":2020, "dataSetInput":"ortokuva" }
}

Esimerkki cURL-komennosta

Maastotietokannan kaikki kohteet suorakaiderajauksella (bbox):

curl -H "Content-Type: application/json" -X POST "https://beta-paikkatieto.maanmittauslaitos.fi/tiedostopalvelu/ogcproc/v1/processes/maastotietokanta_bbox/execution?api-key=xxxxyyyyzzzz" -d "{\"id\": \"maastotietokanta_bbox\",\"inputs\":{\"boundingBoxInput\":[317000.124,6822000.091,327300.003,6822300.598],\"themeInput\":\"maastotietokanta_kaikki\",\"fileFormatInput\":\"GPKG\"}}"