API/v1 : Différence entre versions

De Wiki Biolovision
Sauter à la navigation Sauter à la recherche
m (API doc image)
 
(6 révisions intermédiaires par 2 utilisateurs non affichées)
Ligne 24 : Ligne 24 :
 
At the end it should look like this:
 
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:
 
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.
 
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 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:
 
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:
 
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.
 
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)
 
# Add a GET param, '''"id_commune"''' with the value that you have retrieved in last query (966)
  
IMAGE4
+
The query should look like this:
 +
 
 +
[[Fichier:Get places.png|none|900px|vignette|left|Printscreen from Postman - API query : GET places query]]
 +
 
  
 
So now we have all the places that are on the commune choosed.
 
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"
 
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 ====
 
==== 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"}'''
 
# 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)  
+
 
 +
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 ==
  
=== Atlas documents ===
+
Please see on the portal. For exemple https://www.ornitho.ch/index.php?m_id=43 (You must be logged in)
 
 
:::'''Title''': <nowiki>Atlas documents</nowiki>
 
:::'''URL''': <nowiki>/atlas_documents</nowiki>
 
:::'''Description''': <nowiki>Atlas documents controller. Atlas documents are all documents associated to the atlas project, each document is associated with a grid, the document is visible to users that have the grid right.</nowiki>
 
 
 
==== Public Functions ====
 
 
 
===== List atlas documents =====
 
 
 
:::::'''Title''': <nowiki>List atlas documents</nowiki>
 
:::::'''URL''': <nowiki>/atlas_documents</nowiki>
 
:::::'''Description''': <nowiki>Returns the list of all atlas documents. 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>filename</nowiki>
 
:::::::'''2''': <nowiki>insert_date</nowiki>
 
:::::::'''3''': <nowiki>id_grid</nowiki>
 
:::::::'''4''': <nowiki>id_observer</nowiki>
 
:::::::'''5''': <nowiki>is_published</nowiki>
 
:::::::'''6''': <nowiki>grid_num</nowiki>
 
:::::'''Body Payload''': <nowiki />
 
:::::'''Possible Output Format''':
 
::::::'''0''': <nowiki>json</nowiki>
 
::::::'''1''': <nowiki>xml</nowiki>
 
:::::'''Usage''': <nowiki>GET /atlas_documents list all atlas documents. GET /atlas_documents with filename=test.txt, lists all atlas documents with a filename of test.txt. GET /atlas_documents with grid_num=5613, lists all atlas documents that are linked to the atlas grid 5913.</nowiki>
 
:::::'''Return''': <nowiki>A list of atlas documents.</nowiki>
 
 
 
===== Get a single atlas document =====
 
 
 
:::::'''Title''': <nowiki>Get a single atlas document</nowiki>
 
:::::'''URL''': <nowiki>/atlas_documents/%id%</nowiki>
 
:::::'''Description''': <nowiki>Get an atlas document of id %id%.</nowiki>
 
:::::'''Method''': <nowiki>GET</nowiki>
 
:::::'''URL Params ''':
 
::::::'''Required''':
 
:::::::'''0''': <nowiki>user_pw</nowiki>
 
:::::::'''1''': <nowiki>user_email</nowiki>
 
::::::'''Optional''':
 
 
 
:::::'''Body Payload''': <nowiki />
 
:::::'''Possible Output Format''':
 
::::::'''0''': <nowiki>json</nowiki>
 
::::::'''1''': <nowiki>xml</nowiki>
 
:::::'''Usage''': <nowiki>GET /atlas_documents/5 retrieve atlas document of id 5.</nowiki>
 
:::::'''Return''': <nowiki>An atlas document of id %id%.</nowiki>
 
 
 
=== Entities ===
 
 
 
:::'''Title''': <nowiki>Entities</nowiki>
 
:::'''URL''': <nowiki>/entities</nowiki>
 
:::'''Description''': <nowiki>Entities controller. An observer(user) can be linked to an entity. Observations can be posted as an entity rather than as an individual observer.</nowiki>
 
 
 
==== Public Functions ====
 
 
 
===== List Entities =====
 
 
 
:::::'''Title''': <nowiki>List Entities</nowiki>
 
:::::'''URL''': <nowiki>/entities</nowiki>
 
:::::'''Description''': <nowiki>Returns the list of all entities. 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>short_name</nowiki>
 
:::::::'''1''': <nowiki>full_name_french</nowiki>
 
:::::::'''2''': <nowiki>address</nowiki>
 
:::::::'''3''': <nowiki>url</nowiki>
 
:::::::'''4''': <nowiki>description_french</nowiki>
 
:::::'''Body Payload''': <nowiki />
 
:::::'''Possible Output Format''':
 
::::::'''0''': <nowiki>json</nowiki>
 
::::::'''1''': <nowiki>xml</nowiki>
 
:::::'''Usage''': <nowiki>GET /entities list all entities.</nowiki>
 
:::::'''Return''': <nowiki>A list of entities.</nowiki>
 
 
 
===== Get a single entity =====
 
 
 
:::::'''Title''': <nowiki>Get a single entity</nowiki>
 
:::::'''URL''': <nowiki>/entities/%id%</nowiki>
 
:::::'''Description''': <nowiki>Get an entity of id %id%.</nowiki>
 
:::::'''Method''': <nowiki>GET</nowiki>
 
:::::'''URL Params ''':
 
::::::'''Required''':
 
:::::::'''0''': <nowiki>user_pw</nowiki>
 
:::::::'''1''': <nowiki>user_email</nowiki>
 
::::::'''Optional''':
 
 
 
:::::'''Body Payload''': <nowiki />
 
:::::'''Possible Output Format''':
 
::::::'''0''': <nowiki>json</nowiki>
 
::::::'''1''': <nowiki>xml</nowiki>
 
:::::'''Usage''': <nowiki>GET /entities/5 retrieve entity of id 5.</nowiki>
 
:::::'''Return''': <nowiki>An entity of id %id%.</nowiki>
 
 
 
=== Export organizations controller. ===
 
 
 
:::'''Title''': <nowiki>Export organizations controller.</nowiki>
 
:::'''URL''': <nowiki>/export_organizations</nowiki>
 
:::'''Description''': <nowiki>Export Organizations controller. Observers(users) can authorize different export organizations to export their data.</nowiki>
 
 
 
==== Public Functions ====
 
 
 
===== List export organizations =====
 
 
 
:::::'''Title''': <nowiki>List export organizations</nowiki>
 
:::::'''URL''': <nowiki>/export_organizations</nowiki>
 
:::::'''Description''': <nowiki>Returns the list of all export organizations. 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>full_name</nowiki>
 
:::::::'''1''': <nowiki>text_french</nowiki>
 
