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).

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).

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.

 

BETA-julkaisu 5.4.2022

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\"}}"

Olet estänyt evästeet. Jos haluat antaa palautetta tästä sivusta, hyväksy kävijämittaus- ja analytiikkaevästeet.