Löydös-järjestelmän julkinen rajapinta

Yleistä

Luonnontieteellisen keskusmuseon kaikille avointa Löydös-järjestelmää käytetään julkisen havaintotiedon keräämiseen sähköisillä lomakkeilla. Kerätty tieto tallennetaan järjestelmän tietokantaan sekä mahdollisesti muihin luonnontieteellisen keskusmuseon tai sen yhteistyökumppanien järjestelmiin tutkimuskäyttöä varten.

Joidenkin lomakkeiden kautta kerättävä havaintotieto on luonteeltaan julkista ja siksi Löydös-järjestelmä tarjoaa yleisölle avoimen web-rajapinnan sekä em. rajapintaa hyödyntävän selaimen kerätyn havaintotiedon tarkastelemiseksi sekä lataamiseksi.

Huomaa, että kaikki lomakkeella kerätyt tiedot eivät välttämättä näy rajapinnassa. Esimerkiksi yksityiskohtaiset henkilötiedot ja osoitteet eivät ole näkyvillä. Joidenkin lomakkeiden kohdalla on myös mahdollista määritellä lomakkeen tietoja salaisiksi jolloin niitä ei näytetä julkisessa rajapinnassa.

Rajapinnan käyttäminen

Rajapinta on toteuttettu REST-tyylisenä web-rajapintana jossa tieto välitetään HTTP-protokollan avulla JSON-muodossa.

Tietomuoto

Kaikki Löydös-järjestelmän lomakelähetykset noudattavat yhteistä tietomuotoa jota on lomakekohtaisesti laajennettu.

Kaikille lomakkeille yhteiset kentät

• id - Lomakkeen uniikki tunniste
• submissionTime - Lähetysaika (Suomen paikallista aikaa)
• additionalInfo - Lomakelähetyksen lisätiedot
• formType - Lomakkeen tyypin nimi, voidaan käyttää esim. kaikkien tyypin lomakkeiden hakemiseen rajapinnasta
• location - Havainnon sijainnin kuvaileva olio
• coordinates - Taulukko joka sisältää koordinaatteja, yhden koordinaatin sisältävä taulu vastaa yhtä pistettä kartalla kun taas useampi koordinaatti vastaa taulukon järjestyksen mukaisesti pisteiden muodostamaa kuviota. Kaikki koordinaatit käyttävät WGS84-koordinaattijärjestelmää.
• latitude - Pohjoiskoordinaatti desimaalimuodossa
• longitude - Itäkoordinaatti desimaalimuodossa
• municipality - Kunta tai sitä vastaava hallinnollinen yksikkö
• description - Vapaamuotoinen sijainnin kuvaus
• country - Löydön sijainti, voi olla lyhennemuodossa ("FI") tai selväkielisenä ("Suomi")
• hidden - Totuusarvo joka ilmaisee onko lähetyksen sijaintitiedot piilotettu
• submitters - Kaikki lomakkeen lähettäjien tiedot sisältävä taulukko
• firstName
• lastName
• city
• postalCode
• hidden - Totuusarvo joka ilmaisee onko lähettäjän tiedot piilotettu

Salatut kentät

Joidenkin lomakkeiden yhteydessä käyttäjä voi määritellä joko löydön sijainnin tai omat henkilötietonsa piilotettavaksi. Kentät joihin tietojen piilotus vaikuttaa esitetään joko tyhjinä (koordinaattitaulukot) tai "[hidden]"-teksteinä.

Kaikki lomakkeet

Rajapinnan kaikki lomakkeet ovat haettavissa kaikille lomakkeille yhteisessä muodossa joka sisältää lomakkeen perustiedot. Lomakekohtaisten havaintotietojen tarkastelemiseksi tulee tehdä lomaketyypin mukainen pyyntö (kts. seuraava osa).

Mallipyyntö

GET api/submissions/

