Format des recherches - Le site pour les développeurs Apidae

Cette page décrit le format des recherches pour les services Apidae. Ce format est unique, mais en fonction du service utilisé, la signification de certains paramètres peut varier.

Remarques à portée générale

Format général de la requête

La requête est un objet structuré à sérialiser en JSON.
Une fois sérialisée, la requête a le format suivant (tous les champs ne sont pas représentés) :

{
  "apiKey": "test",
  "projetId": 132,
  "searchQuery": "festival",
  "searchFields": "NOM_DESCRIPTION",
  "selectionIds": [12346, 12347],
  "count": 20,
  "first": 0,
  "order": "PERTINENCE",
  "asc": false
}

Cet exemple de recherche effectue une recherche textuelle sur les champs de description des objets avec le terme « festival » au sein des sélections 12346 et 12347. Le résultat est limité à 20 résultats à partir du premier objet, trié par pertinence décroissante.

Cette requête est à passer avec le nom de paramètre « query » (GET ou POST).

Exemples

http://api.apidae-tourisme.com/api/v002/recherche/list-objets-touristiques?query={"projetId":"xxx","apiKey":"xxxxxx","criteresQuery":"type:RESTAURATION"}

Utiliser un navigateur avec des requêtes construites à la main fonctionne de manière générale. Toutefois, il faut veiller à utiliser des outils dédiés à l’échappement des paramètres et à la sérialisation JSON fournis par votre langage pour éviter tout dysfonctionnement.

Une collection Postman est disponible afin de vous aider à mieux appréhender ce type de constructions.

Associativité des contraintes de la requête

De manière générale, si aucune précision n’est apportée, les critères de recherche s’accumulent et sont liés par une condition logique ET.
Attention, certains critères de recherche peuvent se recouper :

Lorsque les champs identifiants et identifiers sont tous les deux remplis, on applique un opérateur logique OU entre les identifiants des deux listes :

identifiants OU identifiers

Il n’est pas possible de combiner les champs listeEnregistreIds et selectionIds
Quand le champ listeEnregistreeId désigne une sélection d’objets touristiques, on ne garde que les identifiants en commun avec les listes d’identifiants. On utilise l’opérateur logique ET :

(identifiants OU identifiers) ET (*liste d'identifiants remontés par listeEnregistreeId*)

Quand le champ selectionIds est rempli, on effectue un ET logique entre les listes d’identifiants et les sélections :

(identifiants OU identifiers) ET (*liste d'identifiants remontés par selectionIds*)

Lorsque les champs communeCodesInsee et territoireIds sont tous les deux remplis, on applique un opérateur logique OU entre les deux listes.

Requête avec des dates (dateDebut, dateFin)

Les dates de début et date de fin de la requête permettent de trouver des objets déclarés ouverts au moins une date entre la date de début et la date de fin. Les ouvertures des objets sont calculées de manière périodique et sur une période glissante de 700 jours.
La date de début doit être postérieure ou égale à la date du jour.
La date de debut et la date de fin doivent être inférieure à aujourd’hui + 700 jours.
Au délà de 700 jours, les résultats ne seront plus cohérents.

Il n’est pas possible d’obtenir des résultats pour les jours passés ou au delà de 700 jours.

Format de la réponse

Attention, pour des raisons de performance et de taille de la réponse, la réponse est filtrée et ne contient pas tous les champs et toutes les langues stockés dans Apidae.

En fonction de vos besoins, il faut utiliser les champs de requête responseFields et locales pour affiner les données présentes dans le résultat.

Liste des attributs de la requête

apiKey

Clé d’API
Type : chaîne de caractères
Où trouver l’information : interface de gestion du projet ou service de consentement
Exemple de projet de consultation

"apiKey" : "s34WSq8"

Exemple du service de consentement

"apiKey" : "f399cf0b-c557-6609-be75-1337d388a404"

projetId

Identifiant du projet
Type : entier ou chaîne de caractères selon le type de projet
Où trouver l’information : interface de gestion du projet ou service de consentement
Exemple de projet de consultation

"projetId" : 123

Exemple du service de consentement

"projetId" : "9fd02c13-42e7-534f-955g-4333d3071c80"

identifiants

Les identifiants des objets à retourner. Ignoré si la liste est nulle ou vide.
Type : liste d’entiers
Où trouver l’information : disponible dans les objets touristiques ou dans les urls de l’interface web.
Exemple :

"identifiants":[ 14330, 14331 ]

identifiers

Les identifiers des objets à retourner. Ignoré si la liste est nulle ou vide.
Type : liste de chaînes de caractères
Où trouver l’information : disponible sur l’interface de sérialisation des objets dans les outils développeurs.
Paramètre non disponible dans le service de consentement
Exemple :

"identifiers":[ "sitraSTR382168″, "sitraEVE778494″ ]

La présence conjointe d’identifiants et d’identifiers est un héritage historique. Il est conseillé de favoriser les identifiants.

listeEnregistreeId (deprecated)

L’utilisation des listeEnregistreeId a été introduit pour faciliter la migration depuis la version précédente de Apidae. Merci d’utiliser des sélections et des selectionIds qui vous offre une fonctionnalité semblable et permet d’assurer un meilleur suivi des recherches et objets utilisés par votre projet.

Identifiant de la liste enregistrée à récupérer. Dans le cas d’une recherche enregistrée, les critères de recherche peuvent être surchargés par les autres champs de la requête. Ignoré si la valeur est nulle.
Type : entier
Paramètre non disponible dans le service de consentement
Exemple :

"listeEnregistreeId" : 116

Attention : une liste enregistrée ne peut pas être utilisée en même temps qu’une ou plusieurs sélections.
Il n’est pas possible d’utiliser l’attribut searchQuery en même temps qu’une recherche enregistrée. Si c’est le cas, le paramètre dans la requête est ignoré.
Dans le cas d’une recherche de type Agenda, il est obligatoire d’utiliser une liste enregistrée de l’onglet Agenda, sinon le résultat est systématiquement vide.

selectionIds

Les identifiants des sélections d’objets à récupérer. Ignoré si la liste est nulle ou vide.
Type : liste d’entiers.
Où trouver l’information : dans Apidae sur la fiche du projet contenant la sélection
Paramètre non disponible dans le service de consentement
Exemple :

"selectionIds":[ 15, 308, 176 ]

searchId

Paramètre propre au service de consentement.
Les identifiants des recherches d’objets à récupérer.
Type : chaîne de caractères.
Où trouver l’information : dans Apidae sur le channel du service de consentement.
Exemple :

"searchId":"4023139e-d512-4265-c0f5-20887a503g7f"

center

Dans le cas d’une recherche restreinte à une zone géographique, détermine le centre du cercle à utiliser. Ignoré si les coordonnées sont incomplètes, si la valeur est nulle ou si le champ rayon n’est pas défini. Ce critère utilise le format GeoJSON de définition d’un point.
Type : coordonnées géographiques (longitude, latitude)
Exemple :

"center":{"type":"Point","coordinates":[4.833,45.767]}

radius

Dans le cas d’une recherche restreinte à une zone géographique, détermine le rayon du cercle à utiliser. Cette valeur est exprimée en mètres (m.). Ignoré si la valeur est nulle ou si le champ centre n’est pas défini.
Type : entier.
Exemple :

"radius" : 3000

La distance d’un objet par rapport au point de référence n’est pas exposée dans les API.

communeCodesInsee

Codes INSEE des communes sur lesquels se trouvent les objets à retourner. Si plusieurs communes sont spécifiées, on applique un opérateur OU entre elles. Les communes spécifiées s’ajoutent aux territoireIds, si ce champs est rempli. Si un code INSEE désigne Lyon, Marseille ou Paris, on ajoute automatiquement les arrondissements de ces villes dans la requête. Ignoré si la liste est nulle ou vide.
Type : liste de chaînes de caractères.
où trouver l’information : www.insee.fr/fr/methodes/nomenclatures/cog/ ; interfaces Apidae.
Exemple :

"communeCodesInsee":[ "69275", "69388" ]

La base Apidae exploite des communes « fictives » (en particulier pour les stations de ski) ou des communes étrangères. Ces communes peuvent être exploitées via le même champ car il leur a été attribué un code fictif. Vous pouvez obtenir ces codes en consultant le référentiel des communes

territoireIds

Identifiant des territoires sur lesquels se trouvent les objets à retourner. Si plusieurs territoires sont spécifiés, on applique un opérateur OU entre eux. Les territoires spécifiées s’ajoutent aux communeCodesInsee, si ce champs est rempli. Ignoré si la liste est nulle ou vide.
Type : liste d’entiers.
Où trouver l’information : consultation du référentiel.
Exemple :

"territoireIds":[ 95938, 156922 ]

searchQuery

Liste de termes (séparés par des espaces) pour une recherche plein texte. Ignoré si la valeur est nulle. Pour contrôler sur quels champs porte la recherche, voir l’attribut searchFields.
Type : chaîne de caractères.
Exemple :

"searchQuery":"festival jazz"

searchFields

Définit quels champs des objets touristiques sont ciblés par la recherche plein texte.
Type : chaîne de caractères. valeurs possibles :

NOM pour une recherche sur le nom des objets,
NOM_DESCRIPTION pour une recherche sur le nom et les descriptions des objets,
NOM_DESCRIPTION_CRITERES pour une recherche sur le nom, les descriptions et les critères associés aux objets.

Valeur par défaut : NOM_DESCRIPTION_CRITERES.
Exemple :

"searchFields" : "NOM_DESCRIPTION"

criteresQuery

Requête Lucene pour filter les objets touristiques par les éléments de référence, les critères internes et le type. Ignoré si la valeur est nulle. Une requête syntaxiquement incorrecte renverra une erreur.
Type : chaîne de caractère.
Syntaxe : La requête doit cibler l’un des trois champs :

critere (pour les éléments de référence),
critereInterne (pour les critères internes)
type (pour les types d’objets touristiques).

Un terme de la requête est composé d’un nom de champs puis de sa valeur séparé par « : ».
Pour les éléments de référence, la valeur doit être composée du nom de l’élément de référence suivi d’un _ puis de l’identifiant de l’élément de référence : _. Par exemple Environnement_147

Tous les critères ne sont pas accessibles pour ces recherches. Il faut vous assurer que le critère possède la colonne Indexé cochée dans l’interface de consultation des éléments de référence

criteresQuery

critere (pour les éléments de référence),
critereInterne (pour les critères internes)
type (pour les types d’objets touristiques).

Pour les critères internes, la valeur doit être composée comme suit : CritereInterne_. Les identifiants de critères internes sont disponibles sur l’interface des outils développeurs après s’être authentifié.

Pour les types d’objets touristique, la valeur doit être l’un des types listés sur cette page. Il est possible de combiner les termes de la requête avec les opérateurs + et – (voir exemples suivants).
Il est possible de contrôler l’application des opérateurs précédents à l’aide de parenthèses.
Attention : les API ne corrigeront pas les requêtes approximatives, toute requête syntaxiquement incorrecte déclenchera une erreur.

Disponibilité des informations : interface de consultation des éléments de référence, interface de consultation des critères internes.

Exemples : La requête suivante renvoie tous les Equipements :

"criteresQuery":"type:EQUIPEMENT"

Les objets retournés par la requête suivante sont soit des Equipements, soit des objets avec le critère EquipementActivite qui porte l’identifiant 3045 :

"criteresQuery":"critere:EquipementActivite_3045 type:EQUIPEMENT"

Les objets retournés par la requête suivante ont le critère EquipementActivite_3045 et ne sont pas des Equipements :

"criteresQuery":"critere:EquipementActivite_3045 -type:EQUIPEMENT"

Les objets retournés par la requête suivante sont soit des Activités qui n’ont pas le critère EquipementActivite_3045, soit des Equipements :

"criteresQuery":"(+type:ACTIVITE -critere:EquipementActivite_3045) type:EQUIPEMENT"

Les objets retournés par la requête suivante sont les Equipements qui n’ont ni le critère EquipementActivite_3045, ni le critère EquipementActivite_3094 :

"criteresQuery":"+type:EQUIPEMENT -(critere:EquipementActivite_3045 critere:EquipementActivite_3094)"

Les objets possédant le critère interne 2247 :

"criteresQuery":"critereInterne:CritereInterne_2247″

Recherche d’objets non payants (gratuits + tarifs non renseignés) :

"criteresQuery":"-(gratuit:false)"

dateDebut

Date de début de période qui est comparée à la date d’ouverture des objets touristiques. La date de début est incluse dans l’intervalle de recherche. Pour effectuer une recherche sur une journée précise, il suffit de saisir la même valeur pour la date de début et la date de fin. Ignoré si la valeur est nulle.
Type : date au format yyyy-MM-dd.
Exemple :

"dateDebut":"2012-08-15″

dateFin

Date de fin de période qui est comparée à la date d’ouverture des objets touristiques. La date de fin est incluse dans l’intervalle de recherche. Pour effectuer une recherche sur une journée précise, il suffit de saisir la même valeur pour la date de début et la date de fin. Ignoré si la valeur est nulle.
Type : date au format yyyy-MM-dd.
Exemple :

"dateFin":"2012-09-01″

first

Index du premier élément retourné (0-based). Remplacé par 0 si la valeur est nulle ou inférieure à zéro.
Type : entier supérieur ou égal à zéro.
Exemple :

"first":10

count

Nombre maximum d’éléments retournés. Ignoré si la valeur est nulle ou inférieur à zéro. La valeur est plafonnée à 200. Si non précisé, la valeur par défaut 20 est appliquée.
Type : entier supérieur ou égal à zéro.
Exemple :

"count":20

Pour les requêtes renvoyant plus de 200 résultats, il est possible de paginer les résultats en utilisant le paramètre first en plus du paramètre count. Les résultats sont alors récupérés par ensembles de count occurrences.
Pour savoir si une requête renvoi plus de 200 résultats, il faut se baser sur le champ numFound de la réponse.

order

Critère de tri déterminant l’ordre dans lesquels les objets sont retournés.
Type : chaîne de caractères.
Valeurs possibles :

NOM pour trier sur le nom des objets.
IDENTIFIANT pour trier sur les identifiants des objets.
PERTINENCE pour trier sur la pertinence de la recherche plein texte. Ce n’est appliqué que si le champ searchQuery est rempli. Non disponible sur l’agenda.
DISTANCE pour trier sur la distance par rapport au centre de la recherche géolocalisée. Ce n’est appliqué que si les champs centre et rayon sont correctement remplis.
RANDOM pour trier les résultats de manière pseudo-aléatoire. Voir le champ randomSeed.
DATE_OUVERTURE pour trier les objets par date d’ouverture. Seuls les résultats FETE_ET_MANIFESTATION et ACTIVITE sont fournis dans le résultat. Il n’est pas possible de faire de tri descendant sur cet élément. Il faut utiliser les services /agenda/simple/* pour obtenir des résultats triés par date (sans répartition par jour)

> Documentation sur le tri par date

Valeur par défaut : PERTINENCE si le champ searchQuery est rempli et hors agenda, IDENTIFIANT sinon. Si la recherche est basée sur une liste enregistrée qui est une recherche, alors il est possible d’utiliser l’ordre de la recherche enregistrée en ne précisant pas d’ordre.
Exemple :

"order":"NOM"

asc

Définit si les objets retournés doivent être triés par ordre croissant (true) ou décroissant (false).
Type : booléen.
Valeur par défaut : ordre croissant (true).
Remarque : le tri descendant (asc = false) n’est pas possible pour le tri par date d’ouverture.
Exemple :

"asc":"false"

randomSeed

Chaîne de caractères servant de germe pour la génération d’un ordre pseudo-aléatoire. Deux germes différents donneront deux ordres aléatoires différents. Mais en utilisant plusieurs fois le même germe, on obtient toujours le même ordre. Ignoré si le champs order n’a pas pour valeur RANDOM. Si nul ou vide, un germe prédéfini par l’application Apidae est utilisé.
Type : chaîne de caractères alpha-numériques.

Si non précisé, le germe prédéfini utilisé est fixe ; de ce fait, si vous ne précisez pas ce paramètre, vous obtiendrez un ordre aléatoire mais constant (l’ordre peut toutefois être amené à varier si les résultat changent).

Exemple :

"randomSeed":"azo23i7lkh8″

locales

Liste des langues à inclure dans la recherche. Il faut indiquer uniquement le code de langue (deux lettres). Si la liste est nulle ou vide, seule la langue française est exportée.
Type : liste de chaînes de caractères.
> Documentation filtrage des langues
Exemple :

"locales":[ "fr", "en", "es", "it" ]

responseFields

Liste des champs à inclure dans le résultat.
Type : liste de chaînes de caractères
> Documentation filtrage des données
Exemple :

"responseFields":[ "id", "nom" ]

membreProprietaireIds

Identifiants des membres propriétaires des objets touristiques à retourner lors de la recherche. Si plusieurs membres sont spécifiés, on applique un opérateur OU entre eux. Ignoré si la liste est nulle ou vide.
Type : liste d’entiers.
Exemple :

"membreProprietaireIds":[80, 203]