Utilisation de l'API de BASULM

Introduction

La Fédération Française d'ULM propose une API aux développeurs souhaitant utiliser les ressources collectées par ses licenciés au sein du site web BASULM opéré par la Fédération.

Prérequis

Une API (Application Programming Interface) s'adresse aux développeurs maîtrisant ce concept (RestFULL API). La fédération n'a pas vocation a apporter un support technique sur la mise au point d'applications tierces.

L'utilisation des primitives de l'API permettant de récupérer les informations nécessite l'utilisation d'une clef. Celle-ci peut-être sollicitée auprès des responsables de BASULM via le formulaire de contact du site. Vous retrouverez la clef qui vous sera attribuée dans votre espace personnel (MyBasulm). Vous devez donc être enregistré au sein de BASULM pour demander et utiliser l'API. Ceci implique aussi que vous lisiez et acceptez les conditions d'utilisation des informations proposées.

Version

L'API est la présente documentation est actuellement dans sa version 1.3.

Modification en date du 4 janvier 2021 : Pour des raisons de sécurité, la requête envoyée à l'API doit spécifier un "user-agent". Voir l'exemple PHP à la fin de cet article. Vous pouvez déclarer votre propre "user-agent" mais la propriété doit exister dans la requête et ne pas être vide.

Point d'entrée

Le point d'entrée de l'API est <getbasulm>.

L'url d'accès au point d'entrée est donc :

https://basulm.ffplum.fr/getbasulm

Protocole

L'API, comme le site, n'est accessible qu'en protocole sécurisé SSL. Toutes les requêtes doivent répondre au protocole HTTPS.

Méthode

La seule méthode implémentée dans cette version est <get>

Module

Le seul module implémenté dans cette version est le module <basulm> qui donne accès aux bases ULM recensées.

Actions

Les 5 actions disponibles dans cette version sont

• <about> : renvoie la version de l'API. Utile pour tester. Pas de paramètres.
• <liste> : renvoie la liste simplifiée des bases publiées sur le site. Possibilité de ne récupérer que les bases qui ont été mises à jour ou modifées depuis une certaine date
• <detail> : renvoie les informations détaillées d'une base dont l'id est passé en paramètre.
• <getByCode> : renvoie les informations détaillées d'une base dont le code terrain (LFxxxx) est passé en paramètre.
• <listall> : renvoie les informations détaillées de toutes les bases publiées.

Requêtes

Les requêtes sont consitutuées de la concaténation du domaine, du point d'entrée, de la méthode, du module de l'action et des paramètres.

exemple de requêtes :

• basulm.ffplum.fr/getbasulm/get/basulm/about

• basulm.ffplum.fr/getbasulm/get/basulm/liste?date=2017-08-27

• basulm.ffplum.fr/getbasulm/get/basulm/detail?id=999

• basulm.ffplum.fr/getbasulm/get/basulm/listall

 

Header et clef de l'API

Le header de la requête transmise à l'API doit contenir un champ <Authorization>.

La valeur de ce champ doit être composé du mot <api_key> suivi de votre clef.

Exemple d'un header HTTP si votre clef est ABCDEF1982333SDF :

GET /getbasulm/get/basulm/about HTTP/1.1
Host: basulm.ffplum.fr
Authorization: api_key ABCDEF1982333SDF
Cache-Control: no-cache

Réponses

Les réponses sont renvoyées sous la forme d'une chaîne de caractère de type JSON

Le premier champ <status> indique si la requête a été acceptée ou pas.

• <ok> : requête acceptée. Les champs suivants contiennent les données.
• <ko>: la requête a été refusée. Les deux champs suivants contiennent le code de l'erreur est un message d'explication

Exemple de réponse pour une requête refusée :

{
"status": "ko",
"error_code": "REQ_AKI",
"error_description": "API key invalid"
}

Exemple de réponse pour une requête acceptée :

{
"status": "ok",
"about": "Bienvenue sur l'API de BASULM",
"version": "1.0"
}

Détail des actions et exemples de réponses 

about

Cette action est utile pour tester l'accès à l'API et vérifier votre clef. Elle n'a aucun paramètre.

Exemple de requête :

https:basulm.ffplum.fr/getbasulm/get/basulm/about

Exemple de reponse :

{
"status": "ok",
"about": "Bienvenue sur l'API de BASULM",
"version": "1.3"
}

liste

Cette action permet d'obtenir la liste de tous les terrains BASULM qui sont visibles sur le site public. Seuls les champs principaux sont renvoyés afin d'alléger la taille de la réponse.

