Lister les événements d'un agenda

https://api.openagenda.com/v2/agendas/{agendaUid}/events?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
detailed Si égal a 1, rend l'intégralité des données publiques liées à chaque événement
size 2O par défaut. Nombre d'événements à récupérer par réponse
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.
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é.

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 searchAfter 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.

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.
  • timings.asc: Tri chronologique. 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.
  • 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 suivants 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.

Par exemple, si pour la requête suivante:

https://openagenda.com/agendas/123/events.v2.json?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://openagenda.com/agendas/123/events.v2.json?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}

A 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 plutot 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é.