200 OK content-type:text/json

            [
                {
                    id: "5135ef812b15ad56b07fa8cb",
                    submissionTime: "2013-03-05T15:13:37.852",
                    validated: true,
                    additionalInfo: null,
                    location: {
                        coordinates: [ ],
                        municipality: "Aura",
                        description: null,
                        country: null,
                        hidden: false
                    },
                    submitters: [
                        {
                            firstName: "jujj",
                            lastName: "kk",
                            city: null,
                            postalCode: null,
                            hidden: false
                        }
                    ],
                    formType: "kevatseuranta"
                },
                {
                    id: "5151a1a3b23fc3d9e471977d",
                    submissionTime: "2013-03-26T15:24:51.294",
                    validated: true,
                    additionalInfo: null,
                    location: {
                        coordinates: [
                            {
                                latitude: 60.64542082082282,
                                longitude: 22.58617401123047
                            }
                        ],
                        municipality: "Aura",
                        description: null,
                        country: null,
                        hidden: false
                    },
                    submitters: [
                        {
                            firstName: "tsr",
                            lastName: "te",
                            city: null,
                            postalCode: null,
                            hidden: false
                        }
                    ],
                    formType: "kevatseuranta"
                }
            ]
        

Kaikki lomaketyypin lomakkeet

Esimerkkipyyntö

GET api/submissions/luontohavainto/

200 OK content-type:text/JSON

        [
            {
                id: "51543653b4b7d86f35cf52c3",
                submissionTime: "2013-01-08T13:50:00.000",
                validated: null,
                additionalInfo: "",
                location: {
                    coordinates: [ ],
                    municipality: "Mäntyharju",
                    description: "[hidden]",
                    country: null,
                    hidden: true
                },
                submitters: [
                    {
                        firstName: "[hidden]",
                        lastName: "[hidden]",
                        city: null,
                        postalCode: null,
                        hidden: true
                    }
                ],
                observation: {
                    date: "2013-01-05",
                    amount: "1",
                    species: "Harmaapäätikka",
                    additionalInfo: "Ruokaili mökkipihan rasvapötköllä"
                },
                formType: "luontohavainto"
            },
            {
                id: "51543653b4b7d86f35cf52c4",
                submissionTime: "2013-01-08T14:44:00.000",
                validated: null,
                additionalInfo: "",
                location: {
                    coordinates: [
                        {
                            latitude: 60.32762758373686,
                            longitude: 25.06659507751465
                        }
                    ],
                    municipality: "Vantaa",
                    description: "Rekola, Ojanvarsi Pertinkujan ja Suomantien risteyksessä",
                    country: null,
                    hidden: false
                },
                submitters: [
                    {
                        firstName: "Tero",
                        lastName: "Taponen",
                        city: null,
                        postalCode: null,
                        hidden: false
                    }
                ],
                observation: {
                    date: "2012-07-01",
                    amount: "",
                    species: "jättipalsami",
                    additionalInfo: ""
                },
                formType: "luontohavainto"
            }
        ]
    

Yksittäinen lomake

GET api/submissions/luontohavainto/51543653b4b7d86f35cf52c4

200 OK content-type:text/JSON

               {
                   id: "51543653b4b7d86f35cf52c4",
                   submissionTime: "2013-01-08T14:44:00.000",
                   validated: null,
                   additionalInfo: "",
                   location: {
                       coordinates: [
                           {
                               latitude: 60.32762758373686,
                               longitude: 25.06659507751465
                           }
                       ],
                       municipality: "Vantaa",
                       description: "Rekola, Ojanvarsi Pertinkujan ja Suomantien risteyksessä",
                       country: null,
                       hidden: false
                   },
                   submitters: [
                       {
                           firstName: "Tero",
                           lastName: "Taponen",
                           city: null,
                           postalCode: null,
                           hidden: false
                       }
                   ],
                   observation: {
                       date: "2012-07-01",
                       amount: "",
                       species: "jättipalsami",
                       additionalInfo: ""
                   },
                   formType: "luontohavainto"
               }

Selain

Rajapinnan tietojen tarkasteluun ja hakemiseen voidaan käyttää Löydöksen omaa web-pohjaista selainta jossa on mm. sisäänrakennettu kartta.

Kaikki lähetykset
Kaikki kevätseurannan lähetykset