:::::::'''2''': <nowiki>available</nowiki>
 
:::::'''Body Payload''': <nowiki />
 
:::::'''Possible Output Format''':
 
::::::'''0''': <nowiki>json</nowiki>
 
::::::'''1''': <nowiki>xml</nowiki>
 
:::::'''Usage''': <nowiki>GET /export_organizations lists all export organizations.</nowiki>
 
:::::'''Return''': <nowiki>A list of export organizations.</nowiki>
 
 
 
===== Get a single export organization =====
 
 
 
:::::'''Title''': <nowiki>Get a single export organization</nowiki>
 
:::::'''URL''': <nowiki>/export_organizations/%id%</nowiki>
 
:::::'''Description''': <nowiki>Get an export organization of id %id%.</nowiki>
 
:::::'''Method''': <nowiki>GET</nowiki>
 
:::::'''URL Params ''':
 
::::::'''Required''':
 
:::::::'''0''': <nowiki>user_pw</nowiki>
 
:::::::'''1''': <nowiki>user_email</nowiki>
 
::::::'''Optional''':
 
 
 
:::::'''Body Payload''': <nowiki />
 
:::::'''Possible Output Format''':
 
::::::'''0''': <nowiki>json</nowiki>
 
::::::'''1''': <nowiki>xml</nowiki>
 
:::::'''Usage''': <nowiki>GET /entity/5 retrieve an export organization of id 5.</nowiki>
 
:::::'''Return''': <nowiki>An export organization of id %id%.</nowiki>
 
 
 
=== Families controller. ===
 
 
 
:::'''Title''': <nowiki>Families controller.</nowiki>
 
:::'''URL''': <nowiki>/families</nowiki>
 
:::'''Description''': <nowiki>Families controller. Each species is part of both a taxonomic group (see taxo_groups controller) and a family. Example of families: Cuculidae, Equidae ...</nowiki>
 
 
 
==== Public Functions ====
 
 
 
===== List Families =====
 
 
 
:::::'''Title''': <nowiki>List Families</nowiki>
 
:::::'''URL''': <nowiki>/families</nowiki>
 
:::::'''Description''': <nowiki>Returns the list of all species families. 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_taxo_group</nowiki>
 
:::::::'''1''': <nowiki>latin_name</nowiki>
 
:::::'''Body Payload''': <nowiki />
 
:::::'''Possible Output Format''':
 
::::::'''0''': <nowiki>json</nowiki>
 
::::::'''1''': <nowiki>xml</nowiki>
 
:::::'''Usage''': <nowiki>GET /families list all families.</nowiki>
 
:::::'''Return''': <nowiki>A list of families.</nowiki>
 
 
 
===== Get a single family =====
 
 
 
:::::'''Title''': <nowiki>Get a single family</nowiki>
 
:::::'''URL''': <nowiki>/families/%id%</nowiki>
 
:::::'''Description''': <nowiki>Get a family of id %id%.</nowiki>
 
:::::'''Method''': <nowiki>GET</nowiki>
 
:::::'''URL Params ''':
 
::::::'''Required''':
 
:::::::'''0''': <nowiki>user_pw</nowiki>
 
:::::::'''1''': <nowiki>user_email</nowiki>
 
::::::'''Optional''':
 
 
 
:::::'''Body Payload''': <nowiki />
 
:::::'''Possible Output Format''':
 
::::::'''0''': <nowiki>json</nowiki>
 
::::::'''1''': <nowiki>xml</nowiki>
 
:::::'''Usage''': <nowiki>GET /families/5 retrieve a family of id 5.</nowiki>
 
:::::'''Return''': <nowiki>A family of id %id%.</nowiki>
 
 
 
::::
 
 
 
=== Grids controller ===
 
 
 
:::'''Title''': <nowiki>Grids controller</nowiki>
 
:::'''URL''': <nowiki>/grids</nowiki>
 
:::'''Description''': <nowiki>Grids controller.</nowiki>
 
 
 
==== Public Functions ====
 
 
 
===== List Grids =====
 
 
 
:::::'''Title''': <nowiki>List Grids</nowiki>
 
:::::'''URL''': <nowiki>/grids</nowiki>
 
:::::'''Description''': <nowiki>Returns the list of all grids with limits. 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>name</nowiki>
 
:::::::'''1''': <nowiki>y_min</nowiki>
 
:::::::'''2''': <nowiki>y_max</nowiki>
 
:::::::'''3''': <nowiki>x_min</nowiki>
 
:::::::'''4''': <nowiki>x_max</nowiki>
 
:::::'''Body Payload''': <nowiki />
 
:::::'''Possible Output Format''':
 
::::::'''0''': <nowiki>json</nowiki>
 
::::::'''1''': <nowiki>xml</nowiki>
 
:::::'''Usage''': <nowiki>GET /grids list all grids.</nowiki>
 
:::::'''Return''': <nowiki>A the list of grids.</nowiki>
 
 
 
===== Get a single grid =====
 
 
 
:::::'''Title''': <nowiki>Get a single grid</nowiki>
 
:::::'''URL''': <nowiki>/grids/%id%</nowiki>
 
:::::'''Description''': <nowiki>Get a grid of id %id%.</nowiki>
 
:::::'''Method''': <nowiki>GET</nowiki>
 
:::::'''URL Params ''':
 
::::::'''Required''':
 
:::::::'''0''': <nowiki>user_pw</nowiki>
 
:::::::'''1''': <nowiki>user_email</nowiki>
 
::::::'''Optional''':
 
 
 
:::::'''Body Payload''': <nowiki />
 
:::::'''Possible Output Format''':
 
::::::'''0''': <nowiki>json</nowiki>
 
::::::'''1''': <nowiki>xml</nowiki>
 
:::::'''Usage''': <nowiki>GET /grids/5 retrieve grid of id 5.</nowiki>
 
:::::'''Return''': <nowiki>A grid of id %id%.</nowiki>
 
 
 
=== Local admin units controller. ===
 
 
 
:::'''Title''': <nowiki>Local admin units controller.</nowiki>
 
:::'''URL''': <nowiki>/local_admin_units</nowiki>
 
:::'''Description''': <nowiki>Local admin units controller. Example of a local administrative unit: a commune.</nowiki>
 
 
 
==== Public Functions ====
 
 
 
===== List local admin units =====
 
 
 
:::::'''Title''': <nowiki>List local admin units</nowiki>
 
:::::'''URL''': <nowiki>/local_admin_units</nowiki>
 
:::::'''Description''': <nowiki>Returns the list of all local admin units. 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>name</nowiki>
 
:::::::'''1''': <nowiki>insee</nowiki>
 
:::::::'''2''': <nowiki>id_canton</nowiki>
 
