API Apidae : projet, clé, sélections et consentement, pour un site WordPress

Apidae Tourisme met ses fiches à disposition des sites web par une API. Pour s’en servir, il faut un projet, une clé et des sélections, et parfois l’accord du propriétaire des données : c’est le rôle de l’API de consentement. Voici comment ces pièces s’emboîtent, et comment un site WordPress les exploite.

Qu’est-ce que l’API Apidae ?

Apidae est une base de données d’informations touristiques alimentée par les offices de tourisme et les territoires. Chaque fiche (un hôtel, un restaurant, une randonnée, un événement) y est appelée un objet touristique. La base s’ouvre aux sites web et aux applications de deux façons : par ses API, interrogées à la demande, et par des exports, une archive de fichiers JSON envoyée chaque jour.

L’API répond en JSON. Elle permet notamment de :

• lire une fiche à partir de son identifiant ;
• lister les objets d’une sélection, ou seulement leurs identifiants ;
• interroger l’agenda des événements, en version simple ou détaillée.

Les fiches arrivent avec leurs descriptifs, photos, horaires, tarifs et, selon les cas, jusqu’à neuf langues. La documentation technique officielle est publiée sur dev.apidae-tourisme.com.

Les quatre notions à connaître avant de se connecter

Le projet

Tout accès passe par un projet, créé dans l’espace Apidae (base.apidae-tourisme.com). Le projet décrit qui diffuse quoi, et comment. Un site web correspond en général à un projet.

L’identifiant et la clé API

Dans l’onglet Informations générales du projet se trouvent son identifiant et sa clé API. Ce sont les deux valeurs qu’un site ou une extension utilise pour s’authentifier. La clé se garde comme un mot de passe : elle n’a rien à faire dans le code source public ni dans une capture d’écran.

Les sélections

Une sélection regroupe les objets que le projet diffuse : les hébergements de la commune, les manifestations du mois, les itinéraires à vélo. On la définit dans Apidae avec des critères, puis Apidae la calcule. Le site ne récupère que cette sélection. Une sélection qui vient d’être créée doit avoir été calculée pour remonter.

La configuration technique

L’onglet Configuration technique du projet règle le mode de diffusion : technologie utilisée (API), fréquence de génération, format (JSON), version du format de sortie (V2), export des dates d’ouverture. C’est aussi là que s’active le temps réel.

Le temps réel : être prévenu quand une fiche change

Sans temps réel, le site interroge Apidae à intervalle fixe pour savoir ce qui a bougé. Avec le temps réel, c’est Apidae qui envoie un message à une adresse du site (un webhook) dès qu’un événement se produit dans le projet. Six messages existent :

• une fiche est modifiée ;
• une fiche est supprimée ;
• une ou plusieurs fiches sont ajoutées à une sélection ;
• une ou plusieurs fiches sont retirées d’une sélection ;
• une sélection est ajoutée au projet ;
• une sélection est supprimée du projet.

Le site ne recharge alors que ce qui a changé, et les appels inutiles vers la base disparaissent.

Ce que demande une intégration sur mesure

Interroger l’API soi-même suppose de savoir écrire des requêtes HTTP et lire des réponses JSON volumineuses. Sur un site, il faut ensuite tout le reste : stocker les fiches, copier les photos, gérer les langues, recalculer les dates d’ouverture, supprimer ce qui disparaît d’Apidae, et ne pas tout effacer le jour où l’API répond mal. C’est faisable, mais c’est un développement à maintenir dans la durée.

L’API de consentement : diffuser les données d’un autre propriétaire

L’API classique sert les données auxquelles votre projet a accès. L’API de consentement répond à un autre cas : récupérer un flux de données dont vous n’êtes pas propriétaire, avec son accord. Le propriétaire des données compose un flux, le demandeur choisit ce dont il a besoin, et le propriétaire valide ou non les conditions d’accès.

En pratique, l’accès se fait en trois temps :

1. La demande : le développeur ou le propriétaire du site sollicite l’accès au flux auprès du propriétaire des données.
2. La configuration du flux : le demandeur sélectionne les informations utiles, le propriétaire accepte ou refuse les conditions.
3. L’import : une fois l’accord donné, le flux se récupère avec les identifiants délivrés pour ce flux.

Attention : l’API de consentement est servie par une plateforme distincte (api.plateforme.apidae-tourisme.com), avec ses propres points d’accès. Un identifiant de projet Apidae classique y est refusé. Avant de configurer un site, vérifiez donc dans quel cas vous êtes : projet classique ou flux obtenu par consentement.

L’API Apidae sur WordPress avec WP-Apidae

WP-Apidae est une extension WordPress qui fait ce travail d’intégration. Elle prend en charge l’API classique comme l’API de consentement. Nous avons échangé avec les équipes d’Apidae Tourisme et participé à leurs ateliers pendant son développement.

La mise en route suit les notions vues plus haut :

• Connexion : dans les réglages de WP-Apidae, renseignez l’identifiant et la clé API du projet. Pour un flux obtenu par consentement, cochez la case « Consentement API » lors de cette première configuration.
• Sélections : l’extension lit la liste des sélections du projet. Vous choisissez celles à importer, un clic lance l’import.
• Import : il tourne en arrière-plan, même sur de gros volumes. Les photos et documents sont copiés dans la médiathèque, et les fiches sont rangées par type d’objet (quatorze types pris en charge).
• Mise à jour : une synchronisation planifiée reprend les modifications (toutes les 2 heures par défaut, réglable jusqu’à 24 heures). Pour le temps réel, WP-Apidae fournit l’adresse du webhook à coller dans la configuration technique du projet Apidae.
• Affichage : des blocs Listing, Carte, Filtres et Fiche se posent dans les pages depuis l’éditeur, sans code. Des modules ajoutent Elementor, Divi ou le multilingue avec Polylang.

Retour d’expérience : toutle04.fr et toutle05.fr

L’agence Origami édite toutle04.fr et toutle05.fr, deux sites qui publient les données des offices de tourisme des Alpes-de-Haute-Provence et des Hautes-Alpes. Elle a confié à WP-Apidae l’import de ces flux.

Utilisant Apidae depuis plusieurs années pour nos sites toutle04.fr et toutle05.fr nous avions mis en place un système semi-automatique basé sur des traitements de fichiers qui étaient longs, fastidieux et malheureusement non exhaustifs. […] Aujourd’hui nous avons un flux APIDAE automatisé tous les jours pour nos 2 sites avec l’assurance d’avoir la totalité des informations sur les événements que nous désirons publier. […] Notre concept de site (annuaire d’entreprises, agenda d’événements, répertoire de sites touristiques) nous permet aujourd’hui de proposer en permanence sur chaque site plus de 2 000 dates d’événements.

Philippe Ronzevalle, Origami

Voir l’API Apidae à l’œuvre sur un site

Le site de démonstration publie de vraies fiches Apidae avec WP-Apidae et ses modules. Pour un tour guidé sur votre propre projet, en API classique ou en consentement, demandez une démo : nous la préparons avec le constructeur de pages que vous utilisez.