Dokumentaatio generoidaan koodista valmiilla työkalulla, joka toimii melko epävarmasti. Rajapintakuvauksen pitäisi kuitenkin olla kunnossa. Mikäli jokin swagger-kuvauksen vika ei ole jäänyt testeissämme kiinni, kerrothan meille siitä niin korjataan.
Why are there imperfections in Swagger documentation?
The documentation is generated from program code with a tool, which is a bit unstable. The API-description should still be correct. If you find a problem in swagger descriptions that hasn't been caught in our tests, please let us know and we'll fix it.
Miksi Swagger-käyttöliittymä näyttää Map-paluuarvoisille metodeille tyhjän mallin ja esimerkin?
Tämä on bugi swagger-ui-työkalussa, ja on korjattu seuraavaan major-versioon. Itse rajapintakuvaus on kuitenkin kunnossa, joten ongelma on kosmeettinen. Asia korjaantuu kun käyttämämme kirjasto siirtyy tukemaan uudempaa swagger-ui-versiota.
Why does the Swagger UI show an empty model and example for methods returning a Map?
This is a bug in Swagger-UI tool, and should be fixed in the next major version. The API description itself is still fine, so the problem is cosmetic. This will be fixed when the library we use starts to use a more recent Swagger-UI release.
Miksi datassa olevat tunnisteet ovat sellaista muotoa kuin ovat?
Tunnisteen muodosta ei pidä välittää, vaan ne pitää aina käsitellä mielivaltaisina merkkijonoina. Rajapinnan palauttamat tunnisteet ovat globaalisti uniikkeja.
Why are identifiers in the data of the format they are?
Identifiers should always be handled as opaque strings. The identifiers returned by the API are globally unique.
Säilyvätkö vanhat rajapintaversiot saatavilla?
Kyllä. Joskus niitä kuitenkin todennäköisesti tullaan poistamaan, joten pyrithän käyttämään uusinta saatavillaolevaa versiota.
Will all the old API versions be kept available?
Yes. Although most likely some day the oldest ones are going to be removed, so please always try to use as recent version as possible.
Säilyvätkö vanhat rajapintaversiot muuttumattomina?
Rajapintalupauksena kyllä. Korjauksia niihin kuitenkin tehdään. Lisäyksiä saattaa myös tulla, esimerkiksi kokonaan uusi rajapintametodi, tai uusi vastausmuoto, tai uusi kenttä olemassaolevaan paluuarvoon.
Will all the old API versions be kept unmodified?
As an API promise, yes. However, corrections and bug fixes are made. Old versions might also get some additions, like a new API method, or a new response format, or a new field to an existing return value.
Missä eri muodoissa rajapinnan data on tarjolla?
Swagger-dokumentaatiosta näet ajantasaisen listan. Lähes kaikki rajapintametodit on saatavilla kaikissa vastausmuodoissa.
In what formats is the data available?
Swagger documentation will show the available formats. Almost all API methods can produce all available formats.
Miten saan piirretyä dataa kartalle?
Voit katsoa rajapinnan etusivun karttatoteutuksesta mallia.
How can I draw some data on a map?
You can use the API fronpage map implementation as an example.
Etusivun karttatoteutus on melko iso, vaikka onkin melko yksinkertainen. Miten saan edes jotakin kartalle?
Parametri määrittää ajanhetken tai aikavälin, jota voimassaololtaan leikkaavat rivit palautetaan. Yleisin tarve on 'nykyhetki', joksi suosittelemme käytettävän aina edellistä UTC-ajan keskiyötä (T00:00:00Z) välimuistiosuvuuden parantamiseksi.
What is 'time' parameter?
The parameter defines the instant or the interval determining which rows are returned. Those whose validity intersects with the value are returned. Most commond need would be 'now', for which the preceding UTC midnight (T00:00:00Z) is recommended to improve cache hit rate.
Miksi aikaleimoissa on joskus perässä Z ja joskus ei, mitä aikoja nämä ovat?
Rajapinta palauttaa aikaleimat UTC-ajassa (Z), ja jättää aikavyöhykemuunnokset käyttäjän harteille. Ihmisen luettavaksi tarkoitetuissa vastausmuodoissa (HTML, CSV, XLSX) kuitenkin palautetaan aikaleimat Suomen aikavyöhykkeessä sekaannusten välttämiseksi.
Why do timestamps sometimes have a trailing Z and sometimes not? What times are these?
The API returns timestamps in UTC (Z) thus leaving possible time zone handling for the user. Except in formats meant primarily for human consumption (HTML, CSV, XLSX) the stamps are in Finland's timezone to prevent mixups.
Pitääkö minun rajoittaa propertyName-parametrilla data aina mahdollisimman pieneksi?
Se riippuu. Osa datasta on raskaampi hakea tai laskennallista, joten sinänsä kannattaa pyytää vain se mitä tarvitsee. Toisaalta, välimuistiosuvuuden parantamiseksi kannattaa varioida parametreja mahdollisimman vähän. Jos haluat lähes kaiken datan, kannattaa todennäköisesti olla rajoittamatta sitä.
Do I need to use propertyName-parameter to limit the response to as small as possible?
It depends. Some of the data is heavy to acquire or calculated in real time, so often you might want to ask only what you need. On the other hand, to improve cache hit ratio, as common set of parameter should be used as possible. If you need almost all the data, you probably should not limit it.
Mitä arvoja propertyName-parametri hyväksyy?
Karkeastiottaen ne, jotka näkyvät kyseisen rajapintametodin HTML-muodon sarakeotsikkoina.
Useimmissa vastauksissa sallitaan ikuinen välimuistitus, voinko luottaa tähän?
Kyllä, cache-control-headereihin voi luottaa, ja voit näinollen halutessasi laittaa kutsujen väliin oman välimuistipalvelimen mikäli koet sen hyödylliseksi käyttötapaukseesi.
Most responses are allowed to be cached eternally. Can I trust this?
Yes, you should trust cache-control headers. Thus you can easily add a transparent caching proxy between you and the API if you find it useful.
Miksi rajapinta tekee paljon redirectejä?
Välimuistituksen parantamiseksi. Tekemällä uudelleenohjauksia voidaan varsinaiset dataa palauttavat vastaukset välimuistittaa useimmiten ikuisesti.
Why does the API make a lot of redirects?
To improve caching. To change the target of a redirect whenever the data is somehow changed, the responses returning the actual data can mostly be cached eternally.
Mikä on urlin alkuun ilmestyvä numerosarja?
Se kuvaa tietokannan datan jonkinlaista versionumeroa. Mikäli numero ei muutu, ei datakaan ole päivittynyt tietokannassa. Tätä numeroa EI kuulu liittää mukaan varsinaisiin kutsuttaviin rajapintametodeihin, vaan niihin siirrytään uudelleenohjauksen kautta. Paitsi jos haluat optimoida pois joitakin uudelleenohjauksia, ja hoidat datan päivittymisen tarkastelut manuaalisesti, missä tapauksessa numerosarjaa tulisi käsitellä mielivaltaisena merkkijonona.
What's the sequence of numbers appearing in the beginning of the API relative URI path?
It describes a kind of a version number of the data in the database. As long as the number doesn't change, the data in the database also stays the same. This number should NOT be included in actual requests, they should only appear as redirect targets. Unless you want to optimize some redirects away and manually observe changes updating the number when needed, in which case the number should be treated as an opaque string.
Näenkö bi-temporaalisuuden toista historiaa (transaktioaika) jos muutan URL:n alkuun ilmestyvää numeroa?
Vain niiltä osin mitä sattuu säilymään jossakin HTTP-välimuistissa. Vaikka rajapinta kertookin historian (validisuusaika), ei se ole bi-temporaalinen.
Can I observe the 'other' history (transaction time) of bi-temporality if I change the number appearing in the URL?
Only those parts that happen to be stored in a HTTP cache somewhere. Even though the API knows history (valid time), it's not bi-temporal.
Mitä tarkoittaa bi-temporaalisuus?
Se ei mahdu tämän FAQ:n scopeen.
What is bi-temporality?
It's out of scope for this FAQ.
Miksi monet JSON-vastaukset tulevat objektina eivätkä listana?
Kyseltäessä yksittäisellä ajanhetkellä, sisältävät avaimen alla olevat listat aina vain yhden rivin, joka kuvaa miltä käsite näyttää kyseisellä ajanhetkellä. Kyseltäessä aikavälillä, voi tuo lista sisältää useita rivejä mikäli käsite muuttuu jotenkin pyydetyllä aikavälillä. Objekti-rakenne takaa, että yhteen käsitteeseen liittyvät rivit löytyvät aina vastaavan avaimen alta, eikä sinun tarvitse varautua siihen että taulukossa olisi joskus useampia saman käsitteen rivejä. Mikäli koet että tämä aiheuttaa ongelmia esimerkiksi tiettyjen työkalujen toimivuuden suhteen, ota yhteyttä niin mietitään jotakin.
Why are many JSON responses Maps instead of just Lists?
When querying with a single instant of time, the map keys should always containt a singleton list describing how the object looks on that instant. When querying with an interval, can that list include multiple rows if the row happens to change during that interval. Map structure allows all the rows related to the single object to be found under the single key, and you don't have to consider the case when multiple rows of a single list refer to the same object identity. If you find this troublesome for example related to some specific tooling, please let us know and we'll think of something.
Miksi pyynnöissä on niin tiukat vaatimukset, kuten parametrien aakkosjärjestys?
Välimuistiosuvuuden parantamiseksi. Mikäli koet että tämä aiheuttaa ongelmia esimerkiksi tiettyjen työkalujen toimivuuden suhteen, ota yhteyttä niin mietitään jotakin.
Why are there such strict requirements for requests, like the alphabetical order of query parameters?
To improve cache hit ratio. If you find this troublesome for example related to some specific tooling, please let us know and we'll think of something.
Missä koordinaattijärjestelmässä geometriat ovat?
Oletuksena ETRS-TM35FIN-karttaprojektio ja -tasokoordinaatisto (EPSG:3067).
In which coordinate system are the geometries in?
By default, ETRS-TM35FIN projection and plain coordinate system (EPSG:3067)
Mitä muita koordinaattijärjestelmiä on tarjolla?
Saat vastaukset myös WGS84-muodoissa antamalla parametrin srsName=epsg:4326 tai srsName=crs:84 tai srsName=epsg:3857. Tällöin myös mahdolliset koordinaatteja sisältävät kyselyparametrit olettavat saavansa vastaavaa muotoa. 'bbox'-parametrin koordinaattijärjestelmän voit määrätä erikseen viidennellä arvolla.
What other coordinate systems are available?
The responses are available also in different WGS84 formats specified by query parameter srsName=epsg:4326 or srsName=crs:84 or srsName=epsg:3857. Then also possible coordinate values in request parameters are assumed to be in this format. The format of 'bbox'-parameter can be specified separately with a fifth value.
Miten päin WGS84:n longitude ja latitude ovat koordinaateissa?
Tämä rajapinta välttää paikkatietomaailman ongelman antamalla käyttäjän valita. srsName=epsg:4326 määrää järjestyksen lat,lon kun taas srsName=crs:84 päinvastaiseen järjestykseen. Sekasotkusta voi lukea lisää vaikkapa täältä.
Which way in WGS84 are longitude and latitude given?
This common problem is avoided by letting the user decide. srsName=epsg:4326 puts them in lat,lon while srsName=crs:84 in the opposite order. The problem is described in for example here.
Vektorit vai rasteroidut kuvat?
Oma valintasi. Kuvat voivat olla suorituskykyisempiä erityisesti mobiililaitteissa, mutta vektorien kanssa voi vuorovaikuttaa. Vektorit ovat aina tarkkoja kaikilla zoom-tasoilla, kun taas kuvat pitää ladata erikseen tarkemmille zoom-tasoille. Yksi mahdollisuus on ladata 'korkeilla' zoom-tasoilla tasot kuvina ja vaihtaa vektoreihin kun lähestytään zoom-tasoa, jolla käyttäjän voisi olettaa haluavan vuorovaikuttaa kyseisen datan kanssa.
Vectors or rasterized images?
Your choice. Images may be more performant especially in mobile devices, but vectors allow interaction. Vectors are always sharp in every zoom level, whereas images need to be loaded separately for more lower zoom levels. One possibility would be to load images on high zoom levels, and change to vectors when approaching a lower zoom level where the user might want to interact with the data in question.
Mitä 'cql_filter'-parametri tekee?
Suodattaa tulosjoukon rivejä ehtojen perusteella. Useita ehtoja voi yhdistää AND-sanalla. Toteutettuna osajoukko ECQL-filttereistä: =, <>, <, >, <=, >=, _ [NOT] BETWEEN _ AND _, _ [NOT] LIKE '%', _ [NOT] ILIKE '%', _ [NOT] IN (_,_), _ IS [NOT] NULL, INTERSECTS(_,_). INTERSECTS vaatii ensimmäiseksi parametriksi geometria-propertyn ja toiseksi POLYGON-tyyppisen WKT-geometrian.
What does 'cql_filter'-parameter do?
Filter result rows based on given conditions. Multiple conditions can be combined with AND-keyword. A subset of ECQL-filters are implemented: =, <>, <, >, <=, >=, _ [NOT] BETWEEN _ AND _, _ [NOT] LIKE '%', _ [NOT] ILIKE '%', _ [NOT] IN (_,_), _ IS [NOT] NULL, INTERSECTS(_,_). INTERSECTS requires a geometry property as its first value and a literal WKT polygon as the second.
Mitä funktioita 'cql_filter' ja 'propertyName' tukevat?
Ymmärtää rajoitetuissa paikoissa funktioita 'round', 'start', 'end' ja 'duration' sekä aritmetiikkaoperaatioita '+', '-', '*', '/'. 'start' ja 'end' voivat tietokenttien lisäksi viitata request-parametriin.
What functions do 'cql_filter' and 'propertyName' support?
Understands the following functions in limited locations: 'round', 'start', 'end' and 'duration' as well as arithmetic operators '+', '-', '*', '/'. 'start' and 'end' can refer to a request parameter in addition to data fields.
Mistä saan WKT-muotoisia polygoneja?
Voit piirtää etusivun kartalle polygonin, ja saat sen WKT-muodossa.
How can I get polygons in WKT format?
You can use the API frontpage map to draw a polygon and get its WKT format.
Miten piirrän infran kaaviomuodossa / mitä ovat kaaviogeometriat?
Käsitteillä on todellisten koordinaattisijaintien lisäksi 'kaaviokoordinaattisijainnit', joita käyttämällä data voidaan piirtää kaaviomaisena. Esitystapa voidaan valita 'presentation' parametrilla.
How can I present the data in schematic format / what are schematic geometries?
In addition to physical coordinates every geometric object has 'schematic coordinates'. These can be used to draw the data in a schematic representation by using 'presentation' query parameter.
Miten haen 'sisäkkäistä' dataa, esimerkiksi Tilirataosat yhdessä kunnossapitoalueen nimen kanssa?
Voit jatkaa propertyName-arvoja 'suhde'-tapauksissa arvon sisään, esimerkiksi 'propertyName=kunnossapitoalue.nimi'. Ei käytettävissä kaikilla vastausmuodoilla. Tämä soveltuu erityisesti ad-hoc tarpeisiin tai yksittäisen objektin laajempien tietojen kyselemiseen. Rajapintaa aktiivisesti käyttävän sovelluksen voi olla parempi hakea datat erikseen ja yhdistelemällä tarpeen mukaan omassa päässään, hyötyäkseen paremmasta cache-osuvuudesta ja pienemmistä vasteajoista.
How can I retrieve 'nested' data, like Accounting Railway Sections together with the name of their Maintenance area?
You can append nested structures to propertyName parameter values in the cases where there's a relation. For example: 'propertyName=kunnossapitoalue.nimi'. This is not available for all response formats. This is especially useful for ad-hoc needs or querying more data for a single object. Applications using the API actively are likely better to fetch different datasets separately and combine them as needed in their side, to utilize better cache hit ratio and lower response times.
Miten haen sarakkeista 'kaikki paitsi X'?
Voit jättää sarakkeita pois lisäämällä 'propertyName'-parametrissa annettuun nimeen väliviivan etumerkiksi. Tämä toimii myös 'sisäkkäisille' arvoille, mutta huomaa laittaa etumerkki sisäkkäisen nimen yhteyteen.
How can I retrieve properties 'all but X'?
You can exclude properties by prefixing the names in 'propertyName'-parameter with a hyphen. This also works for 'nested' data but remember to add the hyphen to the nested part of the name.
Miten saan rajapinnasta haettua Liikennepaikkojen ja Liikennepaikkavälien muodostaman graafin?