:::::'''Body Payload''': <nowiki />
 
:::::'''Possible Output Format''':
 
::::::'''0''': <nowiki>json</nowiki>
 
::::::'''1''': <nowiki>xml</nowiki>
 
:::::'''Usage''': <nowiki>GET /local_admin_units list all local admin units. </nowiki>
 
:::::'''Return''': <nowiki>A list of local admin units.</nowiki>
 
 
 
===== Search local admin units =====
 
 
 
:::::'''Title''': <nowiki>Search local admin units</nowiki>
 
:::::'''URL''': <nowiki>/local_admin_units/search</nowiki>
 
:::::'''Description''': <nowiki>Returns the list of all communes ordered by smaller size of text first.</nowiki>
 
:::::'''Method''': <nowiki>GET</nowiki>
 
:::::'''URL Params ''':
 
::::::'''Required''':
 
:::::::'''0''': <nowiki>user_pw</nowiki>
 
:::::::'''1''': <nowiki>user_email</nowiki>
 
:::::::'''2''': <nowiki>name</nowiki>
 
::::::'''Optional''':
 
 
 
:::::'''Body Payload''': <nowiki />
 
:::::'''Possible Output Format''':
 
::::::'''0''': <nowiki>json</nowiki>
 
:::::'''Usage''': <nowiki>GET /local_admin_units/search with url param of name=[?] list all local admin unit named [?]. If we search for "abc", "abc" will be first result before "abcd" because "abc" is shorter.</nowiki>
 
:::::'''Return''': <nowiki>A list of local admin units.</nowiki>
 
 
 
===== Get a single local admin unit =====
 
 
 
:::::'''Title''': <nowiki>Get a single local admin unit</nowiki>
 
:::::'''URL''': <nowiki>/local_admin_units/%id%</nowiki>
 
:::::'''Description''': <nowiki>Get one local admin unit of id %id%.</nowiki>
 
:::::'''Method''': <nowiki>GET</nowiki>
 
:::::'''URL Params ''':
 
::::::'''Required''':
 
:::::::'''0''': <nowiki>user_pw</nowiki>
 
:::::::'''1''': <nowiki>user_email</nowiki>
 
::::::'''Optional''':
 
 
 
:::::'''Body Payload''': <nowiki />
 
:::::'''Possible Output Format''':
 
::::::'''0''': <nowiki>json</nowiki>
 
::::::'''1''': <nowiki>xml</nowiki>
 
:::::'''Usage''': <nowiki>GET /local_admin_units/5 retrieve local admin unit of id 5.</nowiki>
 
:::::'''Return''': <nowiki>A local admin unit of id %id%.</nowiki>
 
 
 
=== Media Controller ===
 
 
 
:::'''Title''': <nowiki>Media Controller</nowiki>
 
:::'''URL''': <nowiki>/media</nowiki>
 
:::'''Description''': <nowiki>Media controller. A media can be photos or sounds.</nowiki>
 
 
 
==== Public Functions<br> ====
 
 
 
::::
 
 
 
=== Observations Controller ===
 
 
 
:::'''Title''': <nowiki>Observations Controller</nowiki>
 
:::'''URL''': <nowiki>/observations</nowiki>
 
:::'''Description''': <nowiki>Observations controller.</nowiki>
 
 
 
==== Public Functions ====
 
 
 
===== List Observations =====
 
 
 
:::::'''Title''': <nowiki>List Observations</nowiki>
 
:::::'''URL''': <nowiki>/observations</nowiki>
 
:::::'''Description''': <nowiki>Returns the list of all observations. 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>id_taxo_group</nowiki>
 
:::::::'''2''': <nowiki>id_species</nowiki>
 
:::::::'''3''': <nowiki>id_place</nowiki>
 
:::::::'''4''': <nowiki>id_observer</nowiki>
 
:::::::'''5''': <nowiki>id_transmitter</nowiki>
 
:::::::'''6''': <nowiki>id_form</nowiki>
 
:::::::'''7''': <nowiki>id_grid</nowiki>
 
:::::::'''8''': <nowiki>lat</nowiki>
 
:::::::'''9''': <nowiki>lon</nowiki>
 
:::::::'''10''': <nowiki>precision</nowiki>
 
:::::::'''11''': <nowiki>date</nowiki>
 
:::::::'''12''': <nowiki>date_reverse</nowiki>
 
:::::::'''13''': <nowiki>year</nowiki>
 
:::::::'''14''': <nowiki>day_number</nowiki>
 
:::::::'''15''': <nowiki>estimation_code</nowiki>
 
:::::::'''16''': <nowiki>total_number</nowiki>
 
:::::::'''17''': <nowiki>flight_number</nowiki>
 
:::::::'''18''': <nowiki>atlas_code</nowiki>
 
:::::'''Body Payload''': <nowiki />
 
:::::'''Possible Output Format''':
 
::::::'''0''': <nowiki>json</nowiki>
 
::::::'''1''': <nowiki>xml</nowiki>
 
:::::'''Usage''': <nowiki>GET /observations list all observations. GET /observations with id_species=%id_species% search for all observations with id_species=%id_species%. See optional parameters for more search options.</nowiki>
 
:::::'''Return''': <nowiki>json with the list of observations.</nowiki>
 
 
 
===== Get a single observation =====
 
 
 
:::::'''Title''': <nowiki>Get a single observation</nowiki>
 
:::::'''URL''': <nowiki>/observations/%id%</nowiki>
 
:::::'''Description''': <nowiki>Get an observation of id %id%.</nowiki>
 
:::::'''Method''': <nowiki>GET</nowiki>
 
:::::'''URL Params ''':
 
::::::'''Required''':
 
:::::::'''0''': <nowiki>user_pw</nowiki>
 
:::::::'''1''': <nowiki>user_email</nowiki>
 
::::::'''Optional''':
 
 
 
:::::'''Body Payload''': <nowiki />
 
:::::'''Possible Output Format''':
 
::::::'''0''': <nowiki>json</nowiki>
 
::::::'''1''': <nowiki>xml</nowiki>
 
:::::'''Usage''': <nowiki>GET /observations/5 retrieve observation of id 5.</nowiki>
 
:::::'''Return''': <nowiki>An observation of id %id%.</nowiki>
 
 
 
===== Create an observation =====
 
 
 
:::::'''Title''': <nowiki>Create an observation</nowiki>
 
:::::'''URL''': <nowiki>/observations</nowiki>
 
:::::'''Description''': <nowiki>Create a new observation.</nowiki>
 
:::::'''Method''': <nowiki>POST</nowiki>
 
:::::'''URL Params ''':
 
::::::'''Required''':
 
:::::::'''0''': <nowiki>user_pw</nowiki>
 