Il est possible de spécifier un paramètre <date> sous la forme <YYYY-MM-DD> afin de ne récupérer que les terrains qui ont été modifiés ou créés depuis la date indiquée. En l'absence de ce paramètre, tous les terrains sont renvoyés.

Les terrains obsolètes ou archivés (supprimés de fait) ne sont pas renvoyés. Il vous appartient de vérifier que la liste des codes terrains renvoyée diverge ou pas avec celle stockée dans votre application pour détecter les terrains éventuellement supprimés de la liste publique.

Important : le premier champ renvoyé est <ID>. Il s'agit d'un idenficateur temporaire qui vous permet d'utiliser l'action <detail> pour récupérer toutes les informations d'un terrain donné. Cet ID peut varier dans le temps. Il ne constitue pas une référence absolue à un terrain donné. Nous vous déconseillons de stocker et d'utiliser ce champ dans votre application.

Exemple de requête sans paramètre:

https:basulm.ffplum.fr/getbasulm/get/basulm/liste

Exemple de reponse :

{
"status": "ok",
"nature": "Liste des champs principaux de tous les terrains publiés",
"count": "1210",
"liste": [
{
"id": "56",
"date_modif": "2014-03-02 07:40:20",
"code_terrain": "LF0535",
"toponyme": "Le Buzon Gap",
"type_terrain": "Base ULM fermée définitivement",
"latitude": "N 44 36 12",
"longitude": "E 006 06 22",
"pays": "France",
"region": "Provence-Alpes-Côte d'azur",
"departement": "Hautes-Alpes",
"ville": "",
"altitude": ""
},
{
"id": "73",
"date_modif": "2014-01-13 10:20:37",
"code_terrain": "LF0751",
"toponyme": "Echamps ",
"type_terrain": "Base ULM Autorisation OBLIGATOIRE ",
"latitude": "N 44 50 51",
"longitude": "E 004 11 42",
"pays": "France",
"region": "Auvergne-Rhône-Alpes",
"departement": "Ardèche",
"ville": "Sainte-Eulalie",
"altitude": "3772 ft"
}
.../...
]
}

Exemple de requête avec paramètre :

https:basulm.ffplum.fr/getbasulm/get/basulm/liste?date=2017-04-01

Exemple de reponse :

{
"status": "ok",
"nature": "Liste des champs principaux des terrains modifiés après le 2017-03-31 22:00:00 (UTC)",
"count": "2",
"liste": [
{
"id": "5714",
"date_modif": "2017-06-17 15:28:33",
"code_terrain": "LF2445",
"toponyme": "Braulen",
"type_terrain": "Base ULM fermée définitivement",
"latitude": "N 44 52 07",
"longitude": "E 001 17 24",
"pays": "France",
"region": "Nouvelle Aquitaine",
"departement": "Dordogne",
"ville": "",
"altitude": ""
},
{
"id": "7470",
"date_modif": "2017-06-07 10:18:45",
"code_terrain": "LF6651",
"toponyme": "Torreilles",
"type_terrain": "Aérodrome Privé Ouvert aux ULM",
"latitude": "N 42 44 51",
"longitude": "E 003 00 58",
"pays": "France",
"region": "Occitanie",
"departement": "Pyrénées-Orientales",
"ville": "Torreilles",
"altitude": "10 ft"
}
]
}

Remarque : Toutes les dates stockées dans BASULM sont au format UTC. Il en est de même pour le champ <date_modif> renvoyé par l'API. La date transmise en paramètre est implicitement considérée comme se référant au fuseau horaire de Paris (Europe/Paris) avec une heure à 00:00:00. Elle est convertie en temps UTC par l'API. C'est normalement peu important du fait que l'on ne s'intéresse pas à l'heure de la modification dans cette application. Il faut néanmoins en tenir compte si on fait des manipulations sur la date renvoyée car cela peut entraîner un changement de jour apparent comme dans l'exemple ci-dessus (demande : 1 avril 2017 à 00:00 Europe/Paris, réponse : 31 mars 2017 22:00 UTC).

detail

Cette action permet d'obtenir les informations détaillée d'un terrain donné.

Il est obligatoire de spécifier le paramètre <id> sous la forme d'un entier positif afin de récupérer les informations du terrain en question. L'id doit correspondre à l'un de ceux renvoyés par l'action <liste> (premier champ).

