[APIDAE] Évolution modèle de données APIDAE pour les distinctions

[bruhnild]

Contexte

APIDAE a annoncé une évolution majeure de son modèle d’APIDAE prévue pour novembre 2025 :
l’introduction d’un nouveau tableau distinctions, regroupant les labels, marques, certifications et autres distinctions touristiques.

• Annonce officielle
• Documentation technique

Une rétrocompatibilité sera assurée jusqu’en novembre 2026, mais sans adaptation, les passerelles APIDAE ↔ Geotrek-admin cesseront de fonctionner à cette échéance.

L’objectif de ce ticket est de documenter l’existant, décrire les changements induits, et anticiper les adaptations nécessaires dans Geotrek-admin.

Fonctionnement actuel dans Geotrek-admin

Aujourd’hui, les parsers APIDAE (notamment ApidaeTrekParser) s’appuient sur des champs historiques de l’API APIDAE pour :

• récupérer les labels et thèmes,
• filtrer ces informations via des IDs Sitra connus,
• les mapper vers des champs Geotrek (thèmes, labels).

Ces données sont actuellement exploitées via :

• des champs dédiés (ex. typologyPromoSitra),
• des filtres spécifiques,
• des listes d’IDs codées en dur dans les parsers.

Évolution du modèle APIDAE

Centralisation des données dans distinctions

Les champs précédemment dispersés sont désormais regroupés dans un tableau unique distinctions.

Techniquement, l’adaptation est relativement simple : il faut aller lire les données dans distinctions au lieu des anciens champs.

En revanche, les distinctions ne sont plus différenciées par leur ancien emplacement.
Il devient donc plus difficile de :

• distinguer un label d’une autre distinction,
• filtrer finement les informations souhaitées.

Cela peut entraîner la remontée de données non désirées, sans possibilité de filtrage aussi précise qu’auparavant.

Changement des IDs (labels / thèmes)

Les IDs utilisés historiquement dans Geotrek-admin ne sont plus valides.

APIDAE fournit un fichier de correspondances mais à ce stade aucune correspondance directe n’existe pour les IDs actuellement utilisés dans Geotrek-admin, ce qui impose :

• une recherche manuelle des correspondances,
• une mise à jour explicite des IDs dans les parsers et leurs filtres.

Données partiellement renseignées

Les objets distinctions peuvent être incomplets :

• certains champs sont facultatifs (ex. qualification),
• l’API ne renvoie pas les champs non renseignés.

Les parsers doivent donc être robustes aux champs absents.

Parsers impactés

Geotrek-admin

Parser	Champs	Filtres	Fonctions	Variables
ApidaeTrekParser	Themes Labels	filter_themes filter_labels	—	typologies_sitra_ids_as_themes typologies_sitra_ids_as_labels

IDs actuellement utilisés et correspondances identifiées

Labels

Ancien ID	Libellé	Nouvel ID (distinctions)
1582	Label VTT - FFC	8674
4971	Inscrit au PDIPR	8607
5022	Respirando	8644
5538	Label VTT - FFCT	8675
6049	Label Vélo et Fromages	8673
6566	Label Espace Cyclosport	8671
6825	Station de Trail®	8690

Autres IDs historiquement présents mais sans correspondance identifiée à ce stade :

• 1599 (Déconseillé par mauvais temps)
• 1676 (En plein air)
• 4639 (Conseillé par forte chaleur)
• 4819 (Paysages)
• 3845 (Itinéraire France Vélo)
• 6608 (Site sur-fréquenté)
• 1602 (Circuits de France)

Thèmes

• Aucune correspondance identifiée à ce jour.

Évolutions techniques à prévoir

• Remplacer typologyPromoSitra par distinctions dans m2m_fields du ApidaeTrekParser
• Mettre à jour les IDs utilisés (labels / thèmes)
• Adapter les filtres associés
• Rendre les parsers tolérants aux champs facultatifs
• Mettre à jour les tests unitaires