:::::::'''1''': <nowiki>user_email</nowiki>
 
::::::'''Optional''':
 
 
 
:::::'''Body Payload''': <nowiki>{%json of observation%}</nowiki>
 
:::::'''Possible Output Format''':
 
 
 
:::::'''Usage''': <nowiki>POST /observations create a new observation using body payload. Example of body payload: {
 
                    "data": {
 
                        "sightings": [
 
                            {
 
                                "date": {
 
                                    "@timestamp": "1358204400"
 
                                },
 
                                "species": {
 
                                    "@id": "86"
 
                                },
 
                                "observers": [
 
                                    {
 
                                        "@id": "%replace by id_observer%",
 
                                        "coord_lat": "46.657314336776",
 
                                        "coord_lon": "6.8703200880124",
 
                                        "precision": "precise",
 
                                        "estimation_code": "EXACT_VALUE",
 
                                        "count": "6",
 
                                        "altitude": "800"
 
                                    }
 
                                ]
 
                            }
 
                        ]
 
                    }
 
                }</nowiki>
 
:::::'''Return''': <nowiki>success message in header, check http status code. 201 successful</nowiki>
 
 
 
===== Update an observations =====
 
 
 
:::::'''Title''': <nowiki>Update an observations</nowiki>
 
:::::'''URL''': <nowiki>/observations/%id%</nowiki>
 
:::::'''Description''': <nowiki>Update an observation.</nowiki>
 
:::::'''Method''': <nowiki>PUT</nowiki>
 
:::::'''URL Params ''':
 
::::::'''Required''':
 
:::::::'''0''': <nowiki>user_pw</nowiki>
 
:::::::'''1''': <nowiki>user_email</nowiki>
 
::::::'''Optional''':
 
 
 
:::::'''Body Payload''': <nowiki>{%json of observation%}</nowiki>
 
:::::'''Possible Output Format''':
 
 
 
:::::'''Usage''': <nowiki>PUT /observations/%id% update an observation using body payload. Check "create an observation" for body payload.</nowiki>
 
:::::'''Return''': <nowiki>success message in header, check http status code.</nowiki>
 
 
 
===== Delete an observations =====
 
 
 
:::::'''Title''': <nowiki>Delete an observations</nowiki>
 
:::::'''URL''': <nowiki>/observations/%id%</nowiki>
 
:::::'''Description''': <nowiki>Delete an observation of id %id%. Only observations of the current user can be deleted.</nowiki>
 
:::::'''Method''': <nowiki>DELETE</nowiki>
 
:::::'''URL Params ''':
 
::::::'''Required''':
 
:::::::'''0''': <nowiki>user_pw</nowiki>
 
:::::::'''1''': <nowiki>user_email</nowiki>
 
::::::'''Optional''':
 
 
 
:::::'''Body Payload''': <nowiki />
 
:::::'''Possible Output Format''':
 
 
 
:::::'''Usage''': <nowiki>DELETE /observations/%id% delete an observation.</nowiki>
 
:::::'''Return''': <nowiki>success message in header, check http status code. 200 successful</nowiki>
 
 
 
===== Search an observation =====
 
 
 
:::::'''Title''': <nowiki>Search an observation</nowiki>
 
:::::'''URL''': <nowiki>/observations/search</nowiki>
 
:::::'''Description''': <nowiki>Search for an observation, same parameters than in online version can be used, parameters need to be provided in body payload.</nowiki>
 
:::::'''Method''': <nowiki>POST</nowiki>
 
:::::'''URL Params ''':
 
::::::'''Required''':
 
:::::::'''0''': <nowiki>user_pw</nowiki>
 
:::::::'''1''': <nowiki>user_email</nowiki>
 
::::::'''Optional''':
 
 
 
:::::'''Body Payload''': <nowiki>{%search parameters in json format: period_choice=%period_choice=enum(range, season, offset, all)%,  date_from, date_to, season_from, season_to ,offset, entry_date, species_choice=%species_choice=enum(all, family, species, category)%  specie, family, rarity, location_choice, territorial_unit=%territorial_unit=enum(all, territorial_unit, local_admin_unit, place, coord, grid)%, place, local_admin_unit, territorial_unit_ids, grid_id, coordinates, coordinates_list, altitude_min, altitude_max, atlas_code, comment, observer_id, observers_id_list, only_my_data, only_export, only_entity, only_exported, only_not_exported, only_need_validation, only_form, form, only_with_picture, only_with_sound, only_new, only_death, only_echouage, only_stoc, project, only_with_ring, only_age_sex, chiro_acoustic, chiro_bio, chiro_telemetric, chiro_view, chiro_trace, only_colony, only_colony_extended, rarity_committee %}</nowiki>
 
:::::'''Possible Output Format''':
 
::::::'''0''': <nowiki>json</nowiki>
 
:::::'''Usage''': <nowiki>POST /observations/search search an observation using body payload. Example of body payload: {"period_choice":"range","date_from":"1.1.2013","date_to":"15.1.2013","species_choice":"all"}</nowiki>
 
:::::'''Return''': <nowiki>list of observations.</nowiki>
 
 
 
===== Search closest observations =====
 
 
 
:::::'''Title''': <nowiki>Search closest observations</nowiki>
 
:::::'''URL''': <nowiki>/observations/around_me</nowiki>
 
:::::'''Description''': <nowiki>Search for last observations that are near the coordinate given (4 km area, 5 last days). If no coordinate is given default position from observer will be used.</nowiki>
 
:::::'''Method''': <nowiki>GET</nowiki>
 
:::::'''URL Params ''':
 
::::::'''Required''':
 
:::::::'''0''': <nowiki>user_pw</nowiki>
 
:::::::'''1''': <nowiki>user_email</nowiki>
 
::::::'''Optional''':
 
:::::::'''0''': <nowiki>lat</nowiki>
 
:::::::'''1''': <nowiki>lon</nowiki>
 
:::::'''Body Payload''': <nowiki />
 
:::::'''Possible Output Format''':
 
::::::'''0''': <nowiki>json</nowiki>
 
:::::'''Usage''': <nowiki>POST /observations/around_me with lat=%lat% and lon=%lon% search last 5 days observations in a close area of 50 km from %lat%, %lon%.</nowiki>
 
:::::'''Return''': <nowiki>list of observations.</nowiki>
 
 
 
===== Search last observations =====
 
 
 
:::::'''Title''': <nowiki>Search last observations</nowiki>
 
:::::'''URL''': <nowiki>/observations/last</nowiki>
 
:::::'''Description''': <nowiki>Search for last observations (50 km, 5 days). If no coordinate is given default position from observer will be used.</nowiki>
 
:::::'''Method''': <nowiki>GET</nowiki>
 
:::::'''URL Params ''':
 