Important : dans le cas d'une mise à jour des informations de votre application, n'utilisez pas cette valeur comme index unique. Le code terrain est unique. C'est le seul champ qui permet d'identifier de façon certaine un terrain. L'id n'est cohérent que dans le temps d'une utilisation de l'API. En effet, une modification soumise par un licencié et acceptée par les administrateurs de BASULM entraîne un changement d'ID alors que le code terrain reste inchangé.

Exemple de requête correcte :

https:basulm.ffplum.fr/getbasulm/get/basulm/detail?id=5714

Réponse correspondante :

{
"status": "ok",
"nature": "Informations détaillées sur un seul terrain",
"count": "1",
"detail": {
"id": "5714",
"date_modif": "2017-06-17 15:28:33",
"code_terrain": "LF2445",
"toponyme": "Braulen",
"type_terrain": "Base ULM fermée définitivement",
"latitude": "N 44 52 07",
"longitude": "E 001 17 24",
"pays": "France",
"region": "Nouvelle Aquitaine",
"departement": "Dordogne",
"ville": "",
"altitude": "",
"radio": "",
"nb_pistes": "1",
"nature_piste_1": "herbe",
"largeur_piste_1": "",
"longueur_piste_1": "",
"orientation_piste_1": "Inconnue",
"orientation_pref_1": "",
"nature_piste_2": "",
"largeur_piste_2": "",
"longueur_piste_2": "",
"orientation_piste_2": "",
"orientation_pref_2": "",
"classes": null,
"consignes": ""
}
}

Exemple de requête avec paramètre un paramètre invalide :

https:basulm.ffplum.fr/getbasulm/get/basulm/detail?id=5713

Exemple de reponse :

{
"status": "ko",
"error_code": "BLM_IID",
"error_description": "Supplied id does not exist"
}

getByCode

Cette action permet d'obtenir les informations détaillée d'un terrain donné par son code terrain (LFddnn ou LFAA)

Il est nécessaire de spécifier le paramètre <code> qui doit correspondre à un code terrain valide afin de récupérer les informations du terrain en question. Seuls les terrains publiés (visibles sur le site publique) sont reconnus.

Les codes correspondent soit au code OACI des aéroports (LF pour la France suivies de deux autres lettres) soit aux codes attribués par la Fédération (LF pour la France suivies des 2 chiffres représentant le département suivis de deux chiffres représentant le terrain). Le code terrain est unique et permet de désigner un terrain donné de façon non équivoque (clef).

Le code n'est pas sensible à la casse. "getByCode?code=lfbr" renverra les mêmes informations que "getByCode?code=LFBR"

Exemple de requête correcte :

https:basulm.ffplum.fr/getbasulm/get/basulm/getByCode?code=LF8257

Réponse correspondante :

{
"status": "ok",
"nature": "Informations détaillées sur un terrain par son code",
"count": "1",
"detail": {
"date_modif": "2017-04-22 08:26:32",
"code_terrain": "LF8257",
"toponyme": "Labastide Saint Pierre",
"type_terrain": "Base ULM Accès privé",
"latitude": "N 43 53 54",
"longitude": "E 001 21 52",
"altitude": "330 ft",
"pays": "France",
"region": "Occitanie",
"departement": "Tarn-et-Garonne",
"ville_postale": "Labastide-Saint-Pierre",
"radio": "Auto-info 123.5",
"nb_pistes": "1",
"nature_piste_1": "herbe",
"largeur_piste_1": "35",
"longueur_piste_1": "290",
"orientation_piste_1": "07-25",
"orientation_pref_1": "",
"nature_piste_2": "",
"largeur_piste_2": "",
"longueur_piste_2": "",
"orientation_piste_2": "",
"orientation_pref_2": "",
"classes": [
"2",
"3",
"4",
"6"
],
"consignes": "Tour de piste au sud, intégration 1300 pieds, vent arrière derrière la ferme, circuit 900 pieds. \r\n\r\nÉcolage interdit. Piste privée, utilisation de la piste sous réserve d'autorisation du gestionnaire.",
"statut": "Usager",
"adresse_postale": "Lieu-dit \"Malos\"",
"code_postal": "82370",
"display_contact_info": "non utilisé",
"nom_contact": "Marty Josian",
"mail_contact": "",
"adresse_contact": "",
"tel_contact_1": "+33 6 03 64 62 88",
"tel_contact_2": "+33 6 09 60 42 48",
"facilities": "",
"carburant": "",
"infos": "\r\n",
"site_web": "www.ulmlabastide.fr",
"gestionnaire": "ULM LABASTIDE"
}
}

