Documentation

Utilisation de l'API

L'API permet de consulter la table des observations de la base de données Agromet. Les stations mises à dispositions sont celles du réseau "Pameseb" du CRA-W.

Les mesures disponibles concernent:

  • la température sèche en °C (tsa),
  • la température humide en °C (tha),
  • les précipitations en mm (plu) ,
  • l'humidité relative en % (hra),
  • l'ensoleillement en W/m² si horaire et J/cm² si journalier (ens),
  • l'humectation du feuillage en % ou nb min/heure (hct),
  • la vitesse du vent à 2 mètres en m/s (vvt),
  • la direction du vent à 2 mètres en °N (dvt),
  • la température sous feuillage en °C (tsf),
  • la température sous sol en °C (tss).

Les données fournies sont de fréquence horaire ou journalière.


Obtenir un token

Pour utiliser l'API, vous devez être enregistré auprès du système. Pour le moment, la seule manière d'obtenir un token se fait par email.


Exemple d'appel à l'API avec un script Python

import requests

def requests_with_url_and_token(url, token):
    """
    Example using the requests library
    """

    response = requests.get(url, headers={'Authorization': 'Token {0}'.format(token)})

    return response

if __name__ == '__main__':    
    my_token = 'my_token'
    url =  'https://agromet.be/fr/agromet/api/v3/get_pameseb_hourly/tsa,plu,hra/1,26/2018-09-01/2018-09-05/'
    test = requests_with_url_and_token(url, my_token)

Exemple d'appel à l'API avec un script Curl

curl  -H "Authorization: Token my_token" -L https://agromet.be/fr/agromet/api/v3/get_pameseb_hourly/tsa,plu,hra/1,26/2018-09-01/2018-09-05/

Exemple d'appel à l'API avec un script R

rfunction_with_url_and_token <- function(user_token,  url){

  # Add your user token into the HTTP authentication header
  api_table_req.resp <- httr::GET(url, httr::add_headers("Authorization" = paste("Token", user_token, sep=" ")))

  # Getting the JSON data from the API response
  api_results_json <- httr::content(api_table_req.resp, as = "text")
  
  return(api_results_json) 
}

 my_token = "my_token"
 url =  "https://agromet.be/fr/agromet/api/v3/get_pameseb_hourly/tsa,plu,hra/1,26/2018-09-01/2018-09-05/"
 test = rfunction_with_url_and_token(my_token, url)

Exemple d'appel à l'API avec un script en PHP

function getAPIurl($url, $token) {
    $headers = array(
        'Content-Type: application/json',
        sprintf('Authorization: Token %s', $token)
    );
    
    $curl = curl_init($url);
    
    curl_setopt($curl, CURLOPT_HTTPHEADER, $headers);
    curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
    
    $result = json_decode(curl_exec($curl));
    curl_close($curl);
    
    return $result;
}

$my_token = 'my secret token';
$my_url =  'https://agromet.be/fr/agromet/api/v3/get_pameseb_hourly/tsa,plu,hra/1,26/2018-09-01/2018-09-05/';
$test = getAPIurl($my_url, $my_token);
echo(json_encode($test));

Format de la réponse

Par défaut, l'API renvoie une réponse en format JSON. Celle-ci répond au schema de validation suivant, mais il est aussi possible d'obtenir une réponse en format CSV. Dans ce dernier cas seule la partie 'results' est renvoyée. La dernière ligne du fichier CSV reprend les "terms of service".

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "version": {
      "type": "string"
    },
    "terms_of_service": {
      "type": "string"
    },
    "frequency": {
      "type": "string"
    },
    "references": {
      "type": "object",
      "properties": {
        "stations": {
          "type": "array",
          "items": [
            {
              "type": "object"
            }
          ]
        },
        "points": { 
          "type": "array", 
          "items": [ 
           { 
             "type": "object" 
            } 
          ] 
        }
      }
    },
    "results": {
      "type": "array",
      "items": [
        {
          "type": "object"
        }
      ]
    }
  },
  "required": [
    "version",
    "terms_of_service",
    "frequency",
    "references",
    "results"
  ]
}



Requêtes courantes

Données horaires

exemple:

https://agromet.be/fr/agromet/api/v3/get_pameseb_hourly/tsa,plu,hra/1,26/2018-09-01/2018-09-05/

 

syntaxe:

/agromet/api/v3/get_pameseb_hourly/sensors/station_sids/date_from/date_to/format/

 

paramètres (nb la séquence de ceux-ci doit être respectée):

  • sensors => liste de mesures séparées par des virgules => mesures disponibles: 'tsa', 'tha', 'hra', 'ens', 'dvt', 'vvt', 'plu', 'hct', 'tsf', 'tss' utiliser 'all' pour toutes;
  • station_sids => liste de sid station séparées par des virgules exemple 1,26,35 utiliser 'all' pour toutes;
  • date from => exemple 2017-09-01
  • date to => exemple 2017-09-15

paramètre optionnel:

  • format: format de la réponse: 'json' or 'csv' défaut = 'json'.

Données journalières

exemple:

https://agromet.be/fr/agromet/api/v3/get_pameseb_daily/tsa,plu,hra/1,26/2017-09-01/2017-09-15/

 

syntaxe:

/agromet/api/v2/get_pameseb_daily/sensors/station_sids/date_from/date_to/format/

 

paramètres (nb la séquence de ceux-ci doit être respectée):

  • sensors => liste de mesures séparées par des virgules => mesures disponibles: voir données horaires plus etp (évapotranspiration) et chaque mesure horaire suivie de '_min', '_max', '_avg' ou '_sum'. Utiliser 'all' pour toutes;
  • station_sids => liste de sid station séparées par des virgules exemple 1,26,35 utiliser 'all' pour toutes;
  • date from => exemple 2017-09-01
  • date to => exemple 2017-09-15

paramètre optionnel:

  • format: format de la réponse: 'json' or 'csv' défaut = 'json'.

Prévisions horaires

Les prévisions sont réalisées grâce aux données fournies par The Dark Sky net.

exemple:

https://agromet.be/fr/agromet/api/v3/get_pameseb_hourly_prev/tsa,plu,hra/1,26/7/

 

syntaxe:

/agromet/api/v3/get_pameseb_hourly_prev/sensors/station_sids/nb_days/format/

 

paramètres (nb la séquence de ceux-ci doit être respectée):

  • sensors => liste de mesures séparées par des virgules => mesures disponibles: 'tsa', 'tha', 'hra', 'ens', 'dvt', 'vvt', 'plu', 'hct', 'tsf', 'tss' utiliser 'all' pour toutes;
  • station_sids => liste de sid station séparées par des virgules exemple 1,26,35 utiliser 'all' pour toutes;
  • nb_days => entier, nombres de jours de prévision (max 7)

paramètre optionnel:

  • format: format de la réponse: 'json' or 'csv' défaut = 'json'.

Données spatialisées horaires

Les données spatialisées au km² sont calculées par nos soins sur base des observations aux stations. Ces données sont en phase expérimentale à utiliser avec un bon esprit critique.

exemple:

https://agromet.be/fr/geomatique/api/v3/get_spatial_hourly/all/5.36076/49.92667/2019-03-01T00:00:00Z/2019-03-02T00:00:00Z/

 

syntaxe:

/geomatique/api/v3/get_spatial_hourly/sensors/lon/lat/date_from/date_to/pts/format/

 

paramètres (nb la séquence de ceux-ci doit être respectée):

  • sensors: liste de mesures séparées par des virgules => mesures disponibles: ['tsa', 'hra', 'ens', 'hct'] utiliser 'all' pour toutes;
  • lon: longitude en degrés decimaux => exemple 5.36076;
  • lat: latitude en degrés decimaux => exemple 49.92667;
  • date from: en temps universel UTC => exemple 2019-02-01T00:00:00Z;
  • date to: en temps universel UTC => exemple 2019-02-15T00:00:00Z.

paramètres optionnels:

  • pts: nombre de points les plus proches, défaut = 1 max = 12;
  • format: format de la réponse: 'json' or 'csv' défaut = 'json'.

 

Règles d'agrégation des données.

Nos données brutes sont soit à la minute soit horaires. Nous n'affichons pas pour le moment de données à la minute, mais nous appliquons déjà des règles d'agrégation pour les obtenir des données horaires depuis les données à la minute.

Distinguer les capteurs de pluie (plu) et ensoleillement (ens) qui sont sommés (SUM) et les autres pour lesquels nous déterminons des minimums (min), moyennes (moy) et maximums (max).

Minute.

Pas d'agrégations.

Horaire.

moy.

moyenne des valeurs des 60 minutes précédentes de h:01 à h+1:00.

sum.

somme des valeurs des 60 minutes précédentes de h:01 à h+1:00.

Exception: count hct.

Pour le capteur d'humectation du feuillage (hct) = comptage du nombre de minutes pour lesquelles la valeur du capteur est supérieur à un seuil.

Journalier.

min.

Minimum des valeurs horaires entre 1h UTC +1 à 0h UTC +1.

moy.

Moyenne des valeurs horaires entre 1h UTC +1 à 0h UTC +1.

max.

Maximum des valeurs horaires entre 1h UTC +1 à 0h UTC +1.

sum.

Somme des valeurs horaires de 1h UTC +1 à 0h UTC +1.

Hebdomadaire.

min.

Moyenne des minimums des valeurs journalières entre lundi et dimanche.

moy.

Moyenne des valeurs journalières entre lundi et dimanche.

max.

Moyenne des maximums des valeurs journalières entre lundi et dimanche.

sum.

Somme des valeurs des valeurs journalières entre lundi et dimanche.

Décadaire.

  • première décade du mois du 1 au 10 du mois;
  • deuxième décade du mois du 11 au 20 du mois;
  • troisième décade du mois du 21 à la fin du mois;
min.

Moyenne des minimums des valeurs journalières entre premier et dernier jour de la décade.

moy.

Moyenne des valeurs journalières entre premier et dernier jour de la décade.

max.

Moyenne des maximums des valeurs journalières entre premier et dernier jour de la décade.

sum.

Somme des valeurs des valeurs journalières entre premier et dernier jour de la décade.

Mensuel.

min.

Moyenne des minimums des valeurs journalières entre le premier et le dernier jour du mois.

moy.

Moyenne des valeurs journalières entre le premier et le dernier jour du mois.

max.

Moyenne des maximums des valeurs journalières entre le premier et le dernier jour du mois.

sum.

Somme des valeurs des valeurs journalières entre le premier et le dernier jour du mois.