Usage de l'API

Informations générales

L'API (Application Programming Interface) Poids-Plume permet d'accéder aux données en utilisant des outils informatiques, plutôt que via les visualisations proposées sur le site web. C'est le point d'entrée privilégié si vous souhaitez analyser les données du projet, ou encore télécharger les données de votre mangeoire.

Pour utiliser l'API, il vous faut un compte à jour de son adhésion sur le site web Poids Plume, et une clé d'API (disponible sur votre compte utilisateur). L'usage de l'API se fait dans le respect de ses conditions d'utilisation rappelées sur la page d'information pour un utilisateur. En plus de ces conditions d'utilisations, nous souhaiterions être un peu au courant de l'usage qu'en font les utilisateurs - n'hésitez-pas à nous communiquer toute utilisation que vous en faites, voire à présenter vos résultats à l'association ! Via la mailing liste par exemple ou lors des AGs.

Informations techniques

Les informations accessibles via l'API Poids-Plume incluent les données issues des capteurs sur les mangeoires (poids, température, etc.), et les informations sur les vidéos des oiseaux (annotations, poids mesurée, etc.). Les vidéos elles-mêmes sont inaccessibles via ce service.

L'accès se fait via une requête POST sur l'adresse https://data.poids-plume.fr/data.php, en renseignant les champs suivants dans la requête:

• feeder: la mangeoire pour laquelle les données sont à télécharger

• date: la date pour laquelle télécharger les données (au format YYYY-MM-DD)

• datatype: le type de données à télécharger, 'rawdata', 'filtdata' ou 'visits', correspondant au données interpolées, filtrées et aux visites (voir la page d'information sur les Données_téléchargées)

• username: l'utilisateur faisant la requête (votre nom d'utilisateur)

• sig: Un HMAC sha-256 de votre requête et de votre clé d'API (voir code bash ci-dessous)

La code de réponse http de la page peut être 400 (Bad request) si les paramètres ci-dessus sont mal définis, 403 (Forbidden) si l'accès est refusé ou 404 si aucune donnée correspondante n'a été trouvée. Un message plus explicite expliquant pourquoi la requête a raté est renvoyé. Si la requête est bien formulée, un code de réponse 200 (OK) est renvoyé, et les données sont transférées au client.

Concrètement, les données se présentent sous la forme d'un fichier '.xz' contenant des données tabulaires au format texte (les valeurs étant séparées par des tabulations, voir aussi les informations sur les données téléchargées). Il faut extraire ce fichier (avec tar -xf par exemple), puis les données peuvent être (enfin) lues avec votre logiciel préféré. En pratique, on utilisera la plupart du temps des outils intermédiaires pour effectuer ce travail.

Outils

Script bash minimal

Le script bash ci-dessous devrait pouvoir vous permettre d'effectuer une requête de données via l'API en téléchargeant des données pour une combinaison mangeoire/date/type de données. Il faut remplacer les champs API_USER et API_KEY par leurs valeurs (attention à ne pas faire fuiter ces informations publiquement !). Il peut servir également d'une implémentation de référence pour d'autres implémentations.

Attention, le script ne gère pas les erreurs (absence de données, mauvaise authentification, etc.), et n'extrait pas le fichier '.xz' téléchargé. Livre à vous de l'améliorer ! ;)

#!/bin/bash
# 
# Minimal script to access data from the Poids-Plume project
# 

# User information 
API_KEY="<key>"
API_USER="<user>"

# Information on request
FEEDER="carduelis"
DATE="2020-12-20"
DATATYPE="rawdata"

# Compute hmac
SIG="$(echo -n "${FEEDER}${DATE}${DATATYPE}${API_USER}" | \
         openssl sha256 -hmac "$API_KEY" | \
         cut -d"=" -f2 | 
         sed "s/ //g")"

# Make request
curl -X POST \
  -d "feeder=$FEEDER" \
  -d "date=$DATE" \
  -d "datatype=$DATATYPE" \
  -d "username=$API_USER" \
  -d "sig=$SIG" \
  --output "${DATATYPE}_${FEEDER}_$DATE.xz" \
  "https://data.poids-plume.fr/data.php"