REST/JSON-hakurajapinta?

Lajitietokeskus API.laji.fi
, ,
1

Hei, olisiko mahdollista saada havaintojen hakuun REST/JSON-rajapinta. Esim. hyönteistietokannassa voidaan käyttää seuraavanlaista hakua:

$.ajax({
url: ‘http://hyonteiset.luomus.fi/insects/rest/search/Coleoptera’,
data: { auth: ‘’,
     family: ‘Carabidae’,
    genus: ‘Cicindela’,
    species: ‘campestris’,
    select: ‘DISTINCT year,coordinates10x10’,
    orderBy: ‘year’ },
dataType: ‘json’ })
.done(function( data )
{
  console.log( JSON.stringify( data ) );
})
.fail( function( xhr, textStatus, errorThrown )
{
  console.log( xhr.status, xhr.statusText, xhr.responseText );
});

2

Rajapinta Lajitietokeskuksen uuteen tietovarastoon ja muihin palveluihin on olemassa, määritelty täällä: https://api.laji.fi/

Dokumentaatiota ja käyttöohjeita on tulossa hieman myöhemmin.

3

Joissakin rajapinnan toiminnoissa tarvitaan PersonToken-arvoa. Mihin se liittyy ja mistä sellaisen saa?

4

PersonTokenin saa laji-authista ja sitä käytetään identifioimaan kirjautunut käyttäjä. Laji-auth puolestaan on järjestelmä, joka hoitaa käyttäjien kirjautumisen ja siitä on tulossa myöhemmin dokumentaatio.

5

PersonToken tarvitaan vain kyselyihin, joissa kirjautunut käyttäjä tekee jotain (esim pyytää tiedostolatauksen).

Havaintojen hakua varten /warehouse/query/* on oleellisin.

Mallia voi ottaa esim beta.laji.fi 'n tekemistä kyselyistä, niiden parametrit ovat samoja joita tämä julkinen api ottaa vastaan.

(beta.laji.fi kaikkine toimintoineen perustuu puhtaasti api.laji.fi’n avoimiin rajapintoihin, eikä vastaavan portaalin toteutukseen tarvita mitään erityisoikeuksia).

6

Esim. tämän kaltainen jQuery-haku näyttäisi toimivan:

$.ajax({
    url: ‘https://apitest.laji.fi/v0/collections’,
         data: { langFallback: true,
             pageSize: 200,
             access_token: ‘*****’ },
             dataType: ‘json’ })
     .done(function( data )
     {
         console.log( data )
     })
     .fail(function( xhr )
     {
         console.log( xhr.status, xhr.statusText, xhr.responseText )
     })

7

Kyllä juuri noin. Voit käyttää myös sitä API dokumentaatio sivua testaamaan millaisia vastauksia rajapinta antaa, pistämällä api.laji.fi:ssä access tokenin kenttään sivun oikeassa yläkulmassa ja sitten valitsemalla halutut arvot kenttiin ja klikkaamalla “try it out”-nappia.

8

Noin olen juuri tehnytkin. Varsinaisten havaintojen haku onkin hieman työläämpää kenttien suuren lukumäärän takia. Uskoisin, että tietokannalle voidaan saada huomattavastikin lisäarvoa kehittämällä sille uusia, käyttäjiä kiinnostavia hakutoimintoja.

1 tykkäys
9

Kuulostaa oikein hyvältä. Otamme erittäin mielellään vastaan kehitysideoita

10

Tein kokeeksi Taxa -api-rajapinnan avulla perhosluettelon, jossa on heimot, suvut ja lajit lisättynä vastaavilla id-tunnuksilla. http://insects.fi/hyonteistietokanta/files/Lep-SpeciesCatalog.csv

11

Perushaku näyttäisi palauttavan havainnon (unit) koordinaatit kentässä ‘gathering.conversions’, esim.

{ wgs84CenterPoint: { lat: 64.86617698759933, lon: 25.48549175262451 } }

Onko tuolle olemassa muunnospalvelua YKJ-koordinaateiksi?

/warehouse/query/single -haulla YKJ-koordinaatit saanee (jos ne on ilmoitettu) koko dokumentin tiedoista, mutta se on ehkä vähän turhan työläs tapa…

12

Tällä Luomuksen vanhalla rajapinnalla voi muuntaa koordinaatteja wgs84 → ykj: http://koivu.luomus.fi/projects/coordinateservice/json/?from=WGS84&to=YKJ&n=64.86617698759933&e=25.48549175262451

13

Moi, /warehouse/query/list rajapinnassa on myös valittavana sarakkeet:

  • gathering.conversions.ykj.latMax
  • gathering.conversions.ykj.latMin
  • gathering.conversions.ykj.lonMax
  • gathering.conversions.ykj.lonMin
  • gathering.conversions.ykj3.lat
  • gathering.conversions.ykj3.lon
  • gathering.conversions.ykj4.lat
  • gathering.conversions.ykj4.lon

Vastaukseen halutut arvot voi luetella selected-parametrin arvoina.

(YKJ3 = kymmpiruutu, YKJ4 = kilometriruutu)

Kaikkien havaintojen koordinaatit ovat jo tietovarastossa valmiina muunnettuna wgs84, ykj euref -koordinaatistoihin. (Ulkomaisista havainnoista on vain wgs84 koordinaatit).

14

Ainiin, riittää myös pistää gathering.conversions.ykj jolloin saa latmax/min,lonmax/min ilman että pitää luetella ne kaikki

15

Tällainen Node.js-haku näyttäisi toimivan:

http://pastebin.com/Kj4C14gQ

1 tykkäys
16

Kokeilin hakua pelkästään taxonID:n perusteella:

let taxonID = ‘MX.61523’
let taxonName = ‘Jodis putata’

.get(‘https://apitest.laji.fi/v0/warehouse/query/list’ )
      .query({ taxonId: query.taxonID,
      pageSize: 100,
      page: query.page,
      selected: ‘gathering.conversions.year,gathering.conversions.ykj’,
      orderBy: ‘gathering.conversions.year’,
      access_token: accessToken })


Mistähän mahtaa johtua, että vastaava haku Hyönteistietokannasta tuottaa huomattavasti enemmän havaintoja samasta lajista? Yllä oleva haku tuottaa 6 sivua, yhteensä 583 havaintoa (poistettu pari virheellistä koordinaattia). Hyönteistietokannasta löytyy lajista yli 4000 havaintoa. Laji.fi:n oma hakusivu löytää kyllä yli 7000 havaintoa, joten joku tässä ei ole kohdallaan…

1387×712 188 KB

17

Voi olla, että tuo testirajapinta antaa tulokset www.laji.fi-sivun tietokannasta, johon ei ole ajettu kaikkea Hyönteistietokannan havaintodataa, kun taas beta.laji.fi sisältää kaiken Hyönteistietokannan datan.

18

apitest.laji.fi sisältää osajoukon kaikesta datasta testikäyttöä varten (nyt reilut miljoona havaintoa, mukana mahdollisesti myös keksittyjä havaintoja), api.laji.fi taas kaiken sen datan, joka näkyy myös portaalissa.

19

api.laji.fi antaa tulokseksi {“status”:403,“message”:“Must give a valid access_token”}…

20

api ja apitest:n access_tokenit eivät ole yhteensopivia ja siksi saat tuon virheviestin. Voit pyytää access_tokenin joka toimii api.laji.fi:ssä samaantapaan kuin tuolla apitest.laji.fi:ssä käyttäen api.laji.fi:tä