Lecture

Lister les événements d'un agenda

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

Paramètres

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

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

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