Tekninen kuvaus Maastotietokannan osoitteiden kyselypalvelu (WFS)

HUOM! Palvelu poistuu käytöstä - uusia käyttäjiä ei enää oteta. Vastaavat tiedot ovat saatavilla Geokoodauspalvelusta.

Käyttösopimuksen tehtyäsi pääset palvelun etusivulle osoitteeseen https://ws.nls.fi/maasto/. Huom! tällä sivulla tehdyt WFS-pyynnöt palveluun kirjataan normaaleina palvelupyyntöinä asiakaskohtaisessa käytönseurannassa, jota käytetään myös käyttösopimuksen mukaisen laskutuksen perusteena.

Kyselypalveluun kytkeydyttäessä käytetään WFS-asiakassovelluksessa seuraavaa palvelun metatietokuvauksen mukaista osoitetta: https://ws.nls.fi/maasto/wfs.



Palvelusta on haettavissa WFS-standardin mukaisilla kyselyillä palvelun metatietokuvaus ja kohdeluokkien tietomallikuvaus. Metatietokuvauksesta selviää mm. ne palveluosoitteet, joita käytetään kytkemään asiakassovellus rajapintaan. Kytkeytyvän sovelluksen tulee hakea nämä kuvaukset ajantasaisena itse palvelusta.



Alla on linkkeinä staattiset kopiot näiden kyselyiden vastauksista tutustumista varten:



Palvelun metatietokuvaus (GetCapabilities -kysely)

Kohdeluokkien tietomallikysely (DescribeFeatureType -kysely ilman typename-parametria)

  • kohdetyyppikohtaiset kuvaukset DescribeFeatureType -kyselyllä käyttäen typename-parametria  

 

Yleiset ohjeet Maanmittauslaitoksen WFS 1.1. käyttöön

Maastotietokannan osoitteiden kyselypalvelu (WFS) tarjoaa tuotteena Maastotietokannan osoitepisteitä, joita ovat:

  • Maastotietokannan tiekohteista lasketut osoitepisteet
  • Maastotietokannan tiekohteista erilliset osoitepisteet (esim. saaret).

Tuotteesta on kaksi erilaista skeemaversiota: Osoitepiste ja Osoitenimi.

Molemmat skeemaversiot ovat haettavissa WFS-rajapintapalvelun kautta. WFS-rajapinta mahdollistaa osoitteiden haun spatiaalisella rajauksella, esim. suorakaide- tai ympyrärajauksella. Standardi ei kuitenkaan suoraan mahdollista toimintoa, jolla haetaan tietystä pisteestä lähintä löytyvää kohdetta.

Täten kyselypalvelun yhteyteen on toteutettu myös erillinen Lähimmän osoitteen rajapintapalvelu. Tästä rajapinnasta tarjotaan vain skeemaversion Osoitepiste mukaista palvelua.

Skeemat

Osoitepiste sisältää maastotietokannan osoitteista lasketun osoitepisteen ja sen alikohteena siihen liittyvät osoitteet (katunimi, katunumero) niillä kielillä, joille osoitetieto on kyseisen osoitepisteen osalta kerätty.

  • linkki kohdeluokkien tietomallikysely (DescribeFeatureType -kysely ilman typename-parametria) staattiseen kopioon kyselyn vastauksista tutustumista varten

Osoitenimi sisältää maastotietokannan osoitteista lasketun osoitepisteen ja siihen liittyvän osoitteen yhdellä kielellä samassa kohderakenteessa. Jos samassa pisteessä on osoite useammalla kielellä, nämä ovat erillisinä osoitenimi-kohteina.

  • linkki kohdeluokkien tietomallikysely (DescribeFeatureType -kysely ilman typename-parametria) staattiseen kopioon kyselyn vastauksista tutustumista varten