::::::'''Required''':
 
:::::::'''0''': <nowiki>user_pw</nowiki>
 
:::::::'''1''': <nowiki>user_email</nowiki>
 
::::::'''Optional''':
 
:::::::'''0''': <nowiki>lat</nowiki>
 
:::::::'''1''': <nowiki>lon</nowiki>
 
:::::'''Body Payload''': <nowiki />
 
:::::'''Possible Output Format''':
 
::::::'''0''': <nowiki>json</nowiki>
 
:::::'''Usage''': <nowiki>POST /observations/last with lat=%lat% and lon=%lon% search last 5 days observations in area of 50 km from %lat%, %lon%.</nowiki>
 
:::::'''Return''': <nowiki>list of observations.</nowiki>
 
 
 
===== Search rare observations =====
 
 
 
:::::'''Title''': <nowiki>Search rare observations</nowiki>
 
:::::'''URL''': <nowiki>/observations/rare</nowiki>
 
:::::'''Description''': <nowiki>Search for last rare observations (100 km, 7 days). If no coordinate is given default position from observer will be used.</nowiki>
 
:::::'''Method''': <nowiki>GET</nowiki>
 
:::::'''URL Params ''':
 
::::::'''Required''':
 
:::::::'''0''': <nowiki>user_pw</nowiki>
 
:::::::'''1''': <nowiki>user_email</nowiki>
 
::::::'''Optional''':
 
:::::::'''0''': <nowiki>lat</nowiki>
 
:::::::'''1''': <nowiki>lon</nowiki>
 
:::::'''Body Payload''': <nowiki />
 
:::::'''Possible Output Format''':
 
::::::'''0''': <nowiki>json</nowiki>
 
:::::'''Usage''': <nowiki>POST /observations/rare with lat=%lat% and lon=%lon% search last 7 days observations in area of 100 km from %lat%, %lon%.</nowiki>
 
:::::'''Return''': <nowiki>list of observations.</nowiki>
 
 
 
===== Search my observations =====
 
 
 
:::::'''Title''': <nowiki>Search my observations</nowiki>
 
:::::'''URL''': <nowiki>/observations/my</nowiki>
 
:::::'''Description''': <nowiki>Search for all observations of observer (user_email used).</nowiki>
 
:::::'''Method''': <nowiki>GET</nowiki>
 
:::::'''URL Params ''':
 
::::::'''Required''':
 
:::::::'''0''': <nowiki>user_pw</nowiki>
 
:::::::'''1''': <nowiki>user_email</nowiki>
 
::::::'''Optional''':
 
 
 
:::::'''Body Payload''': <nowiki />
 
:::::'''Possible Output Format''':
 
::::::'''0''': <nowiki>json</nowiki>
 
:::::'''Usage''': <nowiki>POST /observations/my search all observations from current observer (user_email).</nowiki>
 
:::::'''Return''': <nowiki>list of observations.</nowiki>
 
 
 
===== Search observations from a list of observers =====
 
 
 
:::::'''Title''': <nowiki>Search observations from a list of observers</nowiki>
 
:::::'''URL''': <nowiki>/observations/observers_list</nowiki>
 
:::::'''Description''': <nowiki>Search for all observations that have been done by a given list of observers.</nowiki>
 
:::::'''Method''': <nowiki>GET</nowiki>
 
:::::'''URL Params ''':
 
::::::'''Required''':
 
:::::::'''0''': <nowiki>user_pw</nowiki>
 
:::::::'''1''': <nowiki>user_email</nowiki>
 
:::::::'''2''': <nowiki>date_from</nowiki>
 
:::::::'''3''': <nowiki>date_to</nowiki>
 
:::::::'''4''': <nowiki>observers_id_list</nowiki>
 
::::::'''Optional''':
 
 
 
:::::'''Body Payload''': <nowiki />
 
:::::'''Possible Output Format''':
 
::::::'''0''': <nowiki>json</nowiki>
 
:::::'''Usage''': <nowiki>POST /observations/observers_list with date_from=01.01.2014, date_to=01.02.2014, observers_id_list=1,2,3 search all observations from observers with id 1,2,3.</nowiki>
 
:::::'''Return''': <nowiki>list of observations.</nowiki>
 
 
 
===== Search observations from a list of coordinates =====
 
 
 
:::::'''Title''': <nowiki>Search observations from a list of coordinates</nowiki>
 
:::::'''URL''': <nowiki>/observations/coordinates_list</nowiki>
 
:::::'''Description''': <nowiki>Search for all observations of given coordinates list.</nowiki>
 
:::::'''Method''': <nowiki>GET</nowiki>
 
:::::'''URL Params ''':
 
::::::'''Required''':
 
:::::::'''0''': <nowiki>user_pw</nowiki>
 
:::::::'''1''': <nowiki>user_email</nowiki>
 
:::::::'''2''': <nowiki>date_from</nowiki>
 
:::::::'''3''': <nowiki>date_to</nowiki>
 
:::::::'''4''': <nowiki>coordinates_list</nowiki>
 
::::::'''Optional''':
 
 
 
:::::'''Body Payload''': <nowiki />
 
:::::'''Possible Output Format''':
 
::::::'''0''': <nowiki>json</nowiki>
 
:::::'''Usage''': <nowiki>GET /observations/coordinates_list with coordinates_list=%lat_1%:%lon_1%,%lat_2%:%lon_2%</nowiki>
 
:::::'''Return''': <nowiki>list of observations.</nowiki>
 
 
 
===== Search resources linked to an observation =====
 
 
 
:::::'''Title''': <nowiki>Search resources linked to an observation</nowiki>
 
:::::'''URL''': <nowiki>/observations/%observation_id%/%resource%</nowiki>
 
:::::'''Description''': <nowiki>Search for all resources linked to the %observation_id% observation. Possible resources are : photos</nowiki>
 
:::::'''Method''': <nowiki>GET</nowiki>
 
:::::'''URL Params ''':
 
::::::'''Required''':
 
:::::::'''0''': <nowiki>user_pw</nowiki>
 
:::::::'''1''': <nowiki>user_email</nowiki>
 
::::::'''Optional''':
 
 
 
:::::'''Body Payload''': <nowiki />
 
:::::'''Possible Output Format''':
 
::::::'''0''': <nowiki>json</nowiki>
 
:::::'''Usage''': <nowiki>GET /observations/1/photos search all photos linked to observation with id 1.</nowiki>
 
:::::'''Return''': <nowiki>list of resources.</nowiki>
 
 
 
===== Create a new resources for an observation =====
 
 
 
:::::'''Title''': <nowiki>Create a new resources for an observation</nowiki>
 
:::::'''URL''': <nowiki>/observations/%observation_id%/%resource%</nowiki>
 
:::::'''Description''': <nowiki>Creates a new resource and link it to an observation with %observation_id%, %resource% is the type of resource. Possible resources are : photos.</nowiki>
 
:::::'''Method''': <nowiki>POST</nowiki>
 
:::::'''URL Params ''':
 
::::::'''Required''':
 
:::::::'''0''': <nowiki>user_pw</nowiki>
 
:::::::'''1''': <nowiki>user_email</nowiki>
 
::::::'''Optional''':
 
 
 
:::::'''Body Payload''': <nowiki />
 
:::::'''Possible Output Format''':
 
::::::'''0''': <nowiki>json</nowiki>
 
:::::'''Usage''': <nowiki>POST /observations/1/photos create a new resource using file input as content.</nowiki>
 
:::::'''Return''': <nowiki>New resource created.</nowiki>
 
 
 
=== Observers ===
 
 
 
:::'''Title''': <nowiki>Observers</nowiki>
 
:::'''URL''': <nowiki>/observers</nowiki>
 
:::'''Description''': <nowiki>Observers controller. Observers are users of the current website.</nowiki>
 
 
 
==== Public Functions ====
 
 
 
===== Current Observers =====
 
 
 
:::::'''Title''': <nowiki>Current Observers</nowiki>
 
:::::'''URL''': <nowiki>/observers/current</nowiki>
 
:::::'''Description''': <nowiki>Returns the currently logged-in users data. Search on optional parameters can also be done.</nowiki>
 
:::::'''Method''':
 
::::::'''0''': <nowiki>GET</nowiki>
 
:::::'''URL Params ''':
 
::::::'''Required''':
 
:::::::'''0''': <nowiki>user_pw</nowiki>
 
:::::::'''1''': <nowiki>user_email</nowiki>
 
::::::'''Optional''':
 
:::::::'''0''': <nowiki>name</nowiki>
 
:::::::'''1''': <nowiki>surname</nowiki>
 
:::::::'''2''': <nowiki>email</nowiki>
 
:::::'''Body Payload''': <nowiki />
 
:::::'''Possible Output Format''':
 
::::::'''0''': <nowiki>json</nowiki>
 
::::::'''1''': <nowiki>xml</nowiki>
 
:::::'''Usage''': <nowiki>GET /observers/current</nowiki>
 
:::::'''Return''': <nowiki>list of observers</nowiki>
 
 
 
=== Places controller ===
 
 
 
:::'''Title''': <nowiki>Places controller</nowiki>
 
:::'''URL''': <nowiki>/places</nowiki>
 
:::'''Description''': <nowiki>Places controller. Places are linked to the local admin units on which they are contained. On some websites places can represent directly a local admin unit.</nowiki>
 
 
 
==== Public Functions ====
 
 
 
===== List places =====
 
 
 
:::::'''Title''': <nowiki>List places</nowiki>
 
:::::'''URL''': <nowiki>/places</nowiki>
 
:::::'''Description''': <nowiki>Returns the list of all places. 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_commune</nowiki>
 
:::::::'''1''': <nowiki>name</nowiki>
 
:::::::'''2''': <nowiki>id_region</nowiki>
 
:::::::'''3''': <nowiki>place_type</nowiki>
 
:::::::'''4''': <nowiki>coord_lon</nowiki>
 
:::::::'''5''': <nowiki>coord_lat</nowiki>
 
:::::::'''6''': <nowiki>find_closest_place</nowiki>
 
:::::::'''7''': <nowiki>get_hidden</nowiki>
 
:::::::'''8''': <nowiki>pick_limit</nowiki>
 
:::::'''Body Payload''': <nowiki />
 
:::::'''Possible Output Format''':
 
::::::'''0''': <nowiki>json</nowiki>
 
:::::'''Usage''': <nowiki>GET /places list all places. GET /places with find_closest_place=1 and coord_lat=%lat% and coord_lon=%lon% search for the nearest place from the coordinate.</nowiki>
 
:::::'''Return''': <nowiki>A list of places.</nowiki>
 
 
 
===== Get a single place =====
 
 
 
:::::'''Title''': <nowiki>Get a single place</nowiki>
 
:::::'''URL''': <nowiki>/places/%id%</nowiki>
 
:::::'''Description''': <nowiki>Get a place of id %id%.</nowiki>
 
:::::'''Method''': <nowiki>GET</nowiki>
 
:::::'''URL Params ''':
 
::::::'''Required''':
 
:::::::'''0''': <nowiki>user_pw</nowiki>
 
:::::::'''1''': <nowiki>user_email</nowiki>
 
::::::'''Optional''':
 
 
 
:::::'''Body Payload''': <nowiki />
 
:::::'''Possible Output Format''':
 
::::::'''0''': <nowiki>json</nowiki>
 
::::::'''1''': <nowiki>xml</nowiki>
 
:::::'''Usage''': <nowiki>GET /places/5 retrieve entity of id 5.</nowiki>
 
:::::'''Return''': <nowiki>A place of id %id%.</nowiki>
 
 
 
=== Species Controller ===
 
 
 
:::'''Title''': <nowiki>Species Controller</nowiki>
 
:::'''URL''': <nowiki>/species</nowiki>
 
:::'''Description''': <nowiki>Species controller.</nowiki>
 
 
 
==== Public Functions ====
 
 
 
===== List Species =====
 
 
 
:::::'''Title''': <nowiki>List Species</nowiki>
 
:::::'''URL''': <nowiki>/species</nowiki>
 
:::::'''Description''': <nowiki>Returns the list of all species. 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>rarity</nowiki>
 
:::::::'''2''': <nowiki>french_name</nowiki>
 
:::::::'''3''': <nowiki>german_name</nowiki>
 
:::::::'''4''': <nowiki>english_name</nowiki>
 
:::::::'''5''': <nowiki>spanish_name</nowiki>
 
:::::::'''6''': <nowiki>dutch_name</nowiki>
 
:::::'''Body Payload''': <nowiki />
 
:::::'''Possible Output Format''':
 
::::::'''0''': <nowiki>json</nowiki>
 
::::::'''1''': <nowiki>xml</nowiki>
 
:::::'''Usage''': <nowiki>GET /species list all species.</nowiki>
 
:::::'''Return''': <nowiki>json with the list of species.</nowiki>
 
 
 
===== Get a single species =====
 
 
 
:::::'''Title''': <nowiki>Get a single species</nowiki>
 
:::::'''URL''': <nowiki>/species/%id%</nowiki>
 
:::::'''Description''': <nowiki>Get a species of id %id%.</nowiki>
 
:::::'''Method''': <nowiki>GET</nowiki>
 
:::::'''URL Params ''':
 
::::::'''Required''':
 
:::::::'''0''': <nowiki>user_pw</nowiki>
 
:::::::'''1''': <nowiki>user_email</nowiki>
 
::::::'''Optional''':
 
 
 
:::::'''Body Payload''': <nowiki />
 
:::::'''Possible Output Format''':
 
::::::'''0''': <nowiki>json</nowiki>
 
::::::'''1''': <nowiki>xml</nowiki>
 
:::::'''Usage''': <nowiki>GET /species/5 retrieve species of id 5.</nowiki>
 
:::::'''Return''': <nowiki>A species of id %id%.</nowiki>
 
 
 
=== Taxo groups ===
 
 
 
:::'''Title''': <nowiki>Taxo groups</nowiki>
 
:::'''URL''': <nowiki>/taxo_groups</nowiki>
 
:::'''Description''': <nowiki>Taxo groups controller. Each species has a family and a taxo group. Example of taxo groups: birds, sea mammals.</nowiki>
 
 
 
==== Public Functions ====
 
 
 
===== List taxo groups =====
 
 
 
:::::'''Title''': <nowiki>List taxo groups</nowiki>
 
:::::'''URL''': <nowiki>/taxo_groups</nowiki>
 
:::::'''Description''': <nowiki>Returns the list of all taxo groups. 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''':
 
 
 
:::::'''Body Payload''': <nowiki />
 
:::::'''Possible Output Format''':
 
::::::'''0''': <nowiki>json</nowiki>
 
::::::'''1''': <nowiki>xml</nowiki>
 
:::::'''Usage''': <nowiki>GET /taxo_groups list all taxo groups. GET /taxo_groups/%id% get one taxo group of %id%</nowiki>
 
:::::'''Return''': <nowiki>A list of taxo groups.</nowiki>
 
 
 
===== Get a single taxo group =====
 
 
 
:::::'''Title''': <nowiki>Get a single taxo group</nowiki>
 
:::::'''URL''': <nowiki>/taxo_groups/%id%</nowiki>
 
:::::'''Description''': <nowiki>Get a taxo group of id %id%.</nowiki>
 
:::::'''Method''': <nowiki>GET</nowiki>
 
:::::'''URL Params ''':
 
::::::'''Required''':
 
:::::::'''0''': <nowiki>user_pw</nowiki>
 
:::::::'''1''': <nowiki>user_email</nowiki>
 
::::::'''Optional''':
 
 
 
:::::'''Body Payload''': <nowiki />
 
:::::'''Possible Output Format''':
 
::::::'''0''': <nowiki>json</nowiki>
 
::::::'''1''': <nowiki>xml</nowiki>
 
:::::'''Usage''': <nowiki>GET /taxo_groups/5 retrieve taxo_groups of id 5.</nowiki>
 
:::::'''Return''': <nowiki>A taxo group of id %id%.</nowiki>
 
 
 
===== Create new taxo group =====
 
 
 
:::::'''Title''': <nowiki>Create new taxo group</nowiki>
 
:::::'''URL''':
 
::::::'''0''': <nowiki>/taxo_groups</nowiki>
 
:::::'''Description''': <nowiki>Create a new taxo group with id,name and access_mode.</nowiki>
 
:::::'''Method''': <nowiki>POST</nowiki>
 
:::::'''URL Params ''':
 
::::::'''Required''':
 
:::::::'''0''': <nowiki>user_pw</nowiki>
 
:::::::'''1''': <nowiki>user_email</nowiki>
 
::::::'''Optional''':
 
 
 
:::::'''Body Payload''': <nowiki>{"id":%id%,"name":%name%,"access_mode":%access_mode%}</nowiki>
 
:::::'''Possible Output Format''':
 
::::::'''0''': <nowiki>json</nowiki>
 
:::::'''Usage''': <nowiki>POST /taxo_groups with body payload : {"id":62,"name":"TAXO_TEST","access_mode":"full"} access_mode can be "full", "limited", "readonly", "none"</nowiki>
 
:::::'''Return''': <nowiki>success message.</nowiki>
 
 
 
===== Update a taxo group =====
 
 
 
:::::'''Title''': <nowiki>Update a taxo group</nowiki>
 
:::::'''URL''':
 
::::::'''0''': <nowiki>/taxo_groups/%id%</nowiki>
 
:::::'''Description''': <nowiki>Update a taxo group, change access_mode.</nowiki>
 
:::::'''Method''': <nowiki>PUT</nowiki>
 
:::::'''URL Params ''':
 
::::::'''Required''':
 
:::::::'''0''': <nowiki>user_pw</nowiki>
 
:::::::'''1''': <nowiki>user_email</nowiki>
 
:::::::'''2''': <nowiki>access_mode</nowiki>
 
::::::'''Optional''':
 
 
 
:::::'''Body Payload''': <nowiki />
 
:::::'''Possible Output Format''':
 
::::::'''0''': <nowiki>json</nowiki>
 
:::::'''Usage''': <nowiki>PUT /taxo_groups/%id% with access_mode="limited", access_mode can be "full", "limited", "readonly", "none"</nowiki>
 
:::::'''Return''': <nowiki>success message.</nowiki>
 
 
 
===== Delete a taxo group =====
 
 
 
:::::'''Title''': <nowiki>Delete a taxo group</nowiki>
 
:::::'''URL''':
 
::::::'''0''': <nowiki>/taxo_groups/%id%</nowiki>
 
:::::'''Description''': <nowiki>Delete a taxo group.</nowiki>
 
:::::'''Method''': <nowiki>DELETE</nowiki>
 
:::::'''URL Params ''':
 
::::::'''Required''':
 
:::::::'''0''': <nowiki>user_pw</nowiki>
 
:::::::'''1''': <nowiki>user_email</nowiki>
 
::::::'''Optional''':
 
 
 
:::::'''Body Payload''': <nowiki />
 
:::::'''Possible Output Format''':
 
::::::'''0''': <nowiki>json</nowiki>
 
:::::'''Usage''': <nowiki>DELETE /taxo_groups/%id%</nowiki>
 
:::::'''Return''': <nowiki>success message.</nowiki>
 
 
 
=== Taxo groups by website ===
 
 
 
:::'''Title''': <nowiki>Taxo groups by website</nowiki>
 
:::'''URL''': <nowiki>/taxo_website</nowiki>
 
:::'''Description''': <nowiki>Taxo groups by website controller.</nowiki>
 
 
 
==== Public Functions ====
 
 
 
===== List links between taxo groups and websites =====
 
 
 
:::::'''Title''': <nowiki>List links between taxo groups and websites</nowiki>
 
:::::'''URL''': <nowiki>/taxo_website</nowiki>
 
:::::'''Description''': <nowiki>Returns the list of all taxo groups by website.</nowiki>
 
:::::'''Method''': <nowiki>GET</nowiki>
 
:::::'''URL Params ''':
 
::::::'''Required''':
 
:::::::'''0''': <nowiki>user_pw</nowiki>
 
:::::::'''1''': <nowiki>user_email</nowiki>
 
::::::'''Optional''':
 
 
 
:::::'''Body Payload''': <nowiki />
 
:::::'''Possible Output Format''':
 
::::::'''0''': <nowiki>json</nowiki>
 
::::::'''1''': <nowiki>xml</nowiki>
 
:::::'''Usage''': <nowiki>GET /taxo_website list all taxo groups by websites.</nowiki>
 
:::::'''Return''': <nowiki>A list of links between taxo groups and websites.</nowiki>
 
 
 
===== Get a single link between taxo groups and websites =====
 
 
 
:::::'''Title''': <nowiki>Get a single link between taxo groups and websites</nowiki>
 
:::::'''URL''': <nowiki>/taxo_website/%id%</nowiki>
 
:::::'''Description''': <nowiki>Get a link between a taxo group and a website of id %id%.</nowiki>
 
:::::'''Method''': <nowiki>GET</nowiki>
 
:::::'''URL Params ''':
 
::::::'''Required''':
 
:::::::'''0''': <nowiki>user_pw</nowiki>
 
:::::::'''1''': <nowiki>user_email</nowiki>
 
::::::'''Optional''':
 
 
 
:::::'''Body Payload''': <nowiki />
 
:::::'''Possible Output Format''':
 
::::::'''0''': <nowiki>json</nowiki>
 
::::::'''1''': <nowiki>xml</nowiki>
 
:::::'''Usage''': <nowiki>GET /taxo_website/5 retrieve a link between a taxo group and a website of id 5.</nowiki>
 
:::::'''Return''': <nowiki>A link between a taxo group and a website.</nowiki>
 
 
 
=== Territorial Units Controller. ===
 
 
 
:::'''Title''': <nowiki>Territorial Units Controller.</nowiki>
 
:::'''URL''': <nowiki>/territorial_units</nowiki>
 
:::'''Description''': <nowiki>Territorial Units controller. A territorial unit is an area that contains the local admin units (see local admin units controller). Example of territorial unit: Canton, Département, Kreise</nowiki>
 
 
 
==== Public Functions ====
 
 
 
===== List Territorial Units =====
 
 
 
:::::'''Title''': <nowiki>List Territorial Units</nowiki>
 
:::::'''URL''': <nowiki>/territorial_units</nowiki>
 
:::::'''Description''': <nowiki>Returns the list of all local territorial units. 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_country</nowiki>
 
:::::::'''1''': <nowiki>name</nowiki>
 
:::::::'''2''': <nowiki>short_name</nowiki>
 
:::::'''Body Payload''': <nowiki />
 
:::::'''Possible Output Format''':
 
::::::'''0''': <nowiki>json</nowiki>
 
::::::'''1''': <nowiki>xml</nowiki>
 
:::::'''Usage''': <nowiki>GET /territorial_units list all local admin units. GET /territorial_units with name=%name% search for all territorial units with name=%name%.</nowiki>
 
:::::'''Return''': <nowiki>A list of local territorial units.</nowiki>
 
 
 
===== Get a single territorial unit =====
 
 
 
:::::'''Title''': <nowiki>Get a single territorial unit</nowiki>
 
:::::'''URL''': <nowiki>/territorial_units/%id%</nowiki>
 
:::::'''Description''': <nowiki>Get a territorial unit of id %id%.</nowiki>
 
:::::'''Method''': <nowiki>GET</nowiki>
 
:::::'''URL Params ''':
 
::::::'''Required''':
 
:::::::'''0''': <nowiki>user_pw</nowiki>
 
:::::::'''1''': <nowiki>user_email</nowiki>
 
::::::'''Optional''':
 
 
 
:::::'''Body Payload''': <nowiki />
 
:::::'''Possible Output Format''':
 
::::::'''0''': <nowiki>json</nowiki>
 
::::::'''1''': <nowiki>xml</nowiki>
 
:::::'''Usage''': <nowiki>GET /territorial_units/5 retrieve a territorial unit of id 5.</nowiki>
 
:::::'''Return''': <nowiki>A territorial unit.</nowiki>
 
 
 
=== Validations controller ===
 
 
 
:::'''Title''': <nowiki>Validations controller</nowiki>
 
:::'''URL''': <nowiki>/validations</nowiki>
 
:::'''Description''': <nowiki>Validations controller. A validation is composed of a start date, a stop date, a specie and a validation committee.</nowiki>
 
 
 
==== Public Functions ====
 
 
 
===== List Validations =====
 
 
 
:::::'''Title''': <nowiki>List Validations</nowiki>
 
:::::'''URL''': <nowiki>/validations</nowiki>
 
:::::'''Description''': <nowiki>Returns the list of all validations. 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>committee</nowiki>
 
:::::::'''1''': <nowiki>date_start</nowiki>
 
:::::::'''2''': <nowiki>date_stop</nowiki>
 
:::::::'''3''': <nowiki>id_species</nowiki>
 
:::::'''Body Payload''': <nowiki />
 
:::::'''Possible Output Format''':
 
::::::'''0''': <nowiki>json</nowiki>
 
::::::'''1''': <nowiki>xml</nowiki>
 
:::::'''Usage''': <nowiki>GET /validations list all validations.</nowiki>
 
:::::'''Return''': <nowiki>A list of validations.</nowiki>
 
 
 
===== Get a single validation =====
 
 
 
:::::'''Title''': <nowiki>Get a single validation</nowiki>
 
:::::'''URL''': <nowiki>/validations/%id%</nowiki>
 
:::::'''Description''': <nowiki>Get a validation of id %id%.</nowiki>
 
:::::'''Method''': <nowiki>GET</nowiki>
 
:::::'''URL Params ''':
 
::::::'''Required''':
 
:::::::'''0''': <nowiki>user_pw</nowiki>
 
:::::::'''1''': <nowiki>user_email</nowiki>
 
::::::'''Optional''':
 
 
 
:::::'''Body Payload''': <nowiki />
 
:::::'''Possible Output Format''':
 
::::::'''0''': <nowiki>json</nowiki>
 
::::::'''1''': <nowiki>xml</nowiki>
 
:::::'''Usage''': <nowiki>GET /validations/5 retrieve a validation of id 5.</nowiki>
 
:::::'''Return''': <nowiki>A validation.</nowiki>
 

Version actuelle datée du 14 juin 2019 à 16:11

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 communes

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)

API documentation

Please see on the portal. For exemple https://www.ornitho.ch/index.php?m_id=43 (You must be logged in)