Liens entre objets touristiques - Le site pour les développeurs Apidae

Plusieurs champs permettent aux utilisateurs de la base Apidae de lier leurs objets touristiques entre eux. Lier plusieurs événements d’un festival, des activités avec un prestataire, des objets sur un territoire (géographique ou thématique). Toutes ces informations sont disponibles.
Et n’oubliez pas que vous pouvez aussi utiliser les recherches (géographique géolocalisée, par commune, par critères) pour proposer une navigation aisée et pertinente entre les objets touristiques.

Formats utilisés

Les liens vers les objets touristiques font l’objet d’un traitement particulier. De manière à contrôler la taille des flux, les informations relatives aux objets liés présentes à l’intérieur d’un objet touristique sont présentées dans un format particulier qui diffère selon le mode d’exploitation (API ou exports).

Ce paragraphe détaille les informations directement accessibles dans les flux.

Un format condensé pour contrôler la taille du flux

Le format des objets liés est modifié et simplifié par rapport au format complet.

La liste des champs fournis est la suivante : id, nom, identifier, state, adresse, geolocalisation. Les champs adresse et geolocalisation correspond respectivement aux champs localisation.adresse et localisation.geolocalisation de l’objet complet.

Si des informations vous font défaut, réalisez d’autres requêtes avec les identifiants fournis pour récupérer l’ensemble des informations nécessaires.

{
        "type" : "COMMERCE_ET_SERVICE",
        "id" : 172424,
        "nom" : {
          "libelleFr" : "Club des PIOU PIOU"
        },
        "identifier" : "sitraCOS706268",
        "adresse" : {
          "adresse1" : "Au Chinaillon ou au sommet de la télécabine du Rosay",
          "adresse3" : "Domaine skiable alpin",
          "codePostal" : "74450",
          "commune" : {
            "id" : 30713,
            "code" : "74136",
            "nom" : "Le Grand-Bornand",
            "pays" : {
              "elementReferenceType" : "Pays",
              "id" : 532,
              "libelleFr" : "France",
              "ordre" : 78
            },
            "codePostal" : "74450"
          }
        },
        "geolocalisation" : {
          "altitude" : 1366,
          "complement" : {
            "libelleFr" : "Au sommet de la télécabine du Rosay.\nA l'Espace Débutant des Gettiers au Chinaillon"
          },
          "valide" : true,
          "geoJson" : {
            "type" : "Point",
            "coordinates" : [ 6.450573, 45.949113 ]
          }
        }
      }

Seul le type et l’identifiant

Les objets liés (entiers) font partis du contenu de l’export. Utilisez les couples identifiant / type pour récupérer les informations des objets liés.

{
        "type" : "COMMERCE_ET_SERVICE",
        "id" : 172424
}

Prestataire d’activité

Le champ informationsActivite.prestataireActivites est un champ spécifique aux objets de type ACTIVITE. C’est un champ qui permet d’identifier le prestataire associé à une activité. Cela peut par exemple permettre de réaliser des listes de prestataires d’activité, ou sur une fiche activité d’identifier les activités proposées par le même prestataire.

N’importe quel type objet (à l’exception de STRUCTURE ou ACTIVITE ou SEJOUR_PACKAGE ou FETE_ET_MANIFESTATION ou PATRIMOINE_NATUREL) peut être prestataire d’activité. Par exemple, le prestataire associé à un Cours de cuisine peut être un objet RESTAURATION ou DEGUSTATION. Si l’objet pointé par le champ informationsActivite.prestataireActivites possède un aspect PRESTATAIRE_ACTIVITES et qu’on cherche à réaliser une promotion des activités, il faut favoriser l’utilisation de cet aspect.

> Documentation sur les aspects

Liste de prestations

Depuis Avril 2022

Le champ prestationsList est un champ spécifique aux prestataires d’activités. Il permet de lister les activités organisées par le prestataire concerné. Il permet notamment d’établir des listes d’activités pour un prestataire.

"prestationsList" : [ {
    "type" : "ACTIVITE",
    "id" : 88886,
    "nom" : {
      "libelleFr" : "Initiation à l'escalade aux bords de la Dranse",
    },
    "identifier" : "74TBACT100016",
    "state" : "PUBLISHED",
    "adresse" : {
      "adresse1" : "Base de Loisirs de Bioge",
      "adresse2" : "RD 902",
      "codePostal" : "74200",
      "commune" : {
        "id" : 30862,
        "code" : "74295",
        "nom" : "La Vernaz",
        "pays" : {
          "elementReferenceType" : "Pays",
          "id" : 532,
          "libelleFr" : "France",
          "libelleEn" : "France",
          "libelleDe" : "FRANKREICH",
          "ordre" : 78
        },
        "codePostal" : "74200"
      }
    },
    "geolocalisation" : {
      "altitude" : 546,
      "valide" : true,
      "geoJson" : {
        "type" : "Point",
        "coordinates" : [ 6.587741, 46.324453 ]
      }
    }
  }]

Objets liés

Les types de liens sont les suivants (et sont amenés à évoluer, veillez à prévoir un traitement pour les types de liens que vous ne connaissez pas) :

Vous trouverez également une description plus précise de leur utilisation sur le site d’aide d’Apidae :
https://aide.apidae-tourisme.com/hc/fr/articles/360000806492-Saisie-l-onglet-Objets-li%C3%A9s#nature_liens_exemples

DEFAUT : Nature de lien non précisé (En lien avec…)
SUR_PLACE : sur place, indique une réelle proximité entre les objets (pour des objets juste proche l’un de l’autre, la recherche géographique suffit)
ADRESSE_UTILE (non bidirectionnel automatique) : adresse utile, par exemple un loueur de matériel pour un parcours de via-ferrata
ORGANISATEUR_PROGRAMME : l’objet touristique qui possède le lien est l’organisateur
exemple un festival -> liensObjetsTouristiquesTypes type = ORGANISATEUR_PROGRAMME -> un événement
PROGRAMME_ORGANISATEUR : la réciproque du lien précédent
événement -> liensObjetsTouristiquesTypes type = PROGRAMME_ORGANISATEUR -> le festival
CADRE_OFFRE_SPECIALE : lien vers un objet qui propose une offre spéciale liée à l’objet qui porte le lien
OFFRE_SPECIALE_CADRE : la réciproque ; lien vers une offre pour lequel l’objet qui porte le lien propose une offre spéciale
PACKAGE_OBJET : lien vers une offre qui fait parti du package proposé par l’objet qui porte le lien
OBJET_PACKAGE : lien réciproque ; lien d’un item d’un package vers le package correspondant
AU_DEPART_DE (non bidirectionnel automatique) : l’objet se situe au départ de l’objet lié
A_L_ARRIVEE_DE (non bidirectionnel automatique) : l’objet se situe à l’arrivée de l’objet lié
SUR_LE_PARCOURS_DE (non bidirectionnel automatique) : l’objet se situe sur le parcours de l’objet lié
PARCOURS_ETAPE : l’objet lié est une étape de l’objet qui porte le lien
ETAPE_PARCOURS : l’objet lié est le parcours correspondant à l’étape qui porte le lien
COUPS_DE_COEUR_INCONTOURNABLES : lien vers un objet qui est un coup de cœur incontournable lié à l’objet qui porte le lien
VEND_ICI : Vend ses produits ici, réciproque de PROPOSE_PRODUIT_DE
PROPOSE_PRODUIT_DE : Propose les produits de…, réciproque de VEND_ICI
PERMET_ACCEDER_A : Permet d’accéder à…, réciproque de EST_ACCESSIBLE_PAR
EST_ACCESSIBLE_PAR : Est accessible/desservi(e) par…, réciproque de PERMET_ACCEDER_A
EST_SITUE_DANS : Est situé(e) dans…, réciproque de A_DANS_SON_PERIMETRE
A_DANS_SON_PERIMETRE : A dans son périmètre…, réciproque de EST_SITUE_DANS
OFFRE_SIMILAIRE_PROXIMITE : Est une offre similaire à proximité de…, réciproque avec la même nature de lien : permet de proposer une offre équivalente à proximité, si l’offre en cours de consultation est fermée par exemple
SUGGESTION_A_PROXIMITE (non bidirectionnel automatique) : Suggestion à proximité… : pas de réciproque

Concernant les liens dont le sens est important, de manière générale, le terme à gauche s’applique à l’objet qui porte le lien. Exemple festival -> liensObjetTouristiquesTypes -> ORGANISATEUR_PROGRAMME -> pièce de théâtre. L’organisateur est le festival ; la pièce de théâtre fait partie du programme.

Tous les liens, exceptés ceux notés « non bidirectionnel automatique », sont mis à jour de manière automatique des deux côtés de la relation lors de la mise à jour de la fiche (par exemple, si un lien SUR_PLACE est ajouté à un objet, alors le lien contraposé sera mis en place sur l’objet lié).

Le choix du type est libre lors de la saisie, et tous les types ne possèdent pas le même intérêt ; nous vous conseillons donc de vous rapprocher de votre client pour vérifier quels sont les types de relation qui les intéressent et les modalités d’affichage qu’il désire mettre en place.

Cette liste est ordonnable lors de la saisie. Sur Apidae, vous pouvez visualiser ces relations sur la fiche objet touristique (onglet Multimédias et suggestions) dans un mode simple (listing pur avec un ordre conforme à la saisie – pas de regroupement).

API

{
    "liensObjetsTouristiquesTypes" : [ {
      "type" : "SUR_PLACE",
      "objetTouristique" : {
        "type" : "RESTAURATION",
        "id" : 138443,
        "nom" : {
          "libelleFr" : "Estrade"
        },
        "identifier" : "sitraRES535584",
        "state" : "PUBLISHED",
        "adresse" : {
          "adresse1" : "1 avenue de Marlioz",
          "codePostal" : "73100",
          "commune" : {
            "id" : 30248,
            "code" : "73008",
            "nom" : "Aix-les-Bains",
            "pays" : {
              "elementReferenceType" : "Pays",
              "id" : 532,
              "libelleFr" : "France",
              "ordre" : 78
            },
            "codePostal" : "73100"
          }
        },
        "geolocalisation" : {
          "reperePlan" : "I5",
          "complement" : {
            "libelleFr" : "à proximité Centre des Congrès"
          },
          "valide" : true,
          "geoJson" : {
            "type" : "Point",
            "coordinates" : [ 5.913488, 45.685954 ]
          }
        }
      }
    }, {
      "type" : "ADRESSE_UTILE",
      "objetTouristique" : {
        "type" : "PATRIMOINE_CULTUREL",
        "id" : 274951,
        "nom" : {
          "libelleFr" : "Parc des thermes"
        },
        "identifier" : "sitraPCU859226",
        "state" : "PUBLISHED",
        "adresse" : {
          "codePostal" : "73100",
          "commune" : {
            "id" : 30248,
            "code" : "73008",
            "nom" : "Aix-les-Bains",
            "pays" : {
              "elementReferenceType" : "Pays",
              "id" : 532,
              "libelleFr" : "France",
              "ordre" : 78
            },
            "codePostal" : "73100"
          }
        },
        "geolocalisation" : {
          "valide" : true,
          "geoJson" : {
            "type" : "Point",
            "coordinates" : [ 5.915022, 45.686816 ]
          }
        }
      }
    } ]
  }

Exports

{
    "liensObjetsTouristiquesTypes" : [ {
      "type" : "SUR_PLACE",
      "objetTouristique" : {
        "type" : "RESTAURATION",
        "id" : 138443
      }
    }, {
      "type" : "ADRESSE_UTILE",
      "objetTouristique" : {
        "type" : "PATRIMOINE_CULTUREL",
        "id" : 274951
      }
    }

Les territoires

Le champ territoires liste l’ensemble des territoires concernés par l’objet. Ces territoires sont soit décernés de manière automatique en fonction du périmètre géographique de l’objet et des territoires de la base (une commune en commun = territoire affecté à l’objet), soit attribués de manière manuelle à la saisie par les utilisateurs

Le nombre d’éléments à afficher dans le champ territoires étant élevé, un format plus compact est exploité. Dans les flux API, seuls les champs id, nom, type, identifier et state sont inclus dans le flux. Il est possible de faire des requêtes supplémentaires avec les identifiants pour obtenir l’intégralité des informations

De manière générale, l’intérêt des territoires variant en fonction de la communication adoptée, cette information ne doit pas être utilisée de manière brute. Il peut par exemple être nécessaire de déterminer avec votre client son intérêt vis à vis des territoires (recherche seulement, affichage, navigation), et déterminer une liste des territoires à mettre en valeur.