Lister les événements d'un agenda

https://api.openagenda.com/v2/agendas/{agendaUid}/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.
agendaUid Identifiant de l'agenda. Il est affiché en barre latérale de la page publique de l'agenda sur https://openagenda.com
detailed Si égal a 1, rend l'intégralité des données publiques liées à chaque événement
from Optionnel. Récupérer les résultats à partir du n-ième événement. Préférer l'utilisation de la clé after
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. 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

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
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
featured En une ?featured=1 (en une) vs ?featured=0 (pas en une)
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)
state Statut sur l'agenda ?state=2 (publié - valeur par défaut), ?state=1 (prêt à publier), ?state=0 (à contrôler), ?state=-1 (réfusé). Les événements non publiés ne sont accessibles que par les utilisateurs modérateurs ou administrateurs.
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)

Filtres champs additionnels

Les champs additionnels de types à choix (checkbox, radio, select) peuvent également servir de base aux filtres. La clé est alors le code du champ concerné, les valeurs sont les identifiants à sélectionner.

Un exemple pour un champ additionnel Catégories Métropolitaines dont le code est categories-metropolitaines:

?categories-metropolitaines[]=2&categories-metropolitaines[]=4

Les codes et identifiants des champs additionnels sont donnés dans la configuration d'un agenda. Pour plus de détails, rendez vous dans la section correspondante de la documentation.

Tris

Les tris suivants sont possibles. Il sont à placer dans un paramètre sort:

  • timingsWithFeatured.asc: Tri par défaut. Evénéments en une en premier, puis tri chronologique en fonction de la prochaine plage horaire à venir.
  • 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.
  • lastTimingWithFeatured.asc: Comme lastTiming.asc mais avec les événements en une en premier.
  • 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 jeu d'événements, le jeu d'événements 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/agendas/123/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.

Variante export JSON v2

La récupération de données événementielle est également possible via la route suivante. La route API présentée en tête de page est à préférer.

https://openagenda.com/agendas/{agendaUid}/events.v2.json?key={publicKey}

À noter: Le domaine ici à préciser est https://openagenda.com plutôt que https://api.openagenda.com

Les différences se trouvent sur les clés à utiliser pour la navigation:

  • Dans la réponse, la clé "sort" fournit les valeurs à réutiliser pour récupérer les événements suivants plutôt que la clé "after"
  • La réponse ne fournit pas le tri effectif
  • Les contenus suivants peuvent être récupérés en utilisant la clé searchAfter plutôt que after

Ancien export JSON

Cliquez ici pour retrouver l'ancienne documentation.

Lire un événement

https://api.openagenda.com/v2/agendas/{agendaUid}/events/{eventUid}?key={publicKey}

Paramètres

Paramètre Description
agendaUid Identifiant de l'agenda. Il est affiché en barre latérale de la page publique de l'agenda sur https://openagenda.com
eventUid Identifiant de l'événement. Il est affiché en barre latérale de la page publique de l'événement sur https://openagenda.com
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é.