Skeemassa esiintyvien elementtien selitteet:

  • katunimi
    • tiekohteista lasketuilla osoitepisteillä: kadun tai tien nimi
    • tiekohteista erillisillä osoitepisteillä: kohdetta kuvaava selite (esim. saaren nimi)
  • katunumero
    • tiekohteista lasketut osoitepisteet:
      • osoitenumero, joka on laskettu 10 metriä tien keskilinjasta kohtisuoraan joko vasemmalle tai oikealle puolelle
      • katunumerot ovat nollia ja ne lasketaan 100 metrin välein, jos tietä ei ole numeroitu
      • katunumerot ovat laskennallisia, eivät välttämättä todellisia
    • tiekohteista erillisillä osoitepisteillä:
      • kohteen numero tai teksti
  • kieli
    • nimen kielen (suomi, ruotsi, pohjoissaame, inarinsaame tai koltansaame) ISO 639-3 -standardin mukainen kolmikirjaiminen koodi
  • jarjestysnumero
    • tiekohteista lasketuilla osoitepisteillä: juokseva järjestysnumero, joka alkaa tien osoitepisteillä aina 1:stä, kasvaa katunumeroiden mukaisessa järjestyksessä
      • ei ole aina sama kuin katunumero: jos tiellä samoja katunumeroita tai katunumeroita puuttuu välistä tai katunumerot ovat nollia
    • tiekohteista erillisillä osoitepisteillä: samansisältöisten selitteiden juokseva järjestysnumero (esim. saaren sisällä juokseva numero)
  • kuntatunnus
    • sen kunnan kolmenumeroinen kuntatunnus, jonka alueella osoitepistelaskennassa käytetty tieviiva suurimmaksi osaksi sijaitsee
    • sen kunnan kolmenumeroinen kuntatunnus, jonka alueella tiekohteesta erillinen osoitepiste sijaitsee
  • kuntanimiFin
    • kuntatunnuksen mukaisen kunnan nimi suomeksi
    • jos kunnalla ei ole suomenkielistä nimeä, ruotsinkielinen nimi
  • kuntanimiSwe
    • kuntatunnuksen mukaisen kunnan nimi ruotsiksi
    • jos kunnalla ei ole ruotsinkielistä nimeä, suomenkielinen nimi
  • kiinteistotunnus
    • maastotietokannan osoitepisteillä tietoa ei ole
  • rakennustunnus
    • maastotietokannan osoitepisteillä tietoa ei ole
  • sijainti
    • osoitepisteen sijaintipiste, koordinaatit

WFS-rajapintapalvelu

WFS-rajapintapalvelun käyttötavat on kuvattu WFS-rajapintapalveluiden yleisohjeessa.

Lähimmän osoitteen rajapintapalvelu

Tässä on kuvattu kyselypalvelun yhteyteen toteutetun erillisen Lähimmän osoitteen rajapintapalvelun käyttötavat.

Palveluosoite

Lähimmän osoitteen rajapintapalvelu on käytettävissä osoitteesta:

https://ws.nls.fi/maasto/nearestfeature

Kyselypalvelun testilomakkeelta voi muodostaa testikyselyitä sekä WFS-rajapintapalveluun että Lähimmän osoitteen rajapintapalveluun:

https://ws.nls.fi/maasto

Käyttäjätunnistus ja tiedonsiirtoyhteys

Asiakas tunnistetaan HTTP Basic Authentication mukaisesti käyttäen valtuustietona käyttäjätunnusta ja salasanaa. Nämä on oltava mukana jokaisessa pyynnössä. Jos käyttäjälle on annettu oikeus Maastotietokannan osoitteiden kyselypalveluun, tämä oikeus koskee sekä standardin mukaista WFS-rajapintapalvelua että Lähimmän osoitteen rajapintapalvelua.

Yhteys asiakkaan ja palvelun välillä on suojattu käyttäen SSL-yhteyskäytäntöä. Suojaamatonta HTTP-yhteyttä ei tueta.

Rajapinta

Kyselyt rajapintapalveluun tulee välittää KVP- (nimi-arvo-pari) koodattuina käyttäen HTTP:n GET-metodia.

Seuraavassa on lueteltu tuetut kyselyparametrit:

Parametri Arvo Merkitys Kardinaliteetti
TYPENAME Tässä rajapintapalvelussa tulee olla "oso:Osoitepiste" Haettavan kohdetyypin nimi. 1
COORDS Muoto {x},{y}[,{srsname}]



