Recherche transverse
Lister les événements récents et à venir publiés sur des agendas OpenAgenda. Cette fonction est en expérimentation. Vous souhaitez la tester? Contactez-nous en envoyant un email à support@openagenda.com
https://api.openagenda.com/v2/events?key={publicKey}
Paramètres
| Paramètre | Description |
|---|---|
| after | Optionnel. Utile pour récupérer les résultats suivants le premier jeu d'événements rendu, lorsque le total résultant des filtres actifs est supérieur au total du segment rendu. |
| detailed | Si égal a 1, rend l'intégralité des données publiques liées à chaque événement |
| longDescriptionFormat | markdown par défaut. HTML: le contenu du champ longDescription est rendu au format HTML. HTMLWithEmbeds: le contenu du champ longDescription est rendu au format HTML et tout lien pointant vers des contenus multimédias de plateformes connues (Youtube, Soundcloud, Eventbrite, Pixlr...) sera remplacé par un contenu intégré. |
| size | 20 par défaut. Nombre d'événements à récupérer. Il n'est pas possible de récupérer plus de 300 événements par appel. |
| includeLabels | Optionnel. Inclure les labels dans les champs additionnels à choix. Ex: {"categorie": 1} devient {"categorie": {"id": 1, "label": {"fr": "Spectacle"}}}. |
| includeFields | Optionnel. Ou if. Pour préciser les données à remonter pour chaque événement; utile à des fins d'optimisation de temps de réponse et de bande passante. Ex: ?includeFields[]=uid&includeFields[]=title&includeFields[]=location.city |
| monolingual | Optionnel. Préciser un code langue (fr, en, it, de) pour ne renvoyer qu'une seule langue pour les champs multilingues et les labels de champs additionnels. Si la langue choisie n'est pas définie, une langue disponible sera utilisée. |
| removed | Booléen optionnel, 0 par défaut. Exclue alors les références d'événements retirés de l'agenda. Utile pour établir un delta lors d'une synchronisation. null pour les inclure dans le flux, 1 pour ne faire remonter que les références retirées. Seuls l'identifiant et le moment du retrait sont fournis pour les références d'événements retirées (uid, updatedAt) |
Résultat
Le résultat d'une requête est un JSON contenant les clés suivantes:
- total: Total des événements correspondants au à la requête demandée
- events: Segment d'événements résultants de la requête demandée.
- sort: Tri effectif.
- after: A utiliser sur une clé de requête after pour récupérer le segment d'événements suivant
Détail fourni pour chaque événement
Par défaut, seuls les champs standards suivants sont fournis pour chaque événement: title, dateRange, keywords, location, image, originAgenda, description, slug, lastTiming, nextTiming.
L'intégralité des champs publiques n'est incluse que si la valeur detailed est précisée: ?detailed=1
Dans la mesure du possible, utilisez `includeFields` pour expliciter les champs désirés et éviter un transfert de données qui ne seront pas utilisées.
Le détail de chaque champ est donné dans la section traitant de la structure d'un événement OpenAgenda
Filtres
Filtres standards
| Clé | Description | Exemple |
|---|---|---|
| originAgenda.official | Ne lister que les événements provenant d'agendas officiels | ?originAgenda.official=1 |
| city | Filtrer par ville | ?city[]=Lausanne&city[]=Genève |
| department | par Département | ?department[]=Hauts-de-Seine |
| region | par Région | ?region=Normandie |
| timings[gte] | filtrer par horaire supérieur à | ?timings[gte]=2021-...:00:00.000Z |
| timings[lte] | filtre par horaire inférieur à | ?timings[lte]=2021-02-18T...00Z |
| updatedAt[gte] | mis à jour après le | ?updatedAt[gte]=2021-02-1...:00.000Z |
| updatedAt[lte] | mis à jour avant le | ?updatedAt[lte]=2021-02-...00.000Z |
| search | Recherche synthaxique | ?search=Concert |
| uid | Filtre par identifiant | ?uid[]=56158955&uid[]=55895615 |
| slug | Filtre par code url | ?slug=festival-dete |
| relative | Passé / En cours / A venir | ?relative[]=passed (événements passés), ?relative[]=upcoming (événements à venir), ?relative[]=current (événements en cours: avec plages horaires passées ET à venir) |
| keyword | Mots clés | ?keyword[]=gratuit&keyword[]=exposition fonction en ET logique |
| geo | Filtrer sur un carré géographique | ?geo[northEast][lat]=48.9527&geo[northEast][lng]=2.4484&geo[southWest][lat]=48.8560&geo[southWest][lng]=2.1801 |
| locationUid | Filtre par identifiant de lieu | ?locationUid[]=123&locationUid[]=456 |
| accessibility | filtrer par accessibilité particulière | ?accessibility[]=hi&accessibility[]=vi (Voir toutes les valeurs possibles ici) |
| status | filtrer par état | ?status[]=1 (Voir toutes les valeurs possibles ici) |
Tris
Les tris suivants sont possibles. Il sont à placer dans un paramètre sort:
- timings.asc: Tri chronologique en fonction de la prochaine plage horaire à venir. Les événements aux plages horaires à venir les plus proches d'abord jusqu'au plus lointaines à venir, suivi des événements aux plages horaires les plus proches dans le passé aux plus lointaines.
- lastTiming.asc: Tri chronologique en fonction de la dernière plage horaire à venir, suivi des événements aux plages horaires les plus proches dans le passé aux plus lointaines.
- updatedAt.desc: Evénements mis à jour le plus récemment en premier
- updatedAt.asc: Evénements mis à jour le plus récemment en dernier
Navigation
Les résultats sont paginés. Pour récupérer l'intégralité des événements correspondant à une recherche, il est nécessaire de boucler de la manière suivante:
Après avoir récupéré un premier segment, le segment suivant peut être récupéré en prenant la valeur lue dans la clé after du résultat en main pour la passer à un paramètre after sur la requête suivante.
Important: lorsque une des valeurs fournies sous la clé after est null, elle doit être passée à la requête suivante de telle manière: &after=null plutôt que &after=
À noter: Il n'y a plus de jeu d'événements suivant à charger lorsque la réponse rend une liste vide d'événements et une valeur nulle associée à la clé after.
Par exemple, si pour la requête suivante:
https://api.openagenda.com/v2/events?sort=updatedAt.desc
Le résultat obtenu ressemble à ceci:
{
"total": 3412,
"events": [...],
"sort": "updatedAt.desc",
"after": [
1613618483000,
89372912
]
}
Les résultats suivants sont récupérés en précisant le même filtre et tri avec en plus un paramètre after comme ceci:
https://api.openagenda.com/v2/agendas/123/events?sort=updatedAt.desc&after[]=1613618483000&after[]=89372912
Par défaut, les événements sont données par 20. Le paramètre size permet de jouer sur ce nombre, avec un maximum de 300 événements rendus par requête.