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.

optional params:

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