Introduction

Introduction

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. 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. To provide examples we will work with a tool named 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

Taxonomics groups

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:

1. Choose the method GET
2. Write the query HOSTNAME/api/taxo_groups?
3. Enter the GET params, that will be used for the query. In this case user_email and user_pw with the corresponding values.
4. In the Authorization tab choose OAuth 1.0
5. Enter the consumer key and consumer secret key
6. Enter the Token line which will be HOSTNAME/index.php?m_id=1200&cmd=request_token
7. Choose the method signature HMAC-SHA1
8. Tick "Add params to header"
9. Tick "Auto add parameters"

At the end it should look like this:

Printscreen from Postman - API query: GET taxo_groups

The response is displayed below, and should look like that:

Printscreen from Postman - API query: result from GET taxo_groups

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.

Places and municipalities (local_admin_units)

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.

Using the example above, copy it inside a new tab and change a few things:

1. change API query to api/local_admin_units
2. add a GET param "name" next to the user_email and user_pw. Enter the "name" value you want

for this exemple we will be searching for a commune containing the name "Vevey"

You can see the result here:

Printscreen from Postman - API query: GET local_admin_units results

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.

Again copy query from the initial taxo_groups query to a new postman tab and change the following data:

1. The query should now be api/places
2. Add a GET param, "id_commune" with the value that you have retrieved in last query (966)

The query should look like this:

Printscreen from Postman - API query: GET places query

So now we have all the places that are on the commune choosed.

Species

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"

Printscreen from Postman - API query: GET species query

Observations

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:

Search all observations between 2 dates for all species

1. Change method to POST (not GET)
2. Query api/observations/search
3. 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"}

Printscreen from Postman - API query: GET observation during a period

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)