Esim. "385445,6675125,EPSG:3067" tai "385445,6675125"		 Piste, jonka ympäriltä lähintä kohdetta haetaan. Parametrissa x ja y ilmaisevat pisteen koordinaatit (akselien järjestys käytettävän EPSG-koodin mukaisesti). Näiden perässä srsname:lla voidaan ilmoittaa pisteen koordinaatisto. Jos tätä ei ole annettu, oletetaan pisteen olevan EPSG:3067 mukainen koordinaatti. 1
SRSNAME Esim. "EPSG:3067"

Oletuksena "EPSG:3067"		 Vastauksessa palautettavien sijaintitietojen koordinaatisto EPSG-koodina. 0 .. 1
MAXFEATURES Esim. "1" tai "100"

Oletuksena "1"		 Ilmaisee kuinka monta kohdetta pisteen ympäriltä maksimissaan palautetaan. 0 .. 1
BUFFER Esim. "1000" Maksimietäisyys metreinä miltä etäisyydeltä korkeintaan lähintä kohdetta haetaan. 0 .. 1

Esimerkiksi seuraava kysely hakee lähintä osoitepistettä ETRS-TM35FIN koordinaatiston pisteen 385445,6675125 ympäriltä maksimissaan 1 km säteellä:

https://ws.nls.fi/maasto/nearestfeature?TYPENAME=oso:Osoitepiste&COORDS=385445,6675125,EPSG:3067&SRSNAME=EPSG:3067&MAXFEATURES=1&BUFFER=1000 

Rajapinta palauttaa vastauksena XML-muotoisena GML-skeemarakenteena. Rakenne on täsmälleen sama kuin Osoitepiste-rakenne kyselypalvelun WFS-rajapintapalvelussa.

Jos MAXFEATURES-parametrin arvo on suurempi kuin 1, niin vastauksessa Osoitepiste-kohteet palautetaan siinä järjestyksessä, mikä kohde on hakupistettä lähinnä.

Osoitepiste-kysely

Haetaan Osoitepisteet suorakeiteen sisältä.

Xml-rakenteinen pyyntö:

<?xml version="1.0" encoding="UTF-8"?>

<wfs:GetFeature version="1.1.0"

xmlns:oso="http://xml.nls.fi/Osoitteet/Osoitepiste/2011/02"

xmlns:wfs="http://www.opengis.net/wfs"

xmlns:gml="http://www.opengis.net/gml"

xmlns:ogc="http://www.opengis.net/ogc"

xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

xsi:schemaLocation="http://www.opengis.net/wfs

http://schemas.opengis.net/wfs/1.1.0/wfs.xsd">

 <wfs:Query typeName="oso:Osoitepiste">

  <ogc:Filter>

                      <ogc:BBOX>

                              <ogc:PropertyName>oso:sijainti</ogc:PropertyName>

                              <gml:Envelope srsName="EPSG:3067">

                                      <gml:lowerCorner>385000.0 6675000.0</gml:lowerCorner>

                                      <gml:upperCorner>386000.0 6676000.0</gml:upperCorner>

                              </gml:Envelope>

                      </ogc:BBOX>

  </ogc:Filter>

 </wfs:Query>

</wfs:GetFeature>

Sama tulos saadaan HTTP GET-pyynnöllä:

https://ws.nls.fi/maasto/wfs?SERVICE=WFS&REQUEST=GetFeature&VERSION=1.1.0&NAMESPACE=xmlns(oso=http://xml.nls.fi/Osoitteet/Osoitepiste/2011/02)&TYPENAME=oso:Osoitepiste&BBOX=385000,6675000,386000,6676000,EPSG:3067&SRSNAME=EPSG:3067&MAXFEATURES=1000&RESULTTYPE=results

Vastaus

Osoitenimi-kysely

1) Haetaan se Osoitenimi kunnan Helsinki alueelta, jonka katunimi on Opastinsilta ja katunumero 12.

Xml-rakenteinen pyyntö:

