Introduction: Difference between revisions

From Biolovision Help
Jump to navigation Jump to search
(API introduction)
 
 
(30 intermediate revisions by 3 users not shown)
Line 1: Line 1:
== Introduction ==
<br/>


Biolovision API is a RESTful HTTP-based API that can be used to get data such as observations, places, species, grids or other information related to the host website.
All data submitted to a [[Local portals and partners|local portal]] or recorded through the App [[Main Page#Mobile interface|NaturaList]] and synchronised, is stored at [https://data.biolovision.net/ https://data.biolovision.net]. <br/>
Searching observations on any parameter (location,species,date, ...) can be done just as it is done on the website and uses the rights of the observer for providing the data that can be accessed.
<br/>
To provide examples we will work with a tool named [https://chrome.google.com/webstore/detail/postman/fhbjgbiflinjbdggehcddcbncdddomop Postman], which is a plugin that can be installed through Chrome plugin center.
Before starting to do any of the tests please ensure you have the 4 following information: a working '''login/password''' for the website you will use, a '''consumer''' and '''secret key''' for oauth autentification.


=== Examples ===
It serves as worldwide unique portal and: <br />
<span style="color: #000000; margin-left: 25px;"><b>· </b>Stores observations in areas not covered by any local portal <br/>
<span style="color: #000000; margin-left: 25px;"><b>· </b>Stores observations for all taxonomic groups independently of the taxonomic groups opened on each local portal<br/>
<br/>


==== Taxonomics groups ====
At the moment one cannot edit observations or see other's data. Sounds and images are stored although it is not currently possible to see them.  
Each website has different taxonomic groups activated or not. This query will give a list of taxonomic groups and if they are active or not. It is a short example, that is a good starting point to test because data is small and can be quickly obtained.


Inside a new Postman query you need to:
Registered users can: <br />
# Choose the method GET
<span style="color: #000000; margin-left: 25px;"><b>· </b>[[Browsing records (data)|See own data]] <br />
# Write the query ''' ''HOSTNAME''/api/taxo_groups?'''
<span style="color: #000000; margin-left: 25px;"><b>· </b>[[Export records|Export own data]] <br />
# Enter the GET params, that will be used for the query. In this case '''user_email''' and '''user_pw''' with the corresponding values.
<span style="color: #000000; margin-left: 25px;"><b>· </b>Share own data <br />
# In the Authorization tab choose '''OAuth 1.0'''
<span style="color: #000000; margin-left: 25px;"><b>· </b>[[Ephemeris|Calculate ephemerides]] <br />
# Enter the consumer key and consumer secret key
<span style="color: #000000; margin-left: 25px;"><b>· </b>See some statistics <br />
# Enter the Token line which will be ''' ''HOSTNAME''/index.php?m_id=1200&cmd=request_token'''
<span style="color: #000000; margin-left: 25px;"><b>· </b>[[Introduction#Observations|See data submissions worldwide in real time]] <br />
# Choose the method signature '''HMAC-SHA1'''
<br/>
# Tick "Add params to header"
# Tick "Auto add parameters"


At the end it should look like this:
__TOC__


[[Fichier:Taxo group.png|none|900px|vignette|left|Printscreen from Postman - API query : GET taxo_groups]]
=Main interface=
<br/>


<center>
<div class="toc" style="border-radius:5px;background-color:#ffffff;padding-left:8px;padding-right:8px; padding-bottom:8px;width:800px;">
[[File:Main interface.png|800px|link=https://help.biolovision.net/images/c/c1/Main_interface.png]]
<div class="toc" style="border-radius:5px;padding-left:15px;text-align:left; font-size:12px;width:775px;">
'''Main interface.'''
</div>
<p style="color:black;font-size:12px;padding-left:30px;text-align:left;column-count:3;">
<b>1.</b> [[Introduction#Register|Registration]] <br />
<b>2.</b> [[Introduction#Languages|Languages]]<br/>
<b>3.</b> [[Introduction#Main menu|Main menu]] <br />
<b>4.</b> [[Introduction#Observations|Real time observations]] <br/>
<b>5.</b> [[Introduction#Ephemerides|Ephemerides]] <br/>
</p>
</div>
</center>
<br/>
<br/>


The response is displayed below, and should look like that:
<span id="Register"></span>
:::'''1. Registration''' <br/>
Click on '''REGISTER''' to register or log in. <br/>
<br/>


[[Fichier:Taxo group response.png|none|900px|vignette|left|Printscreen from Postman - API query : result from GET taxo_groups]]
See subsection [[Introduction#Registration|Registration]] below to see how to Access the site. <br/>
<br/>


<span id="Languages"></span>
:::'''2. Languages''' <br/>
Select the language to see the web site by clicking on its icon. The selected language is highlighted in yellow. <br/>
<br/>


We will now assume OAuth1 is configured and that email and password are set. So we will not mention them anymore, for simplicity, you can reuse the first example as reference.
If you are a registered user, your choice will be automatically saved for your next visit. <br/>
<br/>


==== Places and communes ====
See wiki section Various > [[Available_languages|Available languages]] for more information on website language and for correspondence of language codes. <br/>
<br/>


Places can be located at any position and each observation is linked to the nearest place (it can also be directly on the place itself for the ones that are not using precise location). Places are inside communes. We will assume we are looking for all places in one commune. We will use api/places and api/local_admin_units. Communes are represented by the local_admin_units and the county (or any other name depending on country) are territorial_units.
:::'''3. Main menu''' <br/>
All functions available to you on this site will be displayed in the main menu. More functions are available to registered users. <br/>
<br/>


Using the example above, copy it inside a new tab and change a few things:
<span id="table"></span>
# change API query to '''api/local_admin_units'''
<center>
# add a GET param '''"name"''' next to the user_email and user_pw. Enter the "name" value you want
<div style="width:70%; border:0px;">
<table border="1" width="100%" class="wikitable sortable">


for this exemple we will be searching for a commune containing the name "Vevey"
<tr style="padding: 25px; text-align: center; font-family: sans serif; ">
<th>Functions</th>
<th>Unregistered user</th>
<th>Registered user</th>
</tr>


You can see the result here:
<tr style="padding: 25px; text-align: center; font-family: sans-serif; ">
<td>See sun and moon information at registered location</td>
<td style="color:red">NO</td>
<td style="color:green">YES</td>
</tr>


[[Fichier:Local units results.jpg|none|600px|vignette|left|Printscreen from Postman - API query : GET local_admin_units results]]
<tr style="padding: 25px; text-align: center; font-family: sans-serif; ">
<td>See latest records</td>
<td style="color:green">YES</td>
<td style="color:green">YES</td>
</tr>


<tr style="padding: 25px; text-align: center; font-family: sans-serif;">
<td>[[Customise website|Customise the website]]</td>
<td style="color:red">NO</td>
<td style="color:green">YES</td>
</tr>


As you can see there is a few communes having the same name. For our example I will use the last one which has id 966.
<tr style="padding: 25px; text-align: center; font-family: sans-serif; ">
<td>[[Browsing records|Access additional information for a record]]</td>
<td style="color:red">NO</td>
<td style="color:red">NO</td>
</tr>


Again copy query from the initial taxo_groups query to a new postman tab and change the following data:
<tr style="padding: 25px; text-align: center; font-family: sans-serif; ">
# The query should now be '''api/places'''
<td>[[Browsing records|See own observations on a map]]</td>
# Add a GET param, '''"id_commune"''' with the value that you have retrieved in last query (966)
<td style="color:red">NO</td>
<td style="color:green">YES</td>
</tr>


The query should look like this:
<tr style="padding: 25px; text-align: center; font-family: sans-serif; ">
<td>[[Browsing records|Access statistics for some species]]</td>
<td style="color:red">NO</td>
<td style="color:green">YES</td>
</tr>


[[Fichier:Get places.png|none|900px|vignette|left|Printscreen from Postman - API query : GET places query]]
<tr style="padding: 25px; text-align: center; font-family: sans-serif; ">
<td>[[Entering_records|Submit observations]]</td>
<td style="color:red">NO</td>
<td style="color:green">YES<sup>1</sup></td>
</tr>


<tr style="padding: 25px; text-align: center; font-family: sans-serif; ">
<td>[[Editing records| Edit own observations]]</td>
<td style="color:red">NO</td>
<td style="color:red">NO</td>
</tr>


So now we have all the places that are on the commune choosed.
<tr style="padding: 25px; text-align: center; font-family: sans-serif; ">
<td>See others' observations</td>
<td style="color:red">NO</td>
<td style="color:red">NO</td>
</tr>


==== Species ====
<tr style="padding: 25px; text-align: center; font-family: sans-serif; ">
<td>[[Exporting your data|Export your own records]]</td>
<td style="color:red">NO</td>
<td style="color:green">YES</td>
</tr>


Another quick example searching all the species that are from taxonomic group 1 (birds) that are used on the website and that have a rarity "unusual"
<tr style="padding: 25px; text-align: center; font-family: sans-serif; ">
<td>Export others' records</td>
<td style="color:red">NO</td>
<td style="color:red">NO</td>
</tr>


[[Fichier:Species unusual.png|none|900px|vignette|left|Printscreen from Postman - API query : GET species query]]
<tr style="padding: 25px; text-align: center; font-family: sans-serif;">
<td>See own profile</td>
<td style="color:red">NO</td>
<td style="color:green">YES</td>
</tr>


<tr style="padding: 25px; text-align: center; font-family: sans-serif;">
<td>[[Ephemeris|Calculate ephemerides]]</td>
<td style="color:red">NO</td>
<td style="color:green">YES</td>
</tr>


==== Observations ====
</table>
<p style="text-align:left; margin-left:5px;"><sup>1</sup>Submit observations through NaturaList application when no local portal exists. </p>
</div>
</center>
<br/>
<br/>


We can get observations using hostname/api/observations but it would generally get to much data for Postman to handle, so you need to search for a smaller dataset here is an example:
<span id="Observations"></span>
:::'''4. Real time observations''' <br/>
The dashboard shows real time observations both for registered and unregistered users. <br/>
<br/>


Search all observations between 2 dates for all species
<center>
<div class="toc" style="border-radius:5px;background-color:#ffffff;padding-left:8px;padding-right:8px; padding-bottom:8px;width:700px;">
[[File:Real time.png|700px|link=https://help.biolovision.net/images/f/f2/Real_time.png]]
<div class="toc" style="border-radius:5px;padding-left:15px;text-align:left; font-size:12px;width:675px;">
'''Real time observations.'''
</div>
<p style="color:black;font-size:12px;padding-left:5px;text-align:left;column-count:1;padding-right:5px;">
<b>5. [[Introduction#Ephemerides|Ephemerides]]: </b> Moon and sun information. See sub section below. <br />
<b>6. Map area: </b> Location of observations submitted to any of the Biolovision sites (including NturaList). Dots appear as observations are submitted (in yellow, the last submission).<br />
<b>7. Observations area: </b> Observations as they are submitted to any of the Biolovision sites (including NaturaList) -in yellow the latest submission. Information limited to number of observations, date, time and local portal where they are submitted.  <br/>
</p>
</div>
</center>
<br/>
<br/>


# Change method to '''POST''' (not GET)
<span id="Ephemerides"></span>
# Query '''api/observations/search'''
:::'''5. Ephemerides''' <br/>
# Inside the body tab you can provide a json wich contains all the search parameters like this '''{"period_choice":"range","date_from":"3.11.2015","date_to":"4.11.2015","species_choice":"all"}'''
General information about the date, time, sun and moon rise and sun and moon set. The data refers to the location you are registered at, or at a representative location determined by the system, if you are not registered. <br/>
<br/>


[[Fichier:Observations 4 nov 2015.png|none|900px|vignette|left|Printscreen from Postman - API query : GET observation during a period]]
Find further details at Main menu > Tools > [[Ephemeris|Calculating ephemerides]]. <br/>
<br/>


=Register=
<br/>


To get more details on the parameters you can use in the search you can use the Api documentation below. (or do a query on api/help/observations)
<center>
<div class="toc" style="border-radius: 5px; padding: 25px; text-align: left; font-family: sans-serif; color: black; width: 600px; background-color: hsl(157, 74%, 80%)">
 
<p>'''REMEMBER:'''<br /><br />
Your USERNAME = EMAIL ADDRESS<br /><br />
UNIQUE LOGIN!: <br />
Same credentials (User name + password) to log in in any of the [[Local portals and partners#Local portals|Local portals]],  [[Main_Page#Mobile_interface|Naturalist]] and [[Main_Page#data.biolovision.net|data.biolovision.net]]<br />
</p>
</div>
</center>
<br/>
<br/>
 
Registered users have more functions than unregistered ones. Go to [[Introduction#table|table above]] to see differences.<br/>
<br/>
 
Use your credentials from any Biolovision site (including NaturaList) also in data.biolovision.net. Or open a new account if you have never registered in any Biolovision site. <br/>
<br/>
 
See sub section: <br/>
* [[Introduction#Log in|Log in]] if you already have an account, or <br/>
* [[Introduction#Open an account|Open an account]] to open a new account. <br/>
<br/>
 
==Open an account==
<br/>
 
If you have never registered to any Biolovision site (including NaturaList), visit wiki section Main interface > Local portal > Getting started > [[Getting started#Registration|Registration]] to learn how to open an account. <br/>
<br/>
 
==Log in==
<br/>
 
If you have previously opened an account at a Biolovision site (including NaturaList), use the same credentials on data.biolovision.net. <br/>
<br/>
 
See wiki section Web interface > Local portal > Getting started > [[Getting started#Logging in|Logging in]] for more information if necessary. <br/>
<br/>
 
If you forgot your password, see wiki section Web interface > Local portal > Getting started> [[Getting started#Requesting a new password|Requesting a new password]] to obtain a new one. <br/>
<br/>
 
==Delete account==
<br/>
 
If you no longer want to participate, visit wiki section Web interface > Local portal > Getting started > [[Getting started#deleting your account|Deleting your account]] to know how to delete the account. <br/>
<br/>

Latest revision as of 10:29, 21 February 2025


All data submitted to a local portal or recorded through the App NaturaList and synchronised, is stored at https://data.biolovision.net.

It serves as worldwide unique portal and:
· Stores observations in areas not covered by any local portal
· Stores observations for all taxonomic groups independently of the taxonomic groups opened on each local portal

At the moment one cannot edit observations or see other's data. Sounds and images are stored although it is not currently possible to see them.

Registered users can:
· See own data
· Export own data
· Share own data
· Calculate ephemerides
· See some statistics
· See data submissions worldwide in real time

Main interface


Main interface.png

Main interface.

1. Registration
2. Languages
3. Main menu
4. Real time observations
5. Ephemerides



1. Registration

Click on REGISTER to register or log in.

See subsection Registration below to see how to Access the site.

2. Languages

Select the language to see the web site by clicking on its icon. The selected language is highlighted in yellow.

If you are a registered user, your choice will be automatically saved for your next visit.

See wiki section Various > Available languages for more information on website language and for correspondence of language codes.

3. Main menu

All functions available to you on this site will be displayed in the main menu. More functions are available to registered users.

Functions Unregistered user Registered user
See sun and moon information at registered location NO YES
See latest records YES YES
Customise the website NO YES
Access additional information for a record NO NO
See own observations on a map NO YES
Access statistics for some species NO YES
Submit observations NO YES1
Edit own observations NO NO
See others' observations NO NO
Export your own records NO YES
Export others' records NO NO
See own profile NO YES
Calculate ephemerides NO YES

1Submit observations through NaturaList application when no local portal exists.



4. Real time observations

The dashboard shows real time observations both for registered and unregistered users.

Real time.png

Real time observations.

5. Ephemerides: Moon and sun information. See sub section below.
6. Map area: Location of observations submitted to any of the Biolovision sites (including NturaList). Dots appear as observations are submitted (in yellow, the last submission).
7. Observations area: Observations as they are submitted to any of the Biolovision sites (including NaturaList) -in yellow the latest submission. Information limited to number of observations, date, time and local portal where they are submitted.



5. Ephemerides

General information about the date, time, sun and moon rise and sun and moon set. The data refers to the location you are registered at, or at a representative location determined by the system, if you are not registered.

Find further details at Main menu > Tools > Calculating ephemerides.

Register


REMEMBER:

Your USERNAME = EMAIL ADDRESS

UNIQUE LOGIN!:
Same credentials (User name + password) to log in in any of the Local portals, Naturalist and data.biolovision.net



Registered users have more functions than unregistered ones. Go to table above to see differences.

Use your credentials from any Biolovision site (including NaturaList) also in data.biolovision.net. Or open a new account if you have never registered in any Biolovision site.

See sub section:


Open an account


If you have never registered to any Biolovision site (including NaturaList), visit wiki section Main interface > Local portal > Getting started > Registration to learn how to open an account.

Log in


If you have previously opened an account at a Biolovision site (including NaturaList), use the same credentials on data.biolovision.net.

See wiki section Web interface > Local portal > Getting started > Logging in for more information if necessary.

If you forgot your password, see wiki section Web interface > Local portal > Getting started> Requesting a new password to obtain a new one.

Delete account


If you no longer want to participate, visit wiki section Web interface > Local portal > Getting started > Deleting your account to know how to delete the account.

Retrieved from "https://help.biolovision.net/index.php?title=Introduction&oldid=18466"