API/v1 - Historique des versions

Admin : /* API documentation */

2019-06-14T15:11:35Z

API documentation

Voir les modifications

Admin : /* Observations */

2018-08-28T12:13:30Z

Observations

Admin le 6 avril 2016 à 14:00

2016-04-06T14:00:05Z

Admin le 8 mars 2016 à 03:55

2016-03-08T03:55:19Z

Admin le 7 mars 2016 à 02:27

2016-03-07T02:27:19Z

Admin le 4 mars 2016 à 14:22

2016-03-04T14:22:18Z

Jennifer : ajout images et legendes

2015-11-04T12:59:14Z

ajout images et legendes

Jennifer : API doc image

2015-11-04T12:30:03Z

API doc image

Jennifer le 4 novembre 2015 à 12:13

2015-11-04T12:13:47Z

Jennifer le 26 octobre 2015 à 13:01

2015-10-26T13:01:44Z

← Version précédente		Version du 28 août 2018 à 12:13
Ligne 82 :		Ligne 82 :


−	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/observations~~/help~~)	+	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)

	== API documentation ==		== API documentation ==

@@ Ligne 905 : / Ligne 905 : @@
 :::::'''Usage''': <nowiki>GET /taxo_groups/5 retrieve taxo_groups of id 5.</nowiki>
 :::::'''Return''': <nowiki>A taxo group of id %id%.</nowiki>
 === Taxo groups by website ===

@@ Ligne 1 106 : / Ligne 1 106 : @@
 :::::'''Usage''': <nowiki>GET /validations/5 retrieve a validation of id 5.</nowiki>
 :::::'''Return''': <nowiki>A validation.</nowiki>
 ===Bearded Vulture Birds controller.===
 :::'''Title''': <nowiki>Bearded Vulture Birds controller.</nowiki>
@@ Ligne 1 160 : / Ligne 1 159 : @@
 :::::'''Title''': <nowiki>List Bearded Vulture informations</nowiki>
 :::::'''URL''': <nowiki>/gypaetus_barbatus_informations</nowiki>
-:::::'''Description''': <nowiki>Returns the list of all bearded vulture informations. Search on optional parameters can also be done.</nowiki>
+:::::'''Description''': <nowiki>Returns the list of all bearded vulture informations.</nowiki>
 :::::'''Method''': <nowiki>GET</nowiki>
 :::::'''URL Params  ''':
@@ Ligne 1 166 : / Ligne 1 165 : @@
 :::::::'''0''': <nowiki>user_pw</nowiki>
 :::::::'''1''': <nowiki>user_email</nowiki>
-::::::'''Optional''':
+::::::'''Optional''': <nowiki></nowiki>
 :::::'''Body Payload''': <nowiki></nowiki>
 :::::'''Possible Output Format''':
@@ Ligne 1 174 : / Ligne 1 171 : @@
 ::::::'''1''': <nowiki>xml</nowiki>
 :::::'''Usage''': <nowiki>GET /gypaetus_barbatus_informations</nowiki>
-:::::'''Return''': <nowiki>A list of possible bearded vulture informations, such as behaviour,interaction ...</nowiki>
+:::::'''Return''': <nowiki>A list of possible bearded vulture informations, such as behaviour,interaction... Each entry has their specific method, which lists the different values. For exemple : GET /gypaetus_barbatus_informations/behaviour</nowiki>

@@ Ligne 1 109 : / Ligne 1 109 : @@
 ===Bearded Vulture Birds controller.===
 :::'''Title''': <nowiki>Bearded Vulture Birds controller.</nowiki>
-:::'''URL''': <nowiki>/bearded_vulture_birds</nowiki>
+:::'''URL''': <nowiki>/gypaetus_barbatus_birds</nowiki>
 :::'''Description''': <nowiki>Bearded vulture birds controller. Each bearded vulture that was introduced has special marks to help identification of individuals. This controller enables to list all the bearded vultures birds.</nowiki>
 ====Public Functions====
 =====List all Bearded Vulture birds=====
 :::::'''Title''': <nowiki>List all Bearded Vulture birds</nowiki>
-:::::'''URL''': <nowiki>/bearded_vulture_birds</nowiki>
+:::::'''URL''': <nowiki>/gypaetus_barbatus_birds</nowiki>
 :::::'''Description''': <nowiki>Returns the list of all Bearded Vulture birds. Search on optional parameters can also be done.</nowiki>
 :::::'''Method''': <nowiki>GET</nowiki>
@@ Ligne 1 133 : / Ligne 1 133 : @@
 ::::::'''0''': <nowiki>json</nowiki>
 ::::::'''1''': <nowiki>xml</nowiki>
