Remote API for the Finnish Entomological Database
Matti Virtala, 2012
1. Introduction
2. Alphabetical List of the API Commands
3. The API Commands
1. Introduction
This document describes the current remote JSONP API for the Finnish Entomological Database. More API methods can be added in future, so you might want to temporarily check out this documentation for new additions.
For most methods a simple html page, using the jQuery library, is presented. This will give you an idea how a certain method can be used.
The html page contains an element <div id='result'></div>. The JavaScript file retrieves the data from the server and inserts the list of records into the div with the jQuery method $('#result').html(list).
More advanced applications work basically in the same way: results are inserted dynamically into an html page. The flexibility of the remote interface is demonstrated by the database interface application Finnish Entomological database, which is implemented entirely using the remote API.
2. Alphaphetical List of the API Commands
eurefToYkj
getAllGenera
getCounts
getFamilies
getFamilyAndRegion
getGenera
getObsData
getObserverAndRegion
getObservers
getSpecies
getTotalCount
getYearlyObserved
search
3. The API Commands
eurefToYkj
A utility to convert a EUREF coordinate into a Finnish YKJ
coordinate.
URL:
http://hyonteiset.luomus.fi/insects/json?op=eurefToYkj&euref=7214227:8440171
Parameters:
| parameter | description | usage |
|---|---|---|
| euref | The euref coordinate | euref=7214227:8440171 |
getAllGenera
Returns all genera in the given order. In the UI, this method is used in a new observation form to allow the user to select a genus from a combobox.
URL:
http://hyonteiset.luomus.fi/insects/json?op=getAllGenera&order=het
Parameters:
| parameter | description | usage |
|---|---|---|
| order | Insect order | order=het |
Example: GetAllGenera.html
getCounts
Returns the number of observations or number of species in different categories.
URL:
http://hyonteiset.luomus.fi/insects/json?op=getCounts&order=col&family=Carabidae&category=year&count=nbrObs
Parameters:
| parameter | description | usage |
|---|---|---|
| order | Insect order | order=col |
| category | Defines the categories in which the counts are calculated. | category=region category=year category=storingYear category=family |
| count | Determines whether the number of observations or number of species are calculated. | count=nbrObs count=nbrSpecies |
| countStartYear | If category=year, countStartYear can be used to define the starting year. Defaults to 1950. | countStartYear=1990 |
| query parameters | In addition to 'category' and 'count', other parameters can also be provided. These parameters delimit the set of observations for which the counts are calculated. | family=Carabidae See search for additional examples on providing query parameters. |
Example: GetCounts.html
getFamilies
Returns the families in the given order.
URL:
http://hyonteiset.luomus.fi/insects/json?op=getFamilies&order=lep
http://hyonteiset.luomus.fi/insects/json?op=getFamilies&order=lep&orderBy=speciesNbr
Parameters:
| parameter | description | usage |
|---|---|---|
| order | Insect order | order=lep |
| orderBy | Sort order of the families | not present - If not present, the families are sorted alphabetically orderBy=speciesNbr - the families are sorted in taxonomic order |
Example: GetFamilies.html
getFamilyAndRegion
Returns the number of observations in each family and region.
URL:
http://hyonteiset.luomus.fi/insects/json?op=getFamilyAndRegion&order=hym
Parameters:
| parameter | description | usage |
|---|---|---|
| order | insect order | order=col |
Example: GetFamilyAndRegion.html
getGenera
Returns all genera in the given family.
URL:
http://hyonteiset.luomus.fi/insects/json?op=getGenera&order=dip&family=Syrphidae
http://hyonteiset.luomus.fi/insects/json?op=getGenera&order=dipP&family=Syrphidae&orderBy=speciesNbr
Parameters:
| parameter | description | usage |
|---|---|---|
| order | Insect order | order=dip |
| family | The family | family=Syrphidae |
| orderBy | sort order of the genera | not present - If not present, the genera are sorted alphabetically orderBy=speciesNbr - the genera are sorted in taxonomic order |
Example: GetGenera.html
getObsData
For personal use. Returns the observation data for the given obsID.
Note that you can use search to retrieve observation data without needing to provide a username and password.
URL:
http://hyonteiset.luomus.fi/insects/json?op=getObsData&order=ara&obsID=9661-1216-6008-4622&username=uname&password=pw
Parameters:
| parameter | description | usage |
|---|---|---|
| order | Insect order | order=ara |
| obsID | Observation id | obsID=9661-1216-6008-4622 |
| username | Your username | username=your_username |
| password | Your password | password=your_password |
The following fields are returned:
obsID
genus
species
mCount
fCount
tCount
devStage
region
county
locality
ykjCoordinates
eurefCoordinates
originalGrid
startDay
startMonth
endDay
endMonth
year
habitat
method
observe
det
detYear
detMethod
note
hideExactData
hideCoord
hideObserver
reliability
checked
Example:
getObserverAndRegion
Returns the number of observations for each observer and region.
URL:
http://hyonteiset.luomus.fi/insects/json?op=getObserverAndRegion&order=het
Parameters:
| parameter | description | usage |
|---|---|---|
| order | Insect order | order=het |
Example: GetObserverAndRegion.html
getObservers
Returns a list of all observers for the given order.
URL:
http://hyonteiset.luomus.fi/insects/json?op=getObservers&order=tri
Parameters:
| parameter | description | usage |
|---|---|---|
| order | Insect order | order=tri |
Example: GetObservers.html
getSpecies
Returns the list of species in the given genus.
URL:
http://hyonteiset.luomus.fi/insects/json?op=getSpecies&order=ara&family=Agelenidae&genus=Tegenaria
http://hyonteiset.luomus.fi/insects/json?op=getSpecies&order=ara&family=Agelenidae&genus=Tegenaria&orderBy=speciesNbr
Parameters:
| parameter | description | usage |
|---|---|---|
| order | Insect order | order=ara |
| family | The family | family=Agelenidae |
| genus | The genus | genus=Tegenaria |
| orderBy | Sort order of the species | not present - If not present, the species are sorted alphabetically orderBy=speciesNbr - the species are sorted in taxonomic order |
Example: GetSpecies.html
getTotalCount
Returns the total number of observations in the given order.
URL:
http://hyonteiset.luomus.fi/insects/json?op=getTotalCount&order=ple
Parameters:
| parameter | description | usage |
|---|---|---|
| order | Insect order | order=ple |
Example: GetTotalCount.html
getYearlyObserved
Returns the number of observations for each region and year.
URL:
http://hyonteiset.luomus.fi/insects/json?op=getYearlyObserved&order=col
Parameters:
| parameter | description | usage |
|---|---|---|
| order | Insect order | order=col |
Example: GetYearlyObserved.html
search
Search is the most versatile remote API operation you can use. In the url you can provide two kinds of parameters: search parameters and output parameters. The search parameters are used to define the set of observations in the result set. The output paramers describe the set of fields which are displayed in each record.
Here is an example:
http://hyonteiset.luomus.fi/insects/json?op=search
&order=col&family=Carabidae&startYear=2012&endYear=2012 // search
&select=speciesName,obsLocation,obsDate,observer // output
The above url returns a list of the following types of items:
[...{"speciesName":"Cicindela campestris",
"obsLocation":"Oba:Haukipudas, Hakoselkä 722471:343412",
"observer":"M. Virtala",
"obsDate":"13.06-16.06.2009"}, ...]
To define the result set, you can use the following fields:
Search fields:
| field | example |
|---|---|
| obsID | obsID=1234-5678-9012-3456 |
| storingDate | storingDate=2003* storingDate=2003-05* |
| order | order=col |
| family | family=Carabidae |
| genus | genus=Amara |
| species | species=aulica |
| region | region=Oba |
| county | county=Oulu |
| locality | locality=Hietasaari |
| coordinates | coordinates=721:342 |
| startDay | startDay=1 |
| startMonth | startMonth=6 |
| endDay | endDay=31 |
| endMonth | endMonth=6 |
| startYear | startYear=2012 |
| endYear | endYear=2012 |
| habitat | habitat=niitty habitat=*niitty |
| method | method=ansakuopilla method=ansa* |
| observer | observer=M. Virtala observer=*Virtala |
| det | det=*Virtala |
| detYear | detYear=2012 |
| detMethod | detMethod=lab. määritys |
| reliability | reliability=0 |
| checked | checked=Tarkistettava* |
| speciesFreq | speciesFreq=60 |
| uhex | uhex='NT' |
Additional criteria can be defined with a userCondition parameter, for example as follows:
userCondition=speciesFreq >= 60
userCondition=today // Observations made today
userCondition=yesterday // Observations made yesterday
userCondition=yesterday+ // Observations made yesterday and today
userCondition=week // Observations made last week
The ordering of the records is defined by the orderBy parameter, e.g.
orderBy=region,year
By default, observations are presented in taxonomic order.
Output fields
The data fields which will be included in the result set are defined by the select parameter. The following output fields are available:
obsID
storingDate
family
genus
species
speciesFreq
uhex
region
county
locality
coordinates
startDay
startMonth
endDay
endMonth
year
habitat
method
observer
det
detYear
detMethod
note
reliability
checked
These are raw fields which are stored in the database. In addition, the following derived values can also be used:
all
speciesName
obsLocation
coordinates10x10
obsDate
Duplicate records can be omitted by using the DISTINCT keyword, e.g.
select="DISTINCT genus,species"
Example: The all parameter
The output criterion select=all provides an easy way to include all output fields into the result. For example, the url
http://localhost:8080/insects/json?op=search&order=COL&obsID=9557-2467-8340-6282&select=all
produces the following result:
{"region":"Lkor","
"det":"M. Pentinsaari",
"endDay":"",
"reliability":"0",
"detMethod":"ZMO",
"obsID":"9557-2467-8340-6282",
"observer":"J. Itämies & O. Nenonen",
"totalCount":" ",
"family":"Carabidae",
"startDay":"13",
"method":"",
"year":"2000",
"note":"2B PF",
"speciesFreq":"2480",
"detYear":"2000",
"species":"terminatus",
"genus":"Leistus",
"storingDate":"2003-10-04",
"devStage":" ",
"habitat":"",
"uhex":"",
"county":"Sodankylä",
"locality":"Mutenia",
"startMonth":"9",
"checked":"",
"endMonth":"",
"speciesName":"Leistus terminatus",
"obsLocation":"Lkor:Sodankylä, Mutenia 754:351",
"coordinates":"754:351",
"obsDate":"13.09.2000"}
]
For clarity, the additional derived fields speciesName, obsLocation, coordinates and obsDate have been emphasized.
Obviously, if you only need a small number of fields, you might specify them directly in a select list instaed of the select=all option.
Example: Species list
http://hyonteiset.luomus.fi/insects/json?op=search&order=COL®ion=Oba&select=DISTINCT%20family,speciesName
[
{"family":"Haliplidae","speciesName":"Haliplus lineolatus"},
{"family":"Haliplidae","speciesName":"Haliplus immaculatus"},
....
{"family":"Curculionidae","speciesName":"Trypodendron signatum"}
]
Example: 10x10km coordinate data
http://hyonteiset.luomus.fi/insects/json?op=search&order=COL&genus=Carabus&species=violaceus&select=DISTINCT%20coordinates10x10
[
{"coordinates10x10":"729:339"},
{"coordinates10x10:"729:338"},
...
{"coordinates10x10":"727:354"}
]
Example: Rare observations
http://hyonteiset.luomus.fi/insects/json?op=search&order=COL&userCondition=speciesFreq%3E=60&select=speciesName,obsLocation,obsDate,speciesFreq
[
{"speciesName":"Gyrinus suffriani",
"speciesFreq":"80",
"obsLocation":"Sa:Valkeala 6758:3497",
"obsDate":"03.06.1991"},
....
]
Example: Recent observations
http://hyonteiset.luomus.fi/insects/json?op=search&order=COL&userCondition=week&select=speciesName,obsLocation,obsDate,collector