<?xml version="1.0" encoding="UTF-8"?>

<wfs:GetFeature version="1.1.0"

xmlns:oso="http://xml.nls.fi/Osoitteet/Osoitepiste/2011/02"

xmlns:wfs="http://www.opengis.net/wfs"

xmlns:gml="http://www.opengis.net/gml"

xmlns:ogc="http://www.opengis.net/ogc"

xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

xsi:schemaLocation="http://www.opengis.net/wfs

http://schemas.opengis.net/wfs/1.1.0/wfs.xsd">

 <wfs:Query typeName="oso:Osoitenimi">

  <ogc:Filter>

                       <ogc:And>

                               <ogc:PropertyIsEqualTo>

                                       <ogc:PropertyName>oso:kuntanimiFin</ogc:PropertyName>

                                      <ogc:Literal>Helsinki</ogc:Literal>

                               </ogc:PropertyIsEqualTo>

                               <ogc:PropertyIsEqualTo>

                                      <ogc:PropertyName>oso:katunimi</ogc:PropertyName>

                                      <ogc:Literal>Opastinsilta</ogc:Literal>

                               </ogc:PropertyIsEqualTo>

                               <ogc:PropertyIsEqualTo>

                                      <ogc:PropertyName>oso:katunumero</ogc:PropertyName>

                                      <ogc:Literal>12</ogc:Literal>

                               </ogc:PropertyIsEqualTo>

                       </ogc:And>

               </ogc:Filter>

 </wfs:Query>

</wfs:GetFeature>

Vastaus

 

2) Rajaus vain katunimellä siten, että haetaan vain katunimen ensimmäinen osoitepiste

Xml-rakenteinen pyyntö:

<?xml version="1.0" encoding="utf-8"?><wfs:GetFeature xmlns:jx="http://apache.org/cocoon/templates/jx/1.0" xmlns:oso="http://xml.nls.fi/Osoitteet/Osoitepiste/2011/02" xmlns:wfs="http://www.opengis.net/wfs" xmlns:gml="http://www.opengis.net/gml" xmlns:ogc="http://www.opengis.net/ogc" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" version="1.1.0" xsi:schemaLocation="http://www.opengis.net/wfs http://schemas.opengis.net/wfs/1.1.0/wfs.xsd">

 <wfs:Query typeName="oso:Osoitenimi">

 <ogc:SortBy>   

          <ogc:SortProperty><ogc:PropertyName>oso:kuntanimiFin</ogc:PropertyName></ogc:SortProperty>            

          <ogc:SortOrder>DESC</ogc:SortOrder> 

 </ogc:SortBy>

        <ogc:Filter>

  <ogc:And>

                        <ogc:PropertyIsLike wildCard="*" singleChar="?" escape="!" matchCase="false">

                                <ogc:PropertyName>oso:katunimi</ogc:PropertyName>

                                <ogc:Literal>*hankamäen*</ogc:Literal>

                        </ogc:PropertyIsLike>   

                         <ogc:PropertyIsEqualTo>

                                <ogc:PropertyName>oso:jarjestysnumero</ogc:PropertyName>

                                <ogc:Literal>1</ogc:Literal>

                         </ogc:PropertyIsEqualTo>                    

  </ogc:And>

          </ogc:Filter>

 </wfs:Query>

</wfs:GetFeature>

Vastaus

 

3) Rajaus katunimellä, osoitenumerolla ja kuntanimellä (voi olla suomen tai ruotsinkielinen, tästä syystä esimerkiksi Helsinki rajaus menee semä kuntanimiFin että kuntanimiSwe kenttään kun käyttäjä voi kirjoittaa myös Helsingfors)

Xml-rakenteinen pyyntö:

<?xml version="1.0" encoding="utf-8"?><wfs:GetFeature xmlns:jx="http://apache.org/cocoon/templates/jx/1.0" xmlns:oso="http://xml.nls.fi/Osoitteet/Osoitepiste/2011/02" xmlns:wfs="http://www.opengis.net/wfs" xmlns:gml="http://www.opengis.net/gml" xmlns:ogc="http://www.opengis.net/ogc" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" version="1.1.0" xsi:schemaLocation="http://www.opengis.net/wfs http://schemas.opengis.net/wfs/1.1.0/wfs.xsd">

 <wfs:Query typeName="oso:Osoitenimi">

 <ogc:SortBy>   

          <ogc:SortProperty><ogc:PropertyName>oso:kuntanimiFin</ogc:PropertyName></ogc:SortProperty>            

          <ogc:SortOrder>DESC</ogc:SortOrder> 

 </ogc:SortBy>

        <ogc:Filter>

  <ogc:And>

                        <ogc:PropertyIsLike wildCard="*" singleChar="?" escape="!" matchCase="false">

                                <ogc:PropertyName>oso:katunimi</ogc:PropertyName>

                                <ogc:Literal>Opastinsilta</ogc:Literal>

                        </ogc:PropertyIsLike>

   

         <ogc:PropertyIsEqualTo>

                                <ogc:PropertyName>oso:katunumero</ogc:PropertyName>

                                <ogc:Literal>12</ogc:Literal>

                        </ogc:PropertyIsEqualTo>     

               

   <ogc:Or>

    <ogc:PropertyIsLike wildCard="*" singleChar="?" escape="!" matchCase="false">

     <ogc:PropertyName>oso:kuntanimiFin</ogc:PropertyName>

                                   <ogc:Literal>Helsinki</ogc:Literal>

                         </ogc:PropertyIsLike>

                  <ogc:PropertyIsLike wildCard="*" singleChar="?" escape="!" matchCase="false">

                           <ogc:PropertyName>oso:kuntanimiSwe</ogc:PropertyName>

                                  <ogc:Literal>Helsinki</ogc:Literal>

                         </ogc:PropertyIsLike>

                 </ogc:Or>  

  </ogc:And>

          </ogc:Filter>

 </wfs:Query>

</wfs:GetFeature>

Vastaus

 

4) Rajaus katunimellä ja katunumerolla  

Xml--rakenteinen pyyntö:

<?xml version="1.0" encoding="utf-8"?><wfs:GetFeature xmlns:jx="http://apache.org/cocoon/templates/jx/1.0" xmlns:oso="http://xml.nls.fi/Osoitteet/Osoitepiste/2011/02" xmlns:wfs="http://www.opengis.net/wfs" xmlns:gml="http://www.opengis.net/gml" xmlns:ogc="http://www.opengis.net/ogc" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" version="1.1.0" xsi:schemaLocation="http://www.opengis.net/wfs http://schemas.opengis.net/wfs/1.1.0/wfs.xsd">

 <wfs:Query typeName="oso:Osoitenimi">

 <ogc:SortBy>   

          <ogc:SortProperty><ogc:PropertyName>oso:kuntanimiFin</ogc:PropertyName></ogc:SortProperty>            

          <ogc:SortOrder>DESC</ogc:SortOrder> 

 </ogc:SortBy>

        <ogc:Filter>

  <ogc:And>

                        <ogc:PropertyIsLike wildCard="*" singleChar="?" escape="!" matchCase="false">

                                <ogc:PropertyName>oso:katunimi</ogc:PropertyName>

                                <ogc:Literal>*silta</ogc:Literal>

                        </ogc:PropertyIsLike>

   

         <ogc:PropertyIsEqualTo>

                                <ogc:PropertyName>oso:katunumero</ogc:PropertyName>

                                <ogc:Literal>12</ogc:Literal>

                        </ogc:PropertyIsEqualTo>                    

  </ogc:And>

          </ogc:Filter>

 </wfs:Query>

</wfs:GetFeature>

Vastaus

Sovellusversio 2011-02

Sovellusversiossa 2011-02 (1.3.2011) julkaistu kyselypalvelu koekäyttöön. Kyselypalvelu sisältää WFS-rajapintapalvelun ja Lähimmän osoitteen rajapintapalvelun.

Tietomallissa käytettävä nimiavaruus: http://xml.nls.fi/Osoitteet/Osoitepiste/2011/02

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