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

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.