Exemple de requête avec paramètre un paramètre invalide :

https:basulm.ffplum.fr/getbasulm/get/basulm/getByCode?code=LFPARIS

Exemple de reponse :

{
"status": "ko",
"error_code": "BLM_UKN",
"error_description": "Supplied Code_terrain is unknown"
}

 

listall

Cette action combine les possibilités de l'action "liste" et de l'action "detail". Elle renvoie la liste de tous les terrains publiés comme l'action "liste" mais au lieu de ne renvoyer que les informations essentielles, "listall" renvoie toutes les informations disponibles dans l'action "detail".

Ceci permet d'obtenir en une seule opération la liste complète des terrains avec toutes les informations détaillées pour chacun.

Pour limiter le volume des données renvoyées, vous avez la possibilité de préciser une date comme pour l'action "liste" (même paramètre, même syntaxe). Ceci permet de limiter la réponse aux seuls terrains qui ont été modifiés ou créés depuis la date transmise en paramètre.

ATTENTION : le résultat peut être volumineux (> 2 Mo). Il est important de ne pas activer cette action à une fréquence supérieure à une fois par jour sauf à mettre en place une procédure incrémentale basée sur la date pour ne récupérer que les terrains modifiés/créés lors des requêtes suivantes.

Exemple de requête :

https:basulm.ffplum.fr/getbasulm/get/basulm/listall?date="2017-04-01"

Exemple de reponse :

{
"status": "ok",
"nature": "Liste détaillée de tous les terrains modifiés ou créés après le 2017-03-31 22:00:00 (UTC)",
"count": "89",
"liste": [
{
"id": "5714",
"date_modif": "2017-06-17 15:28:33",
"code_terrain": "LF2445",
"toponyme": "Braulen",
"type_terrain": "Base ULM fermée définitivement",
"latitude": "N 44 52 07",
"longitude": "E 001 17 24",
"altitude": "",
"pays": "France",
"region": "Nouvelle Aquitaine",
"departement": "Dordogne",
"ville_postale": "",
"radio": "",
"nb_pistes": "1",
"nature_piste_1": "herbe",
"largeur_piste_1": "",
"longueur_piste_1": "",
"orientation_piste_1": "Inconnue",
"orientation_pref_1": "",
"nature_piste_2": "",
"largeur_piste_2": "",
"longueur_piste_2": "",
"orientation_piste_2": "",
"orientation_pref_2": "",
"classes": "",
"consignes": "",
"statut": "Usager",
"adresse_postale": "",
"code_postal": "",
"display_contact_info": "non utilisé",
"nom_contact": "",
"mail_contact": "",
"adresse_contact": "",
"tel_contact_1": "",
"tel_contact_2": "",
"facilities": "",
"carburant": "",
"infos": "piste possible sur google earth !?!",
"site_web": "",
"gestionnaire": ""
"paysid": "1",
"regionid": "4",
"departementid": "52"
},
{
"id": "7470",

etc....

}

}

Remarque : les 3 dernières lignes de la réponse (paysid, regionid et departementid) ont été ajoutées avec la version 1.3. Elles correspondent aux clefs uniques qui codent respectivement les pays, les régions et les départements. Les valeurs de ces champs sont des entiers positifs.

Ces index sont internes. Il ne correspondent pas aux numéros de départements, codes pays ou région tels que définis par les organismes publics.

 

 Exemple de programme (php)

Exemple de programme pouvant être installé sur un serveur et exécuté pour tester l'API. La clef factice doit être remplacée par celle qui vous a été attribuée.

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
CURLOPT_URL => "https://basulm.ffplum.fr/getbasulm/get/basulm/about",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_USERAGENT => "Mozilla/5.0 (Windows NT 6.1; rv:19.0) Gecko/20100101 Firefox/19.0",
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => array(
"authorization: api_key ABCDEF1982333SDF",
"cache-control: no-cache"
),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}

 Liste des codes d'erreur possible

REQ_ANS	Action not specified
HWD_GEN	Generic BASULM error
BLM_PLG	API plugin Misconfigured
BLM_DAT	Supplied date is wrong (yyyy-mm-dd)
BLM_WID	id should be integer greater than 1
BLM_IID	Supplied id does not exist
BLM_CTS	Supplied Code_terrain is too short (> 2)
BLM_CTL	Supplied Code_terrain is too long (<10)
BLM_UKN	Supplied Code_terrain is unknown