-:::::'''Usage''': <nowiki>GET /bearded_vulture_birds list all bearded vulture birds.</nowiki>
+:::::'''Usage''': <nowiki>GET /gypaetus_barbatus_birds list all bearded vulture birds.</nowiki>
 :::::'''Return''': <nowiki>A list of bearded vulture birds.</nowiki>
 =====Get a single bird=====
 :::::'''Title''': <nowiki>Get a single bird</nowiki>
-:::::'''URL''': <nowiki>/bearded_vulture_birds/%id%</nowiki>
+:::::'''URL''': <nowiki>/gypaetus_barbatus_birds/%id%</nowiki>
 :::::'''Description''': <nowiki>Get the bird with id %id%.</nowiki>
 :::::'''Method''': <nowiki>GET</nowiki>
@@ Ligne 1 150 : / Ligne 1 150 : @@
 ::::::'''0''': <nowiki>json</nowiki>
 ::::::'''1''': <nowiki>xml</nowiki>
-:::::'''Usage''': <nowiki>GET /bearded_vulture_birds/5 retrieve bearded vulture bird of id 5.</nowiki>
+:::::'''Usage''': <nowiki>GET /gypaetus_barbatus_birds/5 retrieve bearded vulture bird of id 5.</nowiki>
 :::::'''Return''': <nowiki>The bird with id %id%.</nowiki>
 ===Bearded Vulture informations controller.===
 :::'''Title''': <nowiki>Bearded Vulture informations controller.</nowiki>
-:::'''URL''': <nowiki>/bearded_vulture_informations</nowiki>
+:::'''URL''': <nowiki>/gypaetus_barbatus_informations</nowiki>
-:::'''Description''': <nowiki>bearded_vulture_informations controller.</nowiki>
+:::'''Description''': <nowiki>gypaetus_barbatus_informations controller.</nowiki>
 ====Public Functions====
 =====List Bearded Vulture informations=====
 :::::'''Title''': <nowiki>List Bearded Vulture informations</nowiki>
-:::::'''URL''': <nowiki>/bearded_vulture_informations</nowiki>
+:::::'''URL''': <nowiki>/gypaetus_barbatus_informations</nowiki>
 :::::'''Description''': <nowiki>Returns the list of all bearded vulture informations. Search on optional parameters can also be done.</nowiki>
 :::::'''Method''': <nowiki>GET</nowiki>
@@ Ligne 1 173 : / Ligne 1 173 : @@
 ::::::'''0''': <nowiki>json</nowiki>
 ::::::'''1''': <nowiki>xml</nowiki>
-:::::'''Usage''': <nowiki>GET /bearded_vulture_informations</nowiki>
+:::::'''Usage''': <nowiki>GET /gypaetus_barbatus_informations</nowiki>
 :::::'''Return''': <nowiki>A list of possible bearded vulture informations, such as behaviour,interaction ...</nowiki>
 =====Get a single Bearded Vulture information=====
 :::::'''Title''': <nowiki>Get a single Bearded Vulture information</nowiki>
-:::::'''URL''': <nowiki>/bearded_vulture_informations/%id%</nowiki>
+:::::'''URL''': <nowiki>/gypaetus_barbatus_informations/%id%</nowiki>
 :::::'''Description''': <nowiki>Get the Bearded Vulture information for id %id%.</nowiki>
 :::::'''Method''': <nowiki>GET</nowiki>
@@ Ligne 1 190 : / Ligne 1 190 : @@
 ::::::'''0''': <nowiki>json</nowiki>
 ::::::'''1''': <nowiki>xml</nowiki>
-:::::'''Usage''': <nowiki>GET /bearded_vulture_informations/5</nowiki>
+:::::'''Usage''': <nowiki>GET /gypaetus_barbatus_informations/5</nowiki>
 :::::'''Return''': <nowiki>A Bearded Vulture information for id %id%.</nowiki>

← Version précédente		Version du 4 mars 2016 à 14:22
Ligne 1 106 :		Ligne 1 106 :
	:::::'''Usage''': <nowiki>GET /validations/5 retrieve a validation of id 5.</nowiki>		:::::'''Usage''': <nowiki>GET /validations/5 retrieve a validation of id 5.</nowiki>
	:::::'''Return''': <nowiki>A validation.</nowiki>		:::::'''Return''': <nowiki>A validation.</nowiki>
		+
		+	===Bearded Vulture Birds controller.===
		+	:::'''Title''': <nowiki>Bearded Vulture Birds controller.</nowiki>
		+	:::'''URL''': <nowiki>/bearded_vulture_birds</nowiki>
		+	:::'''Description''': <nowiki>Bearded vulture birds controller. Each bearded vulture that was introduced has special marks to help identification of individuals. This controller enables to list all the bearded vultures birds.</nowiki>
		+	====Public Functions====
		+	=====List all Bearded Vulture birds=====
		+	:::::'''Title''': <nowiki>List all Bearded Vulture birds</nowiki>
		+	:::::'''URL''': <nowiki>/bearded_vulture_birds</nowiki>
		+	:::::'''Description''': <nowiki>Returns the list of all Bearded Vulture birds. Search on optional parameters can also be done.</nowiki>
		+	:::::'''Method''': <nowiki>GET</nowiki>
		+	:::::'''URL Params ''':
		+	::::::'''Required''':
		+	:::::::'''0''': <nowiki>user_pw</nowiki>
		+	:::::::'''1''': <nowiki>user_email</nowiki>
		+	::::::'''Optional''':
		+	:::::::'''0''': <nowiki>id</nowiki>
		+	:::::::'''1''': <nowiki>international_id</nowiki>
		+	:::::::'''2''': <nowiki>sex</nowiki>
		+	:::::::'''3''': <nowiki>birth_date</nowiki>
		+	:::::::'''4''': <nowiki>death_date</nowiki>
		+	:::::::'''5''': <nowiki>release_date</nowiki>
		+	:::::::'''6''': <nowiki>release_place</nowiki>
		+	:::::'''Body Payload''': <nowiki></nowiki>
		+	:::::'''Possible Output Format''':
		+	::::::'''0''': <nowiki>json</nowiki>
		+	::::::'''1''': <nowiki>xml</nowiki>
		+	:::::'''Usage''': <nowiki>GET /bearded_vulture_birds list all bearded vulture birds.</nowiki>
		+	:::::'''Return''': <nowiki>A list of bearded vulture birds.</nowiki>
		+	=====Get a single bird=====
		+	:::::'''Title''': <nowiki>Get a single bird</nowiki>
		+	:::::'''URL''': <nowiki>/bearded_vulture_birds/%id%</nowiki>
		+	:::::'''Description''': <nowiki>Get the bird with id %id%.</nowiki>
		+	:::::'''Method''': <nowiki>GET</nowiki>
		+	:::::'''URL Params ''':
		+	::::::'''Required''':
		+	:::::::'''0''': <nowiki>user_pw</nowiki>
		+	:::::::'''1''': <nowiki>user_email</nowiki>
		+	::::::'''Optional''':
		+
		+	:::::'''Body Payload''': <nowiki></nowiki>
		+	:::::'''Possible Output Format''':
		+	::::::'''0''': <nowiki>json</nowiki>
		+	::::::'''1''': <nowiki>xml</nowiki>
		+	:::::'''Usage''': <nowiki>GET /bearded_vulture_birds/5 retrieve bearded vulture bird of id 5.</nowiki>
		+	:::::'''Return''': <nowiki>The bird with id %id%.</nowiki>
		+	===Bearded Vulture informations controller.===
		+	:::'''Title''': <nowiki>Bearded Vulture informations controller.</nowiki>
		+	:::'''URL''': <nowiki>/bearded_vulture_informations</nowiki>
		+	:::'''Description''': <nowiki>bearded_vulture_informations controller.</nowiki>
		+	====Public Functions====
		+	=====List Bearded Vulture informations=====
		+	:::::'''Title''': <nowiki>List Bearded Vulture informations</nowiki>
		+	:::::'''URL''': <nowiki>/bearded_vulture_informations</nowiki>
		+	:::::'''Description''': <nowiki>Returns the list of all bearded vulture informations. Search on optional parameters can also be done.</nowiki>
		+	:::::'''Method''': <nowiki>GET</nowiki>
		+	:::::'''URL Params ''':
		+	::::::'''Required''':
		+	:::::::'''0''': <nowiki>user_pw</nowiki>
		+	:::::::'''1''': <nowiki>user_email</nowiki>
		+	::::::'''Optional''':
		+	:::::::'''0''': <nowiki>id</nowiki>
		+	:::::::'''1''': <nowiki>name</nowiki>
		+	:::::'''Body Payload''': <nowiki></nowiki>
		+	:::::'''Possible Output Format''':
		+	::::::'''0''': <nowiki>json</nowiki>
		+	::::::'''1''': <nowiki>xml</nowiki>
		+	:::::'''Usage''': <nowiki>GET /bearded_vulture_informations</nowiki>
		+	:::::'''Return''': <nowiki>A list of possible bearded vulture informations, such as behaviour,interaction ...</nowiki>
		+	=====Get a single Bearded Vulture information=====
		+	:::::'''Title''': <nowiki>Get a single Bearded Vulture information</nowiki>
		+	:::::'''URL''': <nowiki>/bearded_vulture_informations/%id%</nowiki>
		+	:::::'''Description''': <nowiki>Get the Bearded Vulture information for id %id%.</nowiki>
		+	:::::'''Method''': <nowiki>GET</nowiki>
		+	:::::'''URL Params ''':
		+	::::::'''Required''':
		+	:::::::'''0''': <nowiki>user_pw</nowiki>
		+	:::::::'''1''': <nowiki>user_email</nowiki>
		+	::::::'''Optional''':
		+
		+	:::::'''Body Payload''': <nowiki></nowiki>
		+	:::::'''Possible Output Format''':
		+	::::::'''0''': <nowiki>json</nowiki>
		+	::::::'''1''': <nowiki>xml</nowiki>
		+	:::::'''Usage''': <nowiki>GET /bearded_vulture_informations/5</nowiki>
		+	:::::'''Return''': <nowiki>A Bearded Vulture information for id %id%.</nowiki>

@@ Ligne 24 : / Ligne 24 : @@
 At the end it should look like this:
-[[Fichier:Taxo group.png|none|600px|vignette|left|Printscreen from Postman - API query : GET taxo_groups]]
+[[Fichier:Taxo group.png|none|900px|vignette|left|Printscreen from Postman - API query : GET taxo_groups]]
 The response is displayed below, and should look like that:
-IMAGE2
+[[Fichier:Taxo group response.png|none|900px|vignette|left|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.
@@ Ligne 34 : / Ligne 36 : @@
 ==== Places and communes ====
-Places are created at different interesting points 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 and then get more detail on one of this place. 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.
+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:
@@ Ligne 44 : / Ligne 46 : @@
 You can see the result here:
-IMAGE3
+[[Fichier:Local units results.jpg|none|600px|vignette|left|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.
@@ Ligne 52 : / Ligne 55 : @@
 # Add a GET param, '''"id_commune"''' with the value that you have retrieved in last query (966)
-IMAGE4
+The query should look like this:
 So now we have all the places that are on the commune choosed.
@@ Ligne 60 : / Ligne 66 : @@
 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"
-IMAGE5
+[[Fichier:Species unusual.png|none|900px|vignette|left|Printscreen from Postman - API query : GET species query]]
 ==== Observations ====
@@ Ligne 72 : / Ligne 79 : @@
 # 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"}'''
-IMAGE
+[[Fichier:Observations 4 nov 2015.png|none|900px|vignette|left|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/observations/help)

← Version précédente		Version du 4 novembre 2015 à 12:13
Ligne 1 :		Ligne 1 :
	== 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 [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 ===
		+
		+	==== 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:
		+	# Choose the method GET
		+	# Write the query ''' ''HOSTNAME''/api/taxo_groups?'''
		+	# Enter the GET params, that will be used for the query. In this case '''user_email''' and '''user_pw''' with the corresponding values.
		+	# In the Authorization tab choose '''OAuth 1.0'''
		+	# Enter the consumer key and consumer secret key
		+	# Enter the Token line which will be ''' ''HOSTNAME''/index.php?m_id=1200&cmd=request_token'''
		+	# Choose the method signature '''HMAC-SHA1'''
		+	# Tick "Add params to header"
		+	# Tick "Auto add parameters"
		+
		+	At the end it should look like this:
		+
		+	IMAGE1
		+
		+	The response is displayed below, and should look like that:
		+
		+	IMAGE2
		+
		+	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 communes ====
		+
		+	Places are created at different interesting points 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 and then get more detail on one of this place. 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:
		+	# change API query to '''api/local_admin_units'''
		+	# 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:
		+
		+	IMAGE3
		+
		+	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:
		+	# The query should now be '''api/places'''
		+	# Add a GET param, '''"id_commune"''' with the value that you have retrieved in last query (966)
		+
		+	IMAGE4
		+
		+	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"
		+
		+	IMAGE5
		+
		+	==== 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
		+
		+	# Change method to '''POST''' (not GET)
		+	# Query '''api/observations/search'''
		+	# 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"}'''
		+
		+	IMAGE
		+
		+	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/observations/help)

	== API documentation ==		== API documentation ==

← Version précédente		Version du 26 octobre 2015 à 13:01
Ligne 1 :		Ligne 1 :
		+	== Introduction ==
		+
	== API documentation ==		== API documentation ==
−
−	~~== Introduction ==~~

	=== Atlas documents ===		=== Atlas documents ===