# API OpenAgenda > Documentation sur l'API Openagenda et autres informations techniques - [Introduction](https://developers.openagenda.com/index.md) ## agendas - [Les agendas](https://developers.openagenda.com/agendas.md): Consulter les paramètres et données liées à un ou plusieurs agendas, à l'exception des événements - [Configuration d'un agenda](https://developers.openagenda.com/agendas/lecture.md): Consulter la configuration, un résumé du contenu et le schéma d'un agenda; - [Lister les agendas où le compte est membre](https://developers.openagenda.com/agendas/mes-agendas.md): Un compte peut être membre d'un ou plusieurs agendas. Cette route permet de les lister - [Recherche](https://developers.openagenda.com/agendas/recherche.md): Lister et rechercher les agendas publiés et indexés sur OpenAgenda - [Schémas et champs additionnels](https://developers.openagenda.com/agendas/schemas.md): Détail du fonctionnement du schéma événement d'un agenda et des champs additionnels. - [Lister les sources d'un agenda](https://developers.openagenda.com/agendas/sources.md): Récupérer les informations principales des agendas source d'un agenda ## authentification - [Authentification](https://developers.openagenda.com/authentification.md): Comment s'authentifier en amont des appels API en consultation ou en édition. ## evenements - [Les événements d'un agenda](https://developers.openagenda.com/evenements.md): Consulter et éditer les événements d'un agenda - [Création d'un événement](https://developers.openagenda.com/evenements/creation.md): Créer un nouvel événement sur un agenda en suivant la méthode usuelle ou avec un identifiant externe à OpenAgenda - [Édition d'un événement](https://developers.openagenda.com/evenements/edition.md): Mettre à jour un événement sur un agenda en suivant la méthode usuelle ou avec un identifiant externe à OpenAgenda - [Lecture d'événements d'un agenda](https://developers.openagenda.com/evenements/lecture.md): Lister ou consulter un événement d'un agenda - [Structure d'un événement](https://developers.openagenda.com/evenements/structure.md): Détails sur les champs standards, champs additionnels et autres champs propres à un agenda - [Suppression d'un événement](https://developers.openagenda.com/evenements/suppression.md): Supprimer un événement ou le retirer d'un agenda ## lieux - [Lieux](https://developers.openagenda.com/lieux.md): Consulter et éditer les lieux d'un agenda - [Création d'un lieu](https://developers.openagenda.com/lieux/creation.md): Créer un lieu sur un agenda en suivant la méthode usuelle ou avec un identifiant externe à OpenAgenda - [Édition d'un lieu](https://developers.openagenda.com/lieux/edition.md): Mettre à jour un lieu sur un agenda en suivant la méthode usuel ou avec un identifiant externe à OpenAgenda - [Lecture des lieux](https://developers.openagenda.com/lieux/lecture.md): Lister ou consulter un lieu d'un agenda - [Structure d'un lieu](https://developers.openagenda.com/lieux/structure.md): Détails sur les champs constitutifs d'un lieu - [Suppression d'un lieu](https://developers.openagenda.com/lieux/suppression.md): Supprimer définitivement un lieu d'un agenda ## membres - [Les membres d'un agenda](https://developers.openagenda.com/membres.md): Lister ## plugins - [Portail node.js](https://developers.openagenda.com/plugins/agenda-portal.md): Une librairie node.js qui permet de déployer un portail événementiel en marque blanche. Elle est disponible sur npm et sur githbub. - [Extension Drupal](https://developers.openagenda.com/plugins/drupal.md): Le module Drupal permet d'intégrer vos agendas hébergés chez https://openagenda.com directement sur votre site Drupal 8, 9 ou 10. - [Code embed](https://developers.openagenda.com/plugins/embeds.md): Ce code est disponible depuis la modale d'export de tout agenda publié sur OpenAgenda. Il permet d'intégrer simplement un agenda fonctionnel avec filtres, vue liste, vue détail sur un site. - [Extension Typo3](https://developers.openagenda.com/plugins/typo3.md): L'extension Typo3 pour OpenAgenda permet d'intégrer un ou plusieurs agendas en marque blanche directement sur vos sites Typo3 version 10.3 ou plus récente. - [Plugin WordPress](https://developers.openagenda.com/plugins/wordpress.md): Le plugin WordPress OpenAgenda vous permet d'intégrer facilement les événements OpenAgenda dans votre site WordPress. Il est publié sur le répertoire officiel wordpress.org et est disponible sous licence MIT sur github.com. --- # Full Documentation Content # Les agendas ``` [GET/POST/DELETE] /v2/agendas ``` Les routes documentées dans la section Agendas permettent de consulter plusieurs paramètres et données propres à un agenda, à l'exception des événements qui sont documentés dans une section dédiée. * [Recherche d'agendas](https://developers.openagenda.com/agendas/recherche.md): lister les agendas publiés sur la plateforme. * [Configuration](https://developers.openagenda.com/agendas/lecture.md): récupérer lire le détail de la configuration d'un agenda. * [Schémas et champs additionnels](https://developers.openagenda.com/agendas/schemas.md): comment étendre le formulaire événement * [Agendas sources](https://developers.openagenda.com/agendas/sources.md): lister les sources d'un agenda * [Mes agendas](https://developers.openagenda.com/agendas/mes-agendas.md): Lister les agendas où l'utilisateur authentifié est membre --- # Configuration d'un agenda Consulter la configuration, un résumé du contenu et le schéma d'un agenda; ``` GET /v2/agendas/{agendaUID} ``` ## En bref[​](#en-bref "Lien direct vers En bref") * L'identifiant d'un agenda `agendaUID` est présenté en pied de barre latérale sur sa page sur . * Une [authentification](https://developers.openagenda.com/authentification.md) est nécessaire. * L'option `?detailed=1` permet de récupérer le détail de la configuration d'un agenda. ## Propriétés[​](#propriétés "Lien direct vers Propriétés") | Clé | Chargé avec `detailed` | Type | Description | | ---------------- | ---------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `uid` | | entier | Identifiant unique | | `title` | | texte | Titre | | `description` | | texte | Description | | `slug` | | texte | Identifiant URL | | `url` | | lien | Lien associé à l'agenda, pointant vers un contenu de référence, comme le site de l'organisme représenté par l'agenda, des instructions ou autre contexte lié à l'agenda | | `official` | | entier | 1 s'il s'agit d'un agenda officiel, 0 sinon | | `networkUid` | | entier | Identifiant du réseau lié à l'agenda lorsque défini | | `locationSetUid` | | entier | Identifiant du jeu de lieux lié à l'agenda lorsque défini | | `updatedAt` | | date | Date de dernière mise à jour de l'agenda | | `createdAt` | | date | Date de création de l'agenda | | `memberSchemaId` | | entier | Identifiant du schéma étendu du formulaire membre lorsque défini | | `officializedAt` | | date | Date d'offialisation | | `image` | | lien | lien vers l'image associée | | `private` | | booléen | Caractère privé de l'agenda. 1 si oui | | `indexed` | | booléen | État d'indexation de l'agenda. 1 pour indexé, 0 pour non indexé | | `settings` | | objet | Configurations diverses de l'agenda: tracking, filtres, messagerie, paramètres de contribution | | `summary` | | objet | Données statistiques de l'agenda, rafraichies régulièrement, sur les mots clés associés, les décomptes d'événements publiés à venir, le carré géographique, les langues définies | | `network` | oui | objet | Informations relatives au réseau lié lorsque défini comme le titre (`title`), l'identifiant (`uid`), l'identifiant du schéma réseau (`formSchemaId`) | | `locationSet` | oui | objet | Informations relatives au jeu de lieux comme l'identifiant (`uid`), le titre (`title`) | | `schema` | oui | objet | Schéma événement propre à l'agenda | ## Exemple[​](#exemple "Lien direct vers Exemple") ``` { "uid": 4443516, "title": "Service Culturel - Université de Rennes", "description": "Découvrez les événements culturelles de l'université. Spectacles, expositions, projets arts & sciences, patrimoine scientifique et artistique…", "slug": "culture-univ-rennes", "url": "https://culture.univ-rennes.fr/", "official": 1, "networkUid": 18279479, "locationSetUid": 2447036, "updatedAt": "2025-07-22T09:09:38.000Z", "createdAt": "2020-07-08T08:25:10.000Z", "officializedAt": "2022-05-06T10:36:43.000Z", "image": "https://cdn.openagenda.com/main/agenda4443516.jpg", "settings": { "contribution": { "type": 2, "defaultState": 2, "canPublish": [ "administrators", "moderators" ], "moderateOnChangeBy": [], "defaultLang": null, "allowLocationCreate": true, "messages": { "instructions": null, "complete": null, "publication": null, "GDPRInformation": null }, "useFields": false } }, "summary": { "keywords": [ "Rennes", "Paimpont", "Brélévenez", "Saint-Malo", "Ille-et-Vilaine", "Côtes-d'Armor", "Bretagne", "cinéma", "Cinéma", "sciences", "concert", "patrimoine", "Science", "théâtre", "collections", "Concert", "Patrimoine" ], "publishedEvents": { "current": 0, "passed": 408, "upcoming": 14 }, "languages": { "fr": 422, "de": 3, "en": 3, "es": 3, "it": 3 }, "recentlyAddedEvents": { "contribution": 5, "shared": 0, "aggregation": 0 }, "viewport": { "topLeft": { "latitude": 48.72958996798843, "longitude": -3.462547017261386 }, "bottomRight": { "latitude": 48.00230098888278, "longitude": -1.6339340060949326 } } }, "network": { "uid": 18279479, "formSchemaId": 23982, "title": "Université Rennes" }, "locationSet": { "uid": 2447036, "title": "Lieux de l'université de Rennes 1" }, "schema": { "fields": [ { "field": "thematique", "label": { "fr": "Thématique" }, "optional": true, "display": true, "enable": true, "enableWith": null, "optionalWith": null, "min": null, "max": null, "options": [ { "id": 2, "value": "culture", "label": { "fr": "Culture" }, "info": null, "display": true }, { "id": 6, "value": "formation-orientation", "label": { "fr": "Formation / Orientation" }, "info": null, "display": true }, ... ], "fieldType": "checkbox", "schemaId": 23982, "schemaType": "network" }, ... ] } } ``` --- # Lister les agendas où le compte est membre ``` GET /v2/me/agendas ``` Consulter les agendas où l'utilisateur authentifié est membre ## En bref[​](#en-bref "Lien direct vers En bref") * Une [authentification](https://developers.openagenda.com/authentification.md) en lecture ou par jeton d'accès est requise. ## Navigation[​](#navigation "Lien direct vers Navigation") | Clé | Type | Description | | ----- | ------ | ----------------------------------------------------------------------------------------------------------- | | after | entier | Clé à fournir pour récupérer le jeu suivant. Elle est donnée dans la réponse du dernier appel reçu | | limit | entier | Définit le nombre d'items récupérés par appel. Valeur par défaut: **20**. Valeur maximale possible: **100** | ## Réponse[​](#réponse "Lien direct vers Réponse") | Clé | Type | Description | | ----- | -------- | ---------------------------------------------------------------------- | | total | entier | Le nombre total de membres | | items | objet\[] | La liste de paires agenda/membre | | after | entier | Valeur à placer dans l'appel suivant pour récupérer le segment suivant | Pour chaque item de la liste fournie, les informations suivantes sont données: | Clé | Type | Description | | ------------------- | --------- | ----------------------------------------------------- | | uid | entier | Identifiant de l'agenda | | title | texte | Titre de l'agenda | | slug | texte | Code URL de l'agenda | | member.userUid | entier | Identifiant du membre | | member.name | texte | Nom d'utilisateur ou nom | | member.email | courriel | Courriel du membre | | member.phone | téléphone | Numéro de téléphone | | member.organization | texte | Organisme représenté | | member.role | texte | Rôle du membre: administrator, moderator, contributor | --- # Recherche Lister et rechercher les agendas publiés et indexés sur OpenAgenda ``` GET /v2/agendas ``` ## Paramètres[​](#paramètres "Lien direct vers Paramètres") ### Filtres[​](#filtres "Lien direct vers Filtres") | Clé | Type | Description | Valeurs | | --------------- | --------- | ------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- | | `official` | booléen | Filtrer selon le critère officiel ou non des agendas | Indéfini par défaut. `0` pour filtrer sur les agendas non-officiels, `1` pour les officiels. | | `search` | texte | Recherche synthaxique sur le titre et les termes clés d'un agenda, dérivant des événements publiés: géographie, mots clés | Exemples: `?search=Festival` ou `search=Loiret` | | `network` | entier | Filtrer selon l'identifiant du réseau d'agendas souhaité | Exemple: `?network=34480426` | | `locationSet` | entier | Filtrer selon l'identifiant du jeu de lieux souhaité | Exemple: `?locationSet=3892749` | | `updatedAt.gte` | timestamp | Filtrer sur les agendas mis à jour après un moment donné. La variante `updatedAt.lte` est également possible. | Exemple: `?updatedAt.gte=2025-07-16T12:19:00.000Z` | | `uid` | entier\[] | Filtrer sur un ou plusieurs agendas par leurs identifiants uniques. | Exemple: `?uid=123` ou `?uid[]=123&uid[]=456` | | `slug` | texte\[] | Filtrer sur un ou plusieurs agendas par leurs codes url | Exemple: `?slug=loiret` ou `slug[]=cite-des-sciences&slug[]=versailles` | ### Contenu[​](#contenu "Lien direct vers Contenu") | Clé | Variante | Type | Description | Valeurs | | --------------- | -------- | -------- | ----------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | | `includeFields` | `if` | texte\[] | Liste des champs à récupérer. Utile pour limiter la volumétrie des données transférées au nécessaire. | `uid`, `title`, `image`, `description`, `official`, `slug`, `summary`, `schema`, `network`, `createdAt`, `locationSet`, `settings` | ### Navigation[​](#navigation "Lien direct vers Navigation") | Clé | Type | Description | Valeurs | | ------- | --------- | ----------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `after` | entier\[] | Clé à fournir pour récupérer le jeu suivant. Elle est donnée dans la réponse. | Exemple: `?after[]=1&after[]=36668061` | | `size` | entier | Nombre d'agendas à récupérer sur un appel. Maximum: 100. | Exemple: `?size=20` | | `sort` | texte | Filtrer par agendas officiels | `createdAt.desc` ou `recentlyAddedEvents.desc`. Si indéfini et avec un critère `search` de défini, le tri sera par pertinence, sinon, par ordre croissant d'identifiant. Le tri par défaut peut être amené à évoluer\` | ## Exemples[​](#exemples "Lien direct vers Exemples") ### curl[​](#curl "Lien direct vers curl") ``` curl -H "key: VOTRE_CLE_PUBLIQUE" \ "https://api.openagenda.com/v2/agendas?size=2&official=1" ``` ...donne: ``` { "after": [1, 125325], "agendas": [ { "uid": 62695, "image": "https://cdn.openagenda.com/main/agenda62695.jpg", "description": "Retrouvez tous les événements du patrimoine sur Grand Châtellerault", "official": true, "title": "Patrimoine Grand Châtellerault", "slug": "patrimoine-grand-chatellerault" }, { "uid": 125325, "image": "https://cdn.openagenda.com/main/agenda125325.jpg", "description": "EPCC pour la connaissance, la valorisation, la conservation et la restauration des patrimoines ethnologique et muséographique en Normandie.", "official": true, "title": "La Fabrique de patrimoines en Normandie", "slug": "fabrique" } ], "total": 3886 } ``` Et: ``` curl -H "key: VOTRE_CLE_PUBLIQUE" \ "https://api.openagenda.com/v2/agendas?size=2&official=1&after[]=1&after[]=125325" ``` ... pour récupérer le jeu de résultats suivants. --- # Schémas et champs additionnels Détail du fonctionnement du schéma événement d'un agenda et des champs additionnels. ## Le schéma événement d'un agenda[​](#le-schéma-événement-dun-agenda "Lien direct vers Le schéma événement d'un agenda") Un agenda propose à sa création un formulaire événement dérivant d'un schéma événement standardisé sur la plateforme. Les champs constitutifs de ce schema sont définis sous la clé `schema.fields` de [la configuration d'un agenda](https://developers.openagenda.com/agendas/lecture.md). ``` { "title": ..., "summary": {...}, "settings": {...}, ..., "schema": { "fields": [ ... ] }, ... } ``` Chaque champ est détaillé par les clés suivantes: | Clés | Type | Description | Valeurs | | ------------------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- | | `field` | texte | Le code du champ, dérive du label initial | Exemple : `thematiques` | | `fieldType` | texte | Le type du champ | Exemples : `checkbox`, `radio`, `select`, `multiselect`, `integer`, `multilingual`, `textarea`, `markdown`, `text`... | | `label`, `info`, `placeholder`, `sub` | texte | Texte ou multilingue. Des valeurs de labels utilisés pour l'affichage du champ sur le formulaire. | Exemple : `{ "fr": "Thématiques" }` | | `optional` | booléen | Par défaut `true`. Le caractère optionnel du champ. Si celui-ci est `false`, le champ doit être informé pour toute création ou mise à jour de l'événement. | | | `options` | objet\[] | Liste d'options pour les champs à choix (ex : `radio`, `checkbox`, `select`...). Pour les créations/mises à jour d'événement, c'est la sous-clé `id` de l'option à préciser qui doit être spécifiée dans le corps de requête en face du nom du champ. | Exemple : `[{"id": 1, "label": {"fr": "Musique"}, "value": "musique"}]` | | `schemaType` | texte | Le type de schéma d'où provient le champ : `event` pour les champs standards, `agenda` ou `network` pour les champs additionnels. | | | `languages` | texte\[] | La liste des langues en cas de champs texte multilingues. Liste vide pour les champ où les choix de langues sont libres | Exemple `["fr", "de"]` | Par exemple, le titre d'un événement est décrit comme ceci: ``` { "languages": [], "field": "title", "fieldType": "text", "optional": false, "max": 150, "label": { "fr": "Titre", "en": "Title", "it": "Titolo", "de": "Titel", "es": "Título" }, "placeholder": { "fr": "Le titre de votre événement", "en": "Title of your event", "it": "Il titolo del tuo evento", "de": "Titel Ihrer Veranstaltung", "es": "El título de su evento" }, "purpose": { "fr": "Titre de l'événement", "en": "Title of the event", "es": "Nombre del evento" }, "schemaType": "event" } ``` ## Les champs additionnels[​](#les-champs-additionnels "Lien direct vers Les champs additionnels") Le schéma standard événement peut être complété de champs dits additionnels, définits soit à l'échelle d'un agenda, soit d'un réseau. Lorsque c'est le cas, ces champs apparaissent dans la configuration `schema` et ont un `schemaType` qui précise la provenance de cette ajout: `agenda` ou `network`. ### Types[​](#types "Lien direct vers Types") Le type de chaque champ est précisé sous la clé `fieldType`. Un type se décline principalement en trois catégories: * **Les champs textuels**: texte simple, texte multi-ligne, HTML, markdown, multilingue. Dans ces cas, les valeurs sont directement associées aux clés "field" des champs sans conversion particulière. * **Les champs à options**: liste à choix unique, à choix multiple, select ou multi-select. Les valeurs associées aux clés dans ce cas sont les identifiants des options sélectionnées (voir exemple ci dessous). * **Les champs à fichiers**: ceux-cis ne sont pas manipulables par API En voici la liste complète: | Type | Clé | À options | Multilinguisme possible | | ---------------- | ----------- | --------- | ----------------------- | | Radio | radio | x | | | Checkbox | checkbox | x | | | Select | select | x | | | Multiselect | multiselect | x | | | Entier | integer | | | | Nombre | number | | | | Texte | text | | x | | Texte multiligne | textearea | | x | | Markdown | markdown | | x | | HTML | html | | x | | Image | image | | | | Fichier | file | | | ### Exemple[​](#exemple "Lien direct vers Exemple") Le cas le plus fréquent que l'on retrouve est qu'un formulaire événement standard soit complété d'un champ de catégories ou thématiques: un champ à choix de type `radio` ou `checkbox`: ``` { "field": "categories", "label": "Catégories", "optional": false, "options": [ { "id": 1, "value": "balade-decouverte-visite", "label": "Balade - découverte - visite" }, { "id": 2, "value": "conference-rencontre-debat", "label": "Conférence - rencontre - débat" }, { "id": 3, "value": "exposition", "label": "Exposition" }, { "id": 4, "value": "fete-salon-marche", "label": "Fête - salon - marché" }, { "id": 5, "value": "musique", "label": "Musique" }, ... ], "fieldType": "checkbox", "schemaType": "network" } ``` Les événements saisis et lus dans l'agenda verront leurs données complétées d'une clé reprenant el nom du champ additionnel: `categories`: ``` { "title": { "fr": "Festival d'été" }, ... "categories": [4], ... } ``` --- # Lister les sources d'un agenda ``` GET /v2/agendas/{agendaUID}/sources ``` Récupérer les informations principales des agendas source d'un agenda ## En bref[​](#en-bref "Lien direct vers En bref") * `agendaUID` est l'identifiant unique de l'agenda où les sources sont référencées. * Une [authentification](https://developers.openagenda.com/authentification.md) en lecture ou par jeton d'accès est requise. * L'utilisateur authentifié doit être administrateur de l'agenda. ## Navigation[​](#navigation "Lien direct vers Navigation") | Clé | Type | Description | | ----- | --------- | ---------------------------------------------------------------------------------------------------------------- | | after | entier\[] | Clé à fournir pour récupérer le jeu suivant. Elle est donnée dans la réponse du dernier appel reçu | | size | entier | Définit le nombre d'événements récupérés par appel. Valeur par défaut: **20**. Valeur maximale possible: **100** | ## Contenu[​](#contenu "Lien direct vers Contenu") | Clé | Type | Description | | -------- | ------------- | --------------------------------------------------------------------------- | | detailed | booléen(0\|1) | Si égal a 1, rend l'intégralité des données publiques liées à chaque source | ## Réponse[​](#réponse "Lien direct vers Réponse") | Clé | Type | Description | | ------- | -------- | --------------------------------------------------------------------------------- | | sources | objet\[] | Segment de sources de l'agenda | | after | entier | Valeur à placer dans l'appel suivant pour récupérer le segment de sources suivant | Chaque source présente les valeurs suivantes: | Clé | Type | Description | | ------ | -------- | ----------------------------------------- | | id | entier | Identifiant de la source | | rules | objet\[] | Rêgles d'agrégation associées à la source | | agenda | objet | Donnée publique de l'agenda source | --- # Authentification Comment s'authentifier en amont des appels API en consultation ou en édition. ## En bref[​](#en-bref "Lien direct vers En bref") Les clés utiles pour s'authentifier sont disponibles depuis [la page de paramètres](https://openagenda.com/settings/apiKey) de votre compte OpenAgenda. La procédure d'authentification diffère selon si vous souhaitez lire ou éditer des contenus. La procédure pour les éditions fonctionnera pour les lectures. ## Consultation seule[​](#consultation-seule "Lien direct vers Consultation seule") Passer la clé publique d'un compte OpenAgenda en entête de requête suffit pour les opérations de consultation. Un exemple: ``` curl -H "key: YOUR_API_KEY" https://api.openagenda.com/v2/agendas ``` **À noter**: * Il est également possible de placer la clé en query: `?key=votreclé`. Cette méthode n'est pas conseillée car elle laisse des traces de la clés dans des logs & historiques. * Un **token d'accès** obtenu avec **la clé secrète** d'un compte peut également servir pour les opérations de lecture. * Des clés de lecture peuvent également être créées depuis l'onglet *Avancé* de l'administration d'un agenda. ## Édition[​](#édition "Lien direct vers Édition") Une clé secrète est nécessaire pour l'édition de contenus via API: elle est attribuée sur simple demande à ### Récupération de la clé[​](#récupération-de-la-clé "Lien direct vers Récupération de la clé") 1. Connectez-vous à votre compte OpenAgenda 2. Accédez à la [section "API"](https://openagenda.com/settings/apiKey) dans vos paramètres 3. Si nécessaire, générez une nouvelle clé API secrète en cliquant sur l'action liée au champ de présentation de la clé. ### Utilisation[​](#utilisation "Lien direct vers Utilisation") La clé secrète permet la récupération d'un token d'accès à la durée de vie limitée et qui devra être passé en entête de toutes les requêtes suivantes: #### Obtention du token d'accès[​](#obtention-du-token-daccès "Lien direct vers Obtention du token d'accès") Il suffit d'une requête `POST` sur la route `https://api.openagenda.com/v2/requestAccessToken` avec en entête, la clé secrète placée en face d'une clé `code`. Voici quelques exemples: ##### bash[​](#bash "Lien direct vers bash") ``` curl -X POST "https://api.openagenda.com/v2/requestAccessToken" -H "Content-Type: application/json" -d' { "code": VOTRE_CLE_SECRETE }' ``` ##### node.js[​](#nodejs "Lien direct vers node.js") ``` const response = await fetch('https://api.openagenda.com/v2/requestAccessToken', { method: 'POST', headers: { 'Content-Type': 'application/json', }, body: JSON.stringify({ code: VOTRE_CLE_SECRETE }), }); const { access_token, expires_in } = await response.json(); ``` #### Utilisation du token[​](#utilisation-du-token "Lien direct vers Utilisation du token") Une fois le token en main, il est à passer en entête de requête sous une clé `access-token` tant que celui-ci n'est pas expiré. Une fois arrivé à expiration, un nouveau token doit être généré. ##### bash[​](#bash-1 "Lien direct vers bash") ``` curl -X GET "https://api.openagenda.com/v2/agendas" -H "Content-Type: application/json" -H "access-token: VOTRE_TOKEN" ``` ##### node.js[​](#nodejs-1 "Lien direct vers node.js") ``` const response = await fetch('https://api.openagenda.com/v2/agendas', { method: 'GET', headers: { 'Content-Type': 'application/json', 'access-token': VOTRE_TOKEN } }); ``` --- # Les événements d'un agenda ``` [GET/POST/PUT/DELETE] /v2/agendas/{agendaUID}/events ``` Cette route permet de gérer les événements référencés sur un agenda: créer des événements, les mettre à jour, les retirer... les opérations sont détaillées dans les pages suivantes: * [Structure](https://developers.openagenda.com/evenements/structure.md): comment est constitué un événement * [Lecture](https://developers.openagenda.com/evenements/lecture.md): consulter un ou plusieurs événements, filtre et faire des recherches * [Création](https://developers.openagenda.com/evenements/creation.md): créer un nouvel événement * [Édition](https://developers.openagenda.com/evenements/edition.md): apporter des modifications à un événement * [Suppression](https://developers.openagenda.com/evenements/suppression.md): retirer ou supprimer un événement d'un agenda --- # Création d'un événement ## Méthode usuelle[​](#méthode-usuelle "Lien direct vers Méthode usuelle") ``` POST /v2/agendas/{agendaUID}/events ``` ### En bref[​](#en-bref "Lien direct vers En bref") Cette route permet la création d'un événement **dans le contexte d'un agenda**. Ceci signifie qu'au delà des valeurs des [champs standard](https://developers.openagenda.com/evenements/structure.md#champs-standards) de l'événement, les valeurs associées aux champs additionnels de l'agenda peuvent être définis. * `agendaUID` est l'identifiant unique de l'agenda où les événements sont référencés * Une [authentification](https://developers.openagenda.com/authentification.md) en écriture par jeton d'accès est requise * Un paramètre `lang` peut être précisé en entête (`lang:fr`) pour simplifier le formatage d'événements monolingues * Pour les événements [physiques/in situ](https://developers.openagenda.com/evenements/structure.md#mode-de-participation), il est nécessaire de les lier à un lieu par son identifiant. Ce dernier doit être connu au moment de la création de l'événement. * Les données définissant l'événement doivent être placées sous une clé `data` en corps de requête. ### Exemples[​](#exemples "Lien direct vers Exemples") #### Cas le plus basique[​](#cas-le-plus-basique "Lien direct vers Cas le plus basique") À minima, un événement doit avoir les informations suivantes de définies: un titre, une description courte, une plage horaire, un lieu. ##### node.js[​](#nodejs "Lien direct vers node.js") ``` import axios from 'axios'; import getImageURL from './getImageURL.js'; import getAccessToken from './getAccessToken.js'; import getAgendaUID from './getAgendaUID.js'; import getLocationUID from './getLocationUID.js'; const { data: { event: createdEvent, }, } = await axios({ method: 'post', url: `https://api.openagenda.com/v2/agendas/${getAgendaUID()}/events`, headers: { 'access-token': getAccessToken(), 'content-type': 'application/json', 'lang': 'fr', }, data: { title: 'Un été au ciné, cinéma en plein air - Donne moi des ailes', description: 'De Nicolas Vanier - 2019 / 1h53 - Avec Louis Vazquez, Jean-Paul Rouve, Mélanie Doutey', locationUid: getLocationUID(), timings: [{ begin: '2025-08-06T21:30:00.000+0200', end: '2025-08-06T23:30:00.000+0200' }], } }); ``` #### Un événement multilingue[​](#un-événement-multilingue "Lien direct vers Un événement multilingue") Les champs `title`, `description`, `longDescription`, `keywords` et `conditions` sont multilingues. Les variantes de chaque langue sont à placer derrière des clés correspondant au code langue. ##### node.js[​](#nodejs-1 "Lien direct vers node.js") ``` ... const { data: { event: createdEvent, }, } = await axios({ method: 'post', url: `https://api.openagenda.com/v2/agendas/${getAgendaUID()}/events`, headers: { 'access-token': getAccessToken(), 'content-type': 'application/json', }, data: { title: { fr: 'Un été au ciné, cinéma en plein air - Donne moi des ailes', en: 'A summer at the movies, open-air cinema - Give me wings', }, description: { fr: 'De Nicolas Vanier - 2019 / 1h53 - Avec Louis Vazquez, Jean-Paul Rouve, Mélanie Doutey', en: 'From Nicola Vanier - 2019 / 1h53 - With Louis Vazquez, Jean-Paul Rouve, Mélanie Doutey', }, keywords: { fr: ['ciné', 'projection'], en: ['movies', 'projection'], }, ... }, }); ``` #### Un événement avec champs additionnels[​](#un-événement-avec-champs-additionnels "Lien direct vers Un événement avec champs additionnels") [Voir ici](https://developers.openagenda.com/agendas/schemas.md) pour des détails sur le fonctionnement des champs additionnels. Pour cet exemple, l'agenda à le champ additionnel suivant de défini: ``` { "field": "thematique", "label": "Thématique", "optional": false, "options": [ { "id": 15, "value": "vie-associative", "label": "Vie associative" }, { "id": 8, "value": "numerique", "label": "Numérique" }, { "id": 61, "value": "culture", "label": "Culture" }, ... ], "fieldType": "checkbox", "schemaType": "network" }, ``` L'événement créé doit être associé à la thématique `Culture`: ##### ``` ... const { data: { event: createdEvent, }, } = await axios({ method: 'post', url: `https://api.openagenda.com/v2/agendas/${getAgendaUID()}/events`, headers: { 'access-token': getAccessToken(), 'content-type': 'application/json', }, data: { title: { fr: 'Un été au ciné, cinéma en plein air - Donne moi des ailes', }, ..., thematique: [61], }, }); ``` #### Événement avec image fournie par fichier[​](#événement-avec-image-fournie-par-fichier "Lien direct vers Événement avec image fournie par fichier") ##### node.js & axios[​](#nodejs--axios "Lien direct vers node.js & axios") ``` import FormData from 'form-data'; import fs from 'fs'; import path from 'path'; import axios from 'axios'; import getAccessToken from './getAccessToken.js'; import getAgendaUID from './getAgendaUID.js'; const imageStream = fs.createReadStream(path.resolve('./image.png')); const form = new FormData(); form.append('data', JSON.stringify({ title: `Titre de l'événement`, description: `Description courte de l'événement`, attendanceMode: 2, onlineAccessLink: 'https://openagenda.com', timings: [{ begin: '2025-08-30T10:00:00+0200', end: '2025-08-30T11:00:00+0200', }] )); form.append('image', imageStream); await axios({ method: 'POST', url: `https://api.openagenda.com/v2/agendas/${getAgendaUID()}/events`, headers: { ...form.getHeaders(), 'access-token': await getAccessToken(), }, data: form, }); ``` ## Création par identifiant externe[​](#création-par-identifiant-externe "Lien direct vers Création par identifiant externe") Un événement peut être créé via un [identifiant externe](https://developers.openagenda.com/evenements/structure.md#identifiants-externes) à OpenAgenda. La même route sert également pour les mise à jour, lorsqu'un événement existe déjà pour l'identifiant donné: ``` PUT /v2/agendas/{agendaUID}/events/ext/{key}/{value} ``` ### En bref[​](#en-bref-1 "Lien direct vers En bref") * `key` est le nom de l'identifiant, `value` sa valeur * Si l'événement existe déjà, il sera mis à jour * Un événement peut être associé à plusieurs identifiants externes * Un événement associé à un ou plusieurs identifiants externes garde un identifiant OpenAgenda unique `UID`. --- # Édition d'un événement ## Méthode usuelle[​](#méthode-usuelle "Lien direct vers Méthode usuelle") ``` [POST/PATCH] /v2/agendas/${agendaUID}/events/${eventUID} ``` ### En bref[​](#en-bref "Lien direct vers En bref") Cette route permet la mise à jour d'un événement **dans le contexte d'un agenda**. Ceci signifie qu'au delà des valeurs des [champs standard](https://developers.openagenda.com/evenements/structure.md#champs-standards) de l'événement, les valeurs associées aux champs additionnels de l'agenda peuvent être mises à jour, ainsi que le statut (publié, à modérer...) ou encore sa mise en une. * `agendaUID` est l'identifiant unique de l'agenda où l'événement est référencé, `eventUID` est l'identifiant unique de l'événement * Une [authentification](https://developers.openagenda.com/authentification.md) en écriture par jeton d'accès est requise * Un paramètre `lang` peut être précisé en entête (`lang:fr`) pour simplifier le formatage d'événements monolingues * La réponse contient le détail de l'événement mis à jour sous une clé `event` * La méthode `POST` est à utiliser pour les mises à jour complètes, `PATCH` pour les mises à jour partielles * Les données définissant l'événement doivent être placées sous une clé `data` en corps de requête. ## Mise à jour par identifiant externe[​](#mise-à-jour-par-identifiant-externe "Lien direct vers Mise à jour par identifiant externe") Un événement peut être mis à jour via un [identifiant externe](https://developers.openagenda.com/evenements/structure.md#identifiants-externes) à OpenAgenda. La même route sert également pour les créations lorsqu'un événement n'existe pas pour l'identifiant donné. ``` PUT /v2/agendas/{agendaUID}/events/ext/{key}/{value} ``` ### En bref[​](#en-bref-1 "Lien direct vers En bref") * `key` est le nom de l'identifiant, `value` sa valeur * Si l'événement existe déjà, il sera mis à jour * Un événement peut être associé à plusieurs identifiants externes * Un événement associé à un ou plusieurs identifiants externes garde un identifiant OpenAgenda unique `UID`. --- # Lecture d'événements d'un agenda ## Lister[​](#lister "Lien direct vers Lister") ``` GET /v2/agendas/{agendaUID}/events ``` ### En bref[​](#en-bref "Lien direct vers En bref") * `agendaUID` est l'identifiant unique de l'agenda où les événements sont référencés. * Une [authentification](https://developers.openagenda.com/authentification.md) en lecture ou par jeton d'accès est requise. * La réponse contient un segment d'événement plutôt que la liste complète. Si le total excède le nombre de lieux rendus en un appel, une boucle de lecture devra être mise en place. ### Paramètres[​](#paramètres "Lien direct vers Paramètres") #### Filtres standards[​](#filtres-standards "Lien direct vers Filtres standards") Les paramètres suivant agissent sur la sélection des événements rendus par un appel. | Clé | Type | Description | | --------------- | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | removed | booléen(0\|1\|null) | Par défaut, les événements ayant été retirés ou supprimés ne sont plus présentés dans l'agenda. Ce paramètre précisé à `1` en fera remonter l'identifiant `uid` et le moment du retrait `updatedAt`. Ceci permet aux traitements de synchronisation de suivre les retraits entre deux intervalles de suppressions. | | city | texte\[] | Filtrer par ville.
Exemple: `?city[]=Lausanne&city[]=Genève` | | department | texte\[] | ...par Département.
Exemple: `?department[]=Hauts-de-Seine` | | region | texte\[] | ...par Région.
Exemple: `?region=Normandie` | | timings\[gte] | date | ...par horaire supérieur à ...
Exemple: `?timings[gte]=2025-...:00:00.000Z` | | timings\[lte] | date | Filtre par horaire inférieur à ...
Exemple: `?timings[lte]=2021-02-18T...00Z` | | updatedAt\[gte] | date | Mis à jour après le ...
Exemple: `?updatedAt[gte]=2021-02-1...:00.000Z` | | updatedAt\[lte] | date | Mis à jour avant le ...
Exemple: `?updatedAt[lte]=2021-02-...00.000Z` | | search | texte\[] | Recherche synthaxique
Exemple: `?search=Concert` | | uid | texte\[] | Filtre par identifiant
Exemple: `?uid[]=56158955&uid[]=55895615` | | slug | texte\[] | Filtre par code url
Exemple: `?slug=festival-dete` | | featured | texte\[] | En une
Exemple: `?featured=1` (en une) vs `?featured=0` (pas en une) | | relative | texte\[] | Passé / En cours / A venir
Exemple: `?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 | texte\[] | Statut sur l'agenda
Exemple: `?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 | texte\[] | Mots clés
Exemple: `?keyword[]=gratuit&keyword[]=exposition` fonction en `ET` logique | | geo | texte\[] | Filtrer sur un carré géographique
Exemple: `?geo[northEast][lat]=48.9527&geo[northEast][lng]=2.4484&geo[southWest][lat]=48.8560&geo[southWest][lng]=2.1801` | | locationUid | texte\[] | Filtre par identifiant de lieu
Exemple: `?locationUid[]=123&locationUid[]=456` | | accessibility | texte\[] | Filtrer par accessibilité particulière
Exemple: `?accessibility[]=hi&accessibility[]=vi` | | status | texte\[] | Filtrer par état
Exemple: `?status[]=1` | #### Filtres de champs additionnels[​](#filtres-de-champs-additionnels "Lien direct vers Filtres de 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 serait `categories-metropolitaines`: ``` GET /v2/agendas/{agendaUID}/events?categories-metropolitaines[]=2 ``` Le fonctionnement des champs additionnels est détaillé [ici](https://developers.openagenda.com/agendas/schemas.md) #### Contenu[​](#contenu "Lien direct vers Contenu") | Clé | Type | Description | | --------------------- | ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | detailed | booléen(0\|1) | Si égal a 1, rend l'intégralité des données publiques liées à chaque événement. | | monolingual | texte | Préciser un code langue (fr, en, it, de) pour ne renvoyer qu'une seule langue pour les champs multilingues ou les labels de champs additionnels. Si la langue choisie n'est pas définie, une langue disponible sera utilisée. | | longDescriptionFormat | texte | `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é. | | includeLabels | booléen(0\|1) | Inclure les labels dans les champs additionnels à choix.
Exemple: `{"categorie": 1}` devient `{"categorie": {"id": 1, "label": {"fr": "Spectacle"}}}`. | | includeFields | texte\[] | Précise les données à remonter pour chaque événement; utile à des fins d'optimisation de temps de réponse et de bande passante. Variante courte: `if[]=` Ex: `if[]=uid&if[]=location.city` | ***Pro tip***: utilisez `detailed` en développement et `includeFields` en production pour réduire le volume de données qui transitent et améliorer les temps de réponse. #### Navigation[​](#navigation "Lien direct vers Navigation") | Clé | Type | Description | | ----- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | after | texte\[] | Sert à 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. | | from | entier | Alternative à `after`. Permet de récupérer les résultats à partir du n-ième événement. Préférer l'utilisation de la clé after pour de meilleures performances, en particulier pour les lectures plus complètes (> 500 événements) | | size | entier | Définit le nombre d'événements récupérés par appel. Valeur par défaut: **20**. Valeur maximale possible: **300** | | sort | texte | Choix du tri à appliquer | ##### Tris[​](#tris "Lien direct vers Tris") Les tris suivants sont possibles. Il sont à placer dans un paramètre `sort`: | Valeur | Description | | -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 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 | #### Réponse |[​](#réponse-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- "Lien direct vers Réponse |") La réponse présente les données sous les clés suivantes: | Clé | Type | Description | | ------ | --------- | ------------------------------------------------------------------------------------ | | total | entier | Le nombre total de membres | | events | objet\[] | Segment d'événements correspondants aux filtres | | sort | texte | Tri effectif | | after | textes\[] | Valeurs à placer dans l'appel suivant pour récupérer le segment d'événements suivant | Les événements sont présentés selon la structure détaillée [ici](https://developers.openagenda.com/evenements/structure.md). ### Quelques cas d'usage[​](#quelques-cas-dusage "Lien direct vers Quelques cas d'usage") #### Récupérer tous les événements à venir publiés sur un agenda[​](#récupérer-tous-les-événements-à-venir-publiés-sur-un-agenda "Lien direct vers Récupérer tous les événements à venir publiés sur un agenda") Dans le cas où l'objectif est de reprendre l'intégralité des événements correspondant à un filtre donné, une suite d'appels sera nécessaire lorsque le total excède la taille maximale d'événements récupérables en un appel (`300`). Pour cet exemple, le souhait est de récupérer tous les événements en cours et à venir publiés sur l'agenda: le filtre `relative` sert dans ce cas. Un premier appel est fait pour récupérer le premier segment des résultats: ``` GET /v2/agendas/{agendaUID}/events?relative[]=current&relative[]=upcoming ``` Le résultat rendu a la forme suivante, il fournit les 20 premiers événements des 872 événements correspondants au filtre demandé: ``` { "total": 872, "events": [...], "after": ["0", "000001758268800", "1758472200000", "5335740"] } ``` Les valeurs fournies sous la clé `after` permettent de récupérer les 20 événements suivants: ``` GET /v2/agendas/{agendaUID}/events?relative[]=current&relative[]=upcoming&after[]=0&after[]=000001758268800&after[]=1758472200000&after[]=5335740 ``` Et ainsi de suite jusqu'à arriver aux derniers événements. La dernière réponse fournira un `after` à `null` indiquant qu'il n'y a plus d'autres événements à récupérer. ``` { "total": 872, "events": [...], "after": null } ``` *** #### Synchroniser une base de données événementielle[​](#synchroniser-une-base-de-données-événementielle "Lien direct vers Synchroniser une base de données événementielle") Un script synchronisant la programmation d'un agenda avec une base tiers à intervalle régulier peut fonctionner en récupérant l'intégralité de la programmation lors de sa première execution puis en se **limitant** au traitement des **ajouts, modifications et suppressions** entre chaque nouvelle execution. Les paramètres suivants sont utiles pour y parvenir: * **updatedAt\[gte]**: préciser la dernière execution du script pour limiter la sélection aux événements mis à jour depuis * **removed**: `null` pour **inclure** les événements qui ont été retirés de la programmation * **sort**: `updatedAt.asc`: optionnellement, trier la sélection suivant l'ordre des mise à jour pour simplifier la lecture ... et dans cet exemple, nous ne nous intéressons qu'aux textes français. ``` GET /v2/agendas/{agendaUID}/events?updatedAt[gte]=2025-07-11T13:49:58.000Z&removed=null&monolingual=fr ``` Le résultat ressemblera à ceci: ``` { "total": 462, "events": [ { "uid": 50976230, "removed": true, "updatedAt": "2025-07-11T13:49:59.024Z" }, { "uid": 1325588, "removed": false, "updatedAt": "2025-07-11T13:52:05.000Z", "createdAt": "2025-07-11T13:52:05.000Z", "title": "Visite de l'Hôtel de ville de Belfort", ... }, ... ], "after": ["1753800986069", "43733206"] } ``` Les identifiants des événements retirés suffisent pour répercuter l'opération de retrait sur la base synchronisée, les autres événements peuvent être soit créés, soit mis à jour ### Export JSON[​](#export-json "Lien direct vers Export JSON") L'export JSON anciennement proposé sur la modale d'export des agendas OpenAgenda est **en fin de vie**. La documentation de cet export [est consultable ici](https://developers.openagenda.com/evenements/export-json), une aide pour migrer les synchronisations [est proposée ici](https://developers.openagenda.com/evenements/export-json-migration). ## Consulter un événement[​](#consulter-un-événement "Lien direct vers Consulter un événement") ### Par son identifiant unique (uid)[​](#par-son-identifiant-unique-uid "Lien direct vers Par son identifiant unique (uid)") ``` GET /v2/agendas/{agendaUID}/events/{eventUID} ``` #### En bref[​](#en-bref-1 "Lien direct vers En bref") * `agendaUID` est l'identifiant unique de l'agenda où l'événement est référencé, `eventUID` son identifiant unique. * Une [authentification](https://developers.openagenda.com/authentification.md) en lecture ou par jeton d'accès est requise. ### Par un identifiant externe à OpenAgenda (extId)[​](#par-un-identifiant-externe-à-openagenda-extid "Lien direct vers Par un identifiant externe à OpenAgenda (extId)") ``` GET /v2/agendas/{agendaUID}/events/ext/{key}/{value} ``` #### En bref[​](#en-bref-2 "Lien direct vers En bref") * `agendaUID` est l'identifiant unique de l'agenda où l'événement est référencé, `key` est le code de l'identifiant externe et `value` sa valeur. * Une [authentification](https://developers.openagenda.com/authentification.md) en lecture ou par jeton d'accès est requise. #### Paramètres[​](#paramètres-1 "Lien direct vers Paramètres") | Clé | Type | Description | | --------------------- | ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | longDescriptionFormat | texte | `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é. | | includeLabels | booléen(0\|1) | Inclure les labels dans les champs additionnels à choix.
Exemple: `{"categorie": 1}` devient `{"categorie": {"id": 1, "label": {"fr": "Spectacle"}}}`. | --- # Structure d'un événement ## Champs standards[​](#champs-standards "Lien direct vers Champs standards") ### Résumé[​](#résumé "Lien direct vers Résumé") Ce sont les champs présents sur **tous les événements** publiés sur OpenAgenda et dont les contraintes doivent être respectées quel que soit l’agenda. | Champ | Code | Éditable | Requis | Valeur par défaut |  Description | | ---------------------------------------------------- | ------------------ | -------- | ------ | ----------------- | ------------------------------------------------------------------------------------------------ | | [**Identifiant Unique**](#identifiant-unique) | `uid` | | | | Identifiant unique OpenAgenda de l’événement | | [**Code URL**](#code-url) | `slug` | | | | Identifiant texte unique OpenAgenda de l'événement | | [**Identifiants externes**](#identifiants-externes) | `extIds` | ✅ | | | Liste de clés/paires identifiant l'événement sur des jeux de données externes à OpenAgenda | | [**Titre**](#titre) | `title` | ✅ | ✅ | | Le titre de l'événement | | [**Description courte**](#description-courte) | `description` | ✅ | ✅ | | La description courte de l'événement | | [**Description longue**](#description-longue) | `longDescription` | ✅ | | | La description longue de l'événement | | [**Conditions**](#conditions) | `conditions` | ✅ | | | Description libre des conditions de participation à l'événement | | [**Mots clés**](#mots-cl%C3%A9s) | `keywords` | ✅ | | | Liste de mots clés | | [**Image**](#image) | `image` | ✅ | | | Illustration principale | | [**Crédits image**](#cr%C3%A9dits-image) | `imageCredits` | ✅ | | | Crédits liés à l’illustration | | [**Inscription**](#outils-dinscription) | `registration` | ✅ | | | Liste des moyens d'inscription : numéros de téléphones, email ou liens hypertextes | | [**Accessibilité**](#accessibilit%C3%A9) | `accessibility` | ✅ | | | Types de handicaps pour lesquels des aménagements sont prévus | | [**Horaires**](#horaires) | `timings` | ✅ | ✅ | | Liste de plages horaires | | [**Âge cible**](#%C3%A2ge-du-public-cibl%C3%A9) | `age` | ✅ | | | Créneau min/max d'âge des participants ciblés | | [**Mode de participation**](#mode-de-participation) | `attendanceMode` | ✅ | | 1 (Physique) | Mode de participation à l'événement (physique vs en ligne) | | [**Identifiant de lieu**](#identifiant-de-lieu) | `locationUid` | ✅ | ✅ ⁽ˡ⁾ | | Identifiant unique OpenAgenda du lieu associé | | [**Lien d’accès**](#lien-dacc%C3%A8s) | `onlineAccessLink` | ✅ | | | Lien hypertexte d'accès à un événement en ligne ou mixte | | [**Liens enrichis**](#liens-enrichis) | `links` | | | | Liste de paires lien / codes enrichis | | [**Fuseau horaire**](#fuseau-horaire) | `timezone` | ✅ | | Fuseau du lieu | Fuseau horaire de référence. Pour les événements en ligne, le fuseau par défaut est Europe/Paris | | [**État**](#%C3%A9tat) | `status` | ✅ | | 1 (Programmé) | Reporté, Annulé, Complet… | | [**Statut**](#statut) | `state` | ✅ | | Selon l'agenda | Statut dans l’agenda : Publié (2), Prêt à publier (1), À modérer (0), Refusé (−1) | | [**Date de création**](#date-de-cr%C3%A9ation) | `createdAt` | | | | Instant de création | | [**Date de mise à jour**](#date-de-mise-%C3%A0-jour) | `updatedAt` | | | | Instant de la dernière mise à jour | ⁽ˡ⁾ Champ lié: requis selon une valeur définie sur un champ voisin. Voir le détail du champ pour des précisions ⁽ᵈ⁾ Une valeur par défaut est définie lorsqu'une valeur n'est pas explicitée pour ce champ. ### Détail[​](#détail "Lien direct vers Détail") #### Identifiant unique[​](#identifiant-unique "Lien direct vers Identifiant unique") Identifiant unique OpenAgenda de l'événement. Assigné à la création de l'événement et non éditable.
**code**: `uid`
**type**: `entier` #### Code URL[​](#code-url "Lien direct vers Code URL") Identifiant utile pour construire une URL lisible dérivée du titre de l'événement.
**code**: `slug`
**type**: `texte` #### Identifiants externes[​](#identifiants-externes "Lien direct vers Identifiants externes") Il est possible d'associer à un événement OpenAgenda des identifiants autres que son identifiant unique (UID). Les identifiants externes peuvent être définits soit par une mise à jour classique, soit via les routes dédiées aux identifiants externes. **code**: `extIds`
**type**: `objet({ key, value })[]` ##### Exemple[​](#exemple "Lien direct vers Exemple") ``` { ... "extIds": [{ "value": "9f15474c-58cd-42a4-9c93-7114b1ee44f0", "key": "Albi" }], ... } ``` #### Titre[​](#titre "Lien direct vers Titre") Le titre de l'événement.
Champ **obligatoire** ne pouvant excéder **140** caractères par langue.
**code**: `title`
**type**: `texte multilingue`
**schema.org**: [name](https://schema.org/name) ##### Exemple[​](#exemple-1 "Lien direct vers Exemple") ``` { ... "title": { "fr": "Le Coin Vert de Stéphane", "en": "The Green Corner of Stéphane", "es": "El rincón verde de Esteban", "de": "Le Coin Vert de Stéphane", "it": "La Zona Verde di Stéphane" }, ... } ``` #### Description courte[​](#description-courte "Lien direct vers Description courte") Chapô, variante courte ou extrait de la description de l'événement. Est utilisé en complément due titre sur les vues réduites (liste) de l'événement.
Champ **obligatoire** ne pouvant excéder **200** caractères par langue.
**code**: `description`
**type**: `texte multilingue`
**schema.org**: [disambiguatingDescription](https://schema.org/disambiguatingDescription) #### Description longue[​](#description-longue "Lien direct vers Description longue") Description de l'événement.
Champ optionnel ne pouvant excéder **10000** caractères par langue.
**code**: `longDescription`
**type**: `texte multilingue markdown`
**schema.org**: [description](https://schema.org/description) ##### À propos du format[​](#à-propos-du-format "Lien direct vers À propos du format") La description est stoquée au format [markdown](https://fr.wikipedia.org/wiki/Markdown). C'est également le format présenté par défaut sur une lecture API. Toujours en **lecture**, une [option](https://developers.openagenda.com/evenements/lecture.md) à passer à l'API permet de faire une conversion et de récupérer la description au format `HTML`. Autrement, en **écriture** un format HTML sera automatiquement converti en markdown en amont d'un enregistrement en base. ##### Contenus enrichis[​](#contenus-enrichis "Lien direct vers Contenus enrichis") Certains liens insérés dans la description longue sont extraits lors de la création ou à la mise à jour et sont associés à des codes d'intégration enrichis mis à disposition dans le champ links de l'événement ainsi que dans la variante html de la description longue. Les services intégrables incluent: *Allociné, Arte, Calameo, Dailymotion, Eventbrite, Flickr, Google Forms, INA, Instagram, PictoAccess, Prezi, Soundcloud, Twitch, Twitter, Vimeo, WeMap, Youtube* ##### Exemple[​](#exemple-2 "Lien direct vers Exemple") ``` { ... "longDescription": { "fr": "**Explorez les multiples visages de l’Afrique du Sud à travers une dégustation commentée de trois vins soigneusement sélectionnés, témoins de la richesse et de la diversité de ses terroirs.**\n\nPartez pour un voyage au cœur de l’un des plus vastes vignobles du nouveau monde, où traditions anciennes et modernité s’entrelacent. À travers cette exploration, vous plongerez dans l’histoire viticole de l’Afrique du sud, mise en valeur par trois régions emblématiques.\n\nChaque cuvée vous révèlera un style singulier, reflet fidèle de son terroir, entre influences maritimes, diversité des sols et caractère des cépages.\n\nDégustation de 3 vins\n\nVous participez régulièrement à nos afterworks de dégustation ? Pensez à notre carte de fidélité Afterwork ! Dès 5 ateliers afterworks effectués, nous vous offrons le 6ème ! Votre carte de fidélité fonctionne pour des ateliers en tarif plein mais aussi en tarif réduit et abonnés. N'oubliez pas de la demander à nos sommeliers.\n\n**Animé par : Raul Vega**, animateur-sommelier à la Cité du Vin\n\n**En partenariat avec** : Wines of South Africa\n\n**Avec le soutien de** : Maison Johanès Boubée" }, ... } ``` #### Conditions[​](#conditions "Lien direct vers Conditions") Détails des conditions de participation à l'événement.
Champ optionnel ne pouvant excéder **255** caractères par langue.
**code**: `conditions`
**type**: `texte multilingue` #### Mots clés[​](#mots-clés "Lien direct vers Mots clés") Liste de mots clés.
Champ optionnel ne pouvant excéder 255 caractères par langue
**code**: `keywords`
**type**: `listes de textes par langue` ##### Exemple[​](#exemple-3 "Lien direct vers Exemple") ``` { ... "keywords": { "fr": ["musique", "concert", "rock"] }, ... } ``` #### Image[​](#image "Lien direct vers Image") Illustration principale de l'événement.
Champ optionnel au format variable selon l'opération.
**code**: `image`
**type**: `fichier` ##### En lecture[​](#en-lecture "Lien direct vers En lecture") Lorsqu'une image est définie plusieurs variantes sont proposées, toujours au format `jpeg`: * **base**: l'image redimensionnée en largeur et non découpée pour tenir sur 700 pixels. * **full**: l'image aux dimensions d'origine * **thumbnail**: l'image redimensionnée et découpée pour tenir dans un rectangle de 200x200 pixels Les dimensions sont précisées pour chaque variante ainsi que la route où elles sont accessibles. ###### Exemple[​](#exemple-4 "Lien direct vers Exemple") ``` { ... "image": { "filename": "23fc5619015849848ffe4843c98a03e2.base.image.jpg", "size": { "width": 700, "height": 394 }, "variants": [ { "filename": "23fc5619015849848ffe4843c98a03e2.full.image.jpg", "size": { "width": 1920, "height": 1080 }, "type": "full" }, { "filename": "23fc5619015849848ffe4843c98a03e2.thumb.image.jpg", "size": { "width": 200, "height": 200 }, "type": "thumbnail" } ], "base": "https://cdn.openagenda.com/main/" }, ... } ``` ##### En écriture[​](#en-écriture "Lien direct vers En écriture") Une image peut être fournie par `URL` ou par fichier lors d'une opération de mise à jour ou de création. Elle doit être publiquement disponible pour pouvoir être chargée dans l'événement. Une fois chargée, elle sera convertie et redimensionnée pour être proposée selon les critères détaillés dans la section précédente. ###### Exemple[​](#exemple-5 "Lien direct vers Exemple") ``` { ..., "image": { "url": "https://i.pinimg.com/originals/d1/d9/ae/d1d9aec6e351baa115000b4b75e02b1b.jpg" } ... } ``` #### Crédits image[​](#crédits-image "Lien direct vers Crédits image") Crédits liés à l’illustration.
Champ optionnel qui ne peut être défini **que** lorsqu'une image est également définie. Ne peut excéder **255** caractères.
**code**: `imageCredits`
**type**: `texte` #### Outils d'inscription[​](#outils-dinscription "Lien direct vers Outils d'inscription") Liste des moyens d’inscription : numéros de téléphones, email ou liens hypertextes. Champ optionnel ne pouvant excéder 2000 caractères au total.
**code**: `registration`
**type**: liste de valeurs de type `link` (lien hypertexte), `phone` (numéro de téléphone) ou `email` (courriel) ##### Exemple en lecture[​](#exemple-en-lecture "Lien direct vers Exemple en lecture") ``` { ..., "registration": [ { "type": "link", "value": "https://formationcontinue.univ-rennes1.fr/cafeinfo" }, { "type": "email", "value": "formcont@univ-rennes1.fr" }, { "type": "phone", "value": "0203040506" } ], ..., } ``` ##### Exemple en écriture[​](#exemple-en-écriture "Lien direct vers Exemple en écriture") Le format suivant est accepté pour les opérations d'écritures. Les types dérivent des valeurs lues: ``` { ... "registration": [ "https://formationcontinue.univ-rennes1.fr/cafeinfo", "formcont@univ-rennes1.fr", "0203040506" ], ... } ``` #### Accessibilité[​](#accessibilité "Lien direct vers Accessibilité") Champ optionnel listant les codes correspondants aux types de handicaps pour lesquels des aménagements sont prévus dans le but rendre l'événement accessible.
**code**: `accessibility`
**type**: `objet` de codes d'accessibilité. ##### Codes[​](#codes "Lien direct vers Codes") * `hi` (Hearing impairment): Handicap auditif * `vi` (Visual impairment): Handicap visuel * `pi` (Psychic impairment): Handicap psychique * `mi` (Motor impairment): Handicap moteur * `ii` (Intellectual impairment): Handicap intellectuel ##### Exemple[​](#exemple-6 "Lien direct vers Exemple") ``` { ... "accessibility": { "hi":false, "ii":false, "vi":true, "mi":false, "pi":false }, ... } ``` #### Horaires[​](#horaires "Lien direct vers Horaires") Liste des plages horaires lors desquels l'événement à lieu.
Champ **obligatoire** ne devant pas excéder **800** plages horaires. Une plage ne peut excéder 24 heures en durée et ne peut chevaucher une autre plage.
**codes**: `timings`
**type**: `object[{begin: Date, end: Date}]`
**schema.org**: [eventSchedule](https://schema.org/eventSchedule) **Important**: le fuseau. Il est important. ##### Exemple[​](#exemple-7 "Lien direct vers Exemple") Une pièce de théatre qui a lieu tous les jours sur une semaine de 17h à 19h: ``` [ { "begin": "2026-02-23T17:00:00+0200", "end": "2026-02-23T19:00:00+0200" }, { "begin": "2026-02-24T17:00:00+0200", "end": "2026-02-24T19:00:00+0200" }, { "begin": "2026-02-25T17:00:00+0200", "end": "2026-02-25T19:00:00+0200" }, { "begin": "2026-02-26T17:00:00+0200", "end": "2026-02-26T19:00:00+0200" }, { "begin": "2026-02-27T17:00:00+0200", "end": "2026-02-27T19:00:00+0200" } ] ``` #### Âge du public ciblé[​](#âge-du-public-ciblé "Lien direct vers Âge du public ciblé") Créneau min/max d'âge des participants ciblés.
Champ optionnel, il n'est pas possible d'annoncer un événement adaptés aux personnes d'un âge supérieur à 120 ans.
**code**: `age`
**type**: `objet {min: entier, max: entier}`
**schema.org**: [typicalAgeRange](https://schema.org/typicalAgeRange) ##### Exemple[​](#exemple-8 "Lien direct vers Exemple") Valeur du champ âge pour un événement pour les enfants de 6 ans ou moins: ``` { ... "age": { "min":0, "max":6 }, ... } ``` #### Mode de participation[​](#mode-de-participation "Lien direct vers Mode de participation") Mode de participation à l’événement (physique/in-situ vs en ligne).
Par défaut, l'événement sera in-situ/physique (valeur `1`). **code**: `attendanceMode`
**type**: `entier(1|2|3)`
**schema.org**: [eventAttendanceMode](https://schema.org/eventAttendanceMode) ##### Valeurs possibles[​](#valeurs-possibles "Lien direct vers Valeurs possibles") * `1` (offline): Participation physique au lieu où se déroule l'événement * `2` (online): Participation en ligne via un lien * `3` (mixed): Participation mixte #### Identifiant de lieu[​](#identifiant-de-lieu "Lien direct vers Identifiant de lieu") Identifiant unique OpenAgenda du lieu associé à préciser dans les opérations d'*écriture*. En *lecture* c'est un objet `location` qui est fourni.
**Obligatoire** pour les événements dont le mode de participation est physique/offline (`1`) ou mixte (`3`). Sur les opérations de `lecture`, ce sont les informations détaillées dans [Lieux > Structure](https://developers.openagenda.com/lieux/structure.md) qui sont fournies.
**code**: `locationUid` en *écriture* ou `location.uid` en *lecture*.
**type**: `entier` #### Lien d'accès[​](#lien-daccès "Lien direct vers Lien d'accès") Lien hypertexte permettant l'accès à un événement en ligne ou mixte.
Champ **obligatoire** pour les événements dont le mode de participation (code `attendanceMode`) est *en ligne* (valeur `2`) ou *mixte* (valeur `3`). Champ non pertinent pour les événements physiques strictes.
**code**: `onlineAccessLink`
**type**: `lien hypertexte`
**schema.org**: [VirtualLocation](https://schema.org/VirtualLocation) #### Liens enrichis[​](#liens-enrichis "Lien direct vers Liens enrichis") Liste de paires de valeurs lien / code enrichi extraits de la description longue.
Ce champ est défini par un traitement interne à l'API. **code**: `links`
**type**: `[{link, data}]` ##### Exemple[​](#exemple-9 "Lien direct vers Exemple") ``` [ { "link": "https://fr.calameo.com/read/0000531370e47329f0819", "data": { "url": "https://www.calameo.com/read/0000531370e47329f0819", "type": "rich", "version": "1.0", "title": "Activités Petite Enfance - Vacances d'Hiver / 0-6 ans", "author": "Ville de Roubaix", "author_url": "https://www.calameo.com/accounts/53137", "provider_name": "calameo.com", "description": "Activités 0-6 ans Petite Enfance vacances d’Hiver...", "thumbnail_url": "https://p.calameoassets.com/210205112752-fc92911ad9.../p1.jpg", "thumbnail_width": 1125, "thumbnail_height": 1596, "html": "
", "cache_age": 86400 } } ] ``` #### Fuseau horaire[​](#fuseau-horaire "Lien direct vers Fuseau horaire") Nom du fuseau horaire de référence. Voir [la liste des identifiants TZ](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones).
Champ défini automatiquement à partir du lieu associé à l'événement pour les événements ayant un mode de participation `attendanceMode` physiques `1` ou mixtes `3`. Pour les événements en ligne sans lieu associée, la valeur par défaut prise par ce champ est `Europe/Paris`. **code**: `timezone`
**type**: `texte`
**exemple**: `Europe/Paris` #### État[​](#état "Lien direct vers État") L'état d'un événement informe l'utilisateur de sa disponibilité. Lorsque la valeur définie n'est pas la valeur par défaut (l'événement est programmé), l'information devient aussi essentielle que le titre. **code**: `status`
**type**: `entier(1|2|3|4|5|6)`
**valeur par défaut**: Programmé (`1`)
**schema.org**: [eventStatus](https://schema.org/eventStatus) ##### Valeurs[​](#valeurs "Lien direct vers Valeurs") * **Programmé** (`1`): État par défaut. L'événement est programmé aux horaires indiqués * **Reprogrammé** (`2`): Les horaires ont changé * **Déplacé en ligne** (`3`): L'événement qui se déroulait à un lieu physique n'est désormais accessible qu'en ligne * **Reporté** (`4`): L'événement ne se déroule plus aux horaires indiqués, les nouveaux horaires ne sont pas encore disponibles * **Complet** (`5`): L'événement n'est plus accessible aux nouveaux participants * **Annulé** (`6`): L'événement n'est plus programmé aux horaires indiqués et n'est pas reporté. #### Statut[​](#statut "Lien direct vers Statut") Indique le statut de l'événement dans le cadre du circuit de modération d'un agenda. L'événement n'est publiquement accessible que s'il a un statut à "Publié" (`2`). Les événements ayant un autre statut ne sont visibles que par les utilisateurs membres de l'agenda et ayant un rôle de **modérateur** ou d'**administrateur**. **code**: `state`
**type**: `entier(-1|0|1|2)` ##### Valeurs[​](#valeurs-1 "Lien direct vers Valeurs") * **Publié** (`2`): L'événement est affiché sur les flux et la page de l'agenda. * **Prêt à publier** (`1`): L'événement a été vu et traité par un membre modérateur ou administrateur. L'événement n'est visible que des membres autorisés. * **À modérer** (`0`): L'événement n'a pas encore été traité par un membre modérateur ou administrateur de l'agenda. L'événement n'est visible que des membres autorisés. * **Refusé** (`-1`): L'événement a été traité et a été refusé par un membre modérateur ou administrateur de l'agenda. En principe, un événement avec ce statut ne sera jamais publié sur l'agenda. #### Date de création[​](#date-de-création "Lien direct vers Date de création") Instant de la création de l'événement.
Ce champ n'est pas éditable. **code**: `createdAt`
**type**: `date` #### Date de mise à jour[​](#date-de-mise-à-jour "Lien direct vers Date de mise à jour") Instant de la dernière mise à jour de l'événement.
Ce champ n'est pas éditable. **code**: `updatedAt`
**type**: `date` ## Champs additionnels[​](#champs-additionnels "Lien direct vers Champs additionnels") Des champs additionnels peuvent venir compléter le modèle standard d'un événement OpenAgenda. Ils sont définis à l'échelle d'un agenda ou d'un réseau d'agendas. Pour en savoir plus, rendez-vous [ici](https://developers.openagenda.com/agendas/schemas.md). --- # Suppression d'un événement ## Méthode usuelle[​](#méthode-usuelle "Lien direct vers Méthode usuelle") ``` DELETE /v2/agendas/{agendaUID}/events/{eventUID} ``` ### En bref[​](#en-bref "Lien direct vers En bref") * `agendaUID` est l'identifiant unique de l'agenda où l'événement est référencé, `eventUID` est son identifiant unique * Une [authentification](https://developers.openagenda.com/authentification.md) en écriture par jeton d'accès est requise * La réponse contient les valeurs associées au lieu supprimé sous une clé `event` Deux cas de figure se présentent: 1. L'agenda est *l'agenda d'origine* de l'événement: l'événement est supprimé s'il a été contribué sur l'agenda. 2. L'agenda n'est pas *l'agenda d'origine*, l'événement a été ajouté par partage ou par agrégation: il est alors simplement retiré. ## Suppression par un identifiant externe à OpenAgenda[​](#suppression-par-un-identifiant-externe-à-openagenda "Lien direct vers Suppression par un identifiant externe à OpenAgenda") ``` DELETE /v2/agendas/{agendaUID}/events/ext/{key}/{value} ``` Rendez vous [ici](https://developers.openagenda.com/evenements/structure.md#identifiants-externes) pour en savoir plus sur les identifiants externes. --- # Lieux ``` [GET/POST/PATCH/PUT/DELETE] /v2/agendas/${agendaUID}/locations ``` Tout événement dont le mode de participation est soit In situ soit Mixte doit comporter une référence à un lieu qui est un objet à part entière sur OpenAgenda: chaque agenda dispose d'un référentiel de lieux. Le détail sur la structure d'un lieu ainsi que les opérations possibles est donné dans les pages suivantes: * [Structure](https://developers.openagenda.com/lieux/structure.md): détails des champs constitutifs d'un lieu. * [Lecture](https://developers.openagenda.com/lieux/lecture.md): Lire des données de lieux d'un agenda. * [Création](https://developers.openagenda.com/lieux/creation.md): Créer un lieu sur un agenda. * [Édition](https://developers.openagenda.com/lieux/edition.md): Mettre à jour complètement ou partiellement un lieu sur un agenda. * [Suppression](https://developers.openagenda.com/lieux/suppression.md): Supprimer un lieu. ## Quelques exemples[​](#quelques-exemples "Lien direct vers Quelques exemples") Voici quelques lieux présents sur OpenAgenda. ### Archives départementales du Nord[​](#archives-départementales-du-nord "Lien direct vers Archives départementales du Nord") ``` { "uid": 72236530, "setUid": 59170, "slug": "archives-departementales-du-nord_1054862", "name": "Archives départementales du Nord", "address": "22, rue Saint-Bernard - Lille", "countryCode": "FR", "adminLevel1": "Hauts-de-France", "adminLevel2": "Nord", "adminLevel3": "Métropole Européenne de Lille", "adminLevel4": "Lille", "city": "Lille", "adminLevel5": null, "adminLevel6": "Wazemmes", "district": "Wazemmes", "postalCode": "59037", "insee": "59350", "latitude": 50.620123, "longitude": 3.042688, "region": "Hauts-de-France", "department": "Nord", "timezone": "Europe/Paris", "updatedAt": "2023-07-24T08:44:48.000Z", "createdAt": "2023-02-21T10:55:50.000Z", "description": {}, "website": "http://www.archivesdepartementales.lenord.fr", "email": "archivedep@lenord.fr", "phone": "0359730600", "links": [], "access": {}, "state": 0, "imageCredits": null, "extIds": null } ``` ### Musée de Metz[​](#musée-de-metz "Lien direct vers Musée de Metz") ``` { "uid": 13131110, "setUid": null, "slug": "musee-de-metz-la-cour-dor_2769859", "name": "Musée de Metz - La Cour d'Or", "address": "2 rue du haut poirier, 57000 Metz, France", "countryCode": "FR", "adminLevel1": "Grand Est", "adminLevel2": "Moselle", "adminLevel3": "Eurométropole de Metz", "adminLevel4": "Metz", "city": "Metz", "adminLevel5": "Bellecroix", "adminLevel6": "Bellecroix", "district": "Bellecroix", "postalCode": "57000", "insee": "57463", "latitude": 49.121009, "longitude": 6.178047, "region": "Grand Est", "department": "Moselle", "timezone": "Europe/Paris", "updatedAt": "2025-07-23T08:53:55.000Z", "createdAt": "2025-04-16T17:35:11.000Z", "image": "https://cdn.openagenda.com/main/location13131110.a3bfef9ede4a4029836244131a345ef5.jpg?_ts=1753260834908", "description": { "fr": "Les salles du musée d'histoire et d'archéologie regroupent des collections issues du patrimoine local de l'Antiquité jusqu'à la Renaissance. Des ensembles d'exception illustrent la période gallo-romaine : les thermes antiques, des stèles funéraires sculptées, une colonne à l'anguipède, un autel dédié à Mithra, de nombreux objets de la vie quotidienne ; le département médiéval illustre environ un millénaire d'art et d'histoire. On peut admirer : les tombes mérovingiennes, la statuaire présentée dans le Grenier de Chèvremont, les trésors médiévaux de la salle de l'an Mil, le chancel de l'église Saint Pierre aux Nonnains. La collection d'architecture révèle des vestiges civils et religieux dans un cadre atypique. Le visiteur doit également remarquer les éléments du décor intérieur comme les plafonds peints et le mobilier. La collection de beaux-arts réunit de nombreuses œuvres issues de mouvements artistiques différents : les œuvres de plusieurs écoles européennes (française, allemande, flamande, hollandaise) s'étendant du XVIe au XXe siècle, les œuvres des artistes de l'École de Metz." }, "website": "https://musee.metzmetropole.fr", "email": "musees@metzmetropole.fr", "phone": "0387201320", "links": [], "access": {}, "state": 1, "imageCredits": "© La Cour d'Or-Musée de Metz", "extIds": [ { "key": "default", "value": "62adc12a-3316-5d66-9e6f-ca989ada7a13?dc93fb2a-806a-45dc-90ed-b72324c12e69" } ] } ``` --- # Création d'un lieu ``` POST /v2/agendas/{agendaUID}/locations ``` ## En bref[​](#en-bref "Lien direct vers En bref") * `agendaUID` est l'identifiant unique de l'agenda où le lieu est référencé * Une [authentification](https://developers.openagenda.com/authentification.md) en écriture par jeton d'accès est requise * Si les coordonnées du lieu ne sont pas précisées, un géocodage sera effectué en amont de l'opération de création du lieu. * Les données définissant le lieu sont à placer directement dans le corps de requête, elles sont détaillées [ici](https://developers.openagenda.com/lieux/structure.md). Le `Content-Type` doit être de type `application/json`. * La réponse contient le détail du lieu créé sous une clé `location` * Si une image est chargée avec le lieu, le `Content-Type` doit être de type `multipart/form-data`, auquel cas les données du lieux sont à encoder en JSON et placés sous une clé `data`, l'image étant un fichier placé sous la clé `image`. ## Exemples[​](#exemples "Lien direct vers Exemples") ### Création avec image[​](#création-avec-image "Lien direct vers Création avec image") #### node.js[​](#nodejs "Lien direct vers node.js") Exemple avec `POST` en encodage `multipart/form-data` où une image est chargée avec le lieu: ``` import FormData from 'form-data'; import axios from 'axios'; import getImageURL from './getImageURL.js'; import getAccessToken from './getAccessToken.js'; import getAgendaUID from './getAgendaUID.js'; const form = new FormData(); const imageURL = getImageURL(); const accessToken = getAccessToken(); const agendaUID = getAgendaUID(); form.append('data', JSON.stringify({ name: 'Théâtre Beaulieu', address: '9 bis Bd François Blancho, 44200 Nantes', countryCode: 'FR', imageCredits: `Le nom de l'auteur`, })); const { data: imageStream } = await axios({ method: 'get', url: getURLEncoded(imageURL) , responseType: 'stream', }); form.append('image', imageStream); const { data: { location: createdLocation } } = await axios({ method: 'post', url: `https://api.openagenda.com/v2/agendas/${agendaUID}/locations`, headers: { ...form.getHeaders(), 'access-token': accessToken, }, data: form, }); ``` ### Création sans image[​](#création-sans-image "Lien direct vers Création sans image") #### node.js[​](#nodejs-1 "Lien direct vers node.js") Exemple avec `POST` en encodage `application/json`: ``` import axios from 'axios'; import getImageURL from './getImageURL.js'; import getAccessToken from './getAccessToken.js'; import getAgendaUID from './getAgendaUID.js'; const { data: { location: createdLocation } } = await axios({ method: 'post', url: `https://api.openagenda.com/v2/agendas/${getAgendaUID()}/locations`, headers: { 'access-token': getAccessToken(), 'content-type': 'application/json' }, data: { name: 'Théâtre Beaulieu', address: '9 bis Bd François Blancho, 44200 Nantes', countryCode: 'FR', imageCredits: `Le nom de l'auteur`, }, }); ``` ## Création par un identifiant externe à OpenAgenda[​](#création-par-un-identifiant-externe-à-openagenda "Lien direct vers Création par un identifiant externe à OpenAgenda") ``` PUT /v2/agendas/{agendaUID}/locations/ext/{key}/{value} ``` \### En bref * `key` est le nom de l'identifiant, `value` sa valeur * Si le lieu existe déjà, il sera mis à jour * Un lieu peut être associé à plusieurs identifiants externes * Un lieu associé à un ou plusieurs identifiants externes garde un identifiant OpenAgenda unique (UID). ### Exemples[​](#exemples-1 "Lien direct vers Exemples") #### node.js[​](#nodejs-2 "Lien direct vers node.js") ``` import axios from 'axios'; import getImageURL from './getImageURL.js'; import getAccessToken from './getAccessToken.js'; import getAgendaUID from './getAgendaUID.js'; import getInfoNantesID from './getInfoNantesID.js'; const { data: { location: createdLocation } } = await axios({ method: 'put', url: `https://api.openagenda.com/v2/agendas/${getAgendaUID()}/locations/ext/infonantes/${getInfoNantesID()}`, headers: { 'access-token': getAccessToken(), 'content-type': 'application/json' }, data: { name: 'Théâtre Beaulieu', address: '9 bis Bd François Blancho, 44200 Nantes', countryCode: 'FR', imageCredits: `Le nom de l'auteur`, }, }); ``` --- # Édition d'un lieu ``` [POST/PATCH] /v2/agendas/${agendaUID}/locations/${locationUID} ``` ## En bref[​](#en-bref "Lien direct vers En bref") * `agendaUID` est l'identifiant unique de l'agenda où le lieu est référencé, `locationUID` est l'identifiant unique du lieu * Une [authentification](https://developers.openagenda.com/authentification.md) en écriture par jeton d'accès est requise * Les données définissant le lieu sont à placer directement dans le corps de requête, elles sont détaillées [ici](https://developers.openagenda.com/lieux/structure.md). Le `Content-Type` doit être de type `application/json`. * La réponse contient le détail du lieu mis à jour sous une clé `location` * La méthode `POST` est à utiliser pour les mises à jour complètes, `PATCH` pour les mises à jour partielles * Si une image est chargée avec le lieu, le `Content-Type` doit être de type `multipart/form-data`, auquel cas les données du lieux sont à encoder en JSON et placés sous une clé `data`, l'image étant un fichier placé sous la clé `image`. ## Exemples[​](#exemples "Lien direct vers Exemples") ### Mise à jour du nom d'un lieu[​](#mise-à-jour-du-nom-dun-lieu "Lien direct vers Mise à jour du nom d'un lieu") Le `PATCH` permet de cibler les données à modifier. #### node.js[​](#nodejs "Lien direct vers node.js") ``` import axios from 'axios'; import getImageURL from './getImageURL.js'; import getAccessToken from './getAccessToken.js'; import getAgendaUID from './getAgendaUID.js'; import getLocationUID from './getLocationUID.js'; const { data: { location: patchedLocation } } = await axios({ method: 'patch', url: `https://api.openagenda.com/v2/agendas/${getAgendaUID()}/locations/${getLocationUID()}`, headers: { 'access-token': getAccessToken(), 'content-type': 'application/json' }, data: { name: 'Maison des associations', }, }); ``` ### Mise à jour complète[​](#mise-à-jour-complète "Lien direct vers Mise à jour complète") ``` import axios from 'axios'; import getImageURL from './getImageURL.js'; import getAccessToken from './getAccessToken.js'; import getAgendaUID from './getAgendaUID.js'; import getLocationUID from './getLocationUID.js'; const { data: { location: updatedLocation } } = await axios({ method: 'post', url: `https://api.openagenda.com/v2/agendas/${getAgendaUID()}/locations/${getLocationUID()}`, headers: { 'access-token': getAccessToken(), 'content-type': 'application/json' }, data: { name: 'Site Gallo-Romain de la Croix-Guillaume', address: 'Saint-Quirin, 57560 Saint-Quirin, France', countryCode: 'FR', adminLevel1: 'Grand Est', adminLevel2: 'Moselle', adminLevel3: 'Communauté de communes Sarrebourg Moselle Sud', city: 'Saint-Quirin', postalCode: '57560', insee: '57003', latitude: 48.607757, longitude: 7.0963, timezone: 'Europe/Paris', description: { fr: 'Le site concentre sur un même plateau l\'ensemble des fonctions d\'un hameau antique : habitat, activités économiques, culte et nécropole. Il illustre l\'occupation des hauteurs vosgiennes à l\'époque gallo-romaine, du 1er au IIIe siècle après Jésus-Christ.', en: 'The site concentrates on the same plateau all the functions of an ancient hamlet: housing, economic activities, worship and necropolis. It illustrates the occupation of the Vosges heights during the Gallo-Roman period, from the 1st to the 3rd century AD.', it: 'Il sito concentra su un unico altopiano tutte le funzioni di un antico borgo: abitazione, attività economiche, culto e necropoli. Illustra l\'occupazione delle alture dei Vosgi in epoca gallo-romana, dal I al III secolo dopo Cristo.', de: 'Der Standort konzentriert auf einem einzigen Plateau alle Funktionen eines antiken Weilers: Wohnraum, wirtschaftliche Aktivitäten, Kult und Nekropole. Es veranschaulicht die Besetzung der Vogesen-Höhen in gallo-römischer Zeit, vom 1\\. bis zum 3\\. Jahrhundert nach Christus.', es: 'El sitio concentra en una misma meseta todas las funciones de un antiguo caserío: hábitat, actividades económicas, culto y necrópolis. Ilustra la ocupación de las alturas vosgiennes en la época galo-romana, del 1o al 3o siglo después de Cristo.' }, website: 'https://www.tourisme-sarrebourg.fr/sit/848143929-la-croix-guillaume/', email: 'an@email.com', phone: '0378959056', links: [], access: { fr: 'Situé à quelques kilomètres à l\'est du village, dans la forêt domaniale de Saint-Quirin, le site est accessible en voiture (10 mn de marche), ou bien à pied (3/4 d\'heure de St-Quirin). A pied, au départ de la mairie, en direction du plan d\'eau, suivre le balisage "anneau jaune" (circulaire des 7 roses) jusqu’au carrefour de la "Croix Guillaume", puis le GR5 sur 200m. En voiture, direction Lettenbach, Abreschviller. Au col de "Deux-Croix", prendre la route des "4 chemins". Se garer à l\'entrée du chemin de la "Croix Guillaume" et suivre le balisage "anneau jaune" jusqu\'au carrefour de la Croix Guillaume" puis le GR5 sur 200m. Le site est fléché.', en: 'Located a few kilometers east of the village, in the forest of Saint-Quirin, the site is accessible by car (10 minutes walk), or on foot (3/4 hour from St-Quirin). On foot, starting from the town hall, in the direction of the lake, follow the "yellow ring" (circular with 7 roses) until the crossroads of the "Croix Guillaume", then the GR5 for 200m. By car, direction Lettenbach, Abreschviller. At the "Deux-Croix" pass, take the "4 paths" road. Park at the entrance of the path "Croix Guillaume" and follow the signs "yellow ring" until the crossroads of Croix Guillaume" then the GR5 on 200m. The site is signposted.', it: 'Situato a pochi chilometri a est del villaggio, nella foresta demaniale di Saint-Quirin, il sito è accessibile in auto (10 minuti a piedi) o a piedi (3/4 ora da St-Quirin). A piedi, dal municipio, in direzione del lago, seguire il cartello "anello giallo" (circolare delle 7 rose) fino all\'incrocio della "Croix Guillaume", poi il GR5 su 200m. In auto, direzione Lettenbach, Abreschviller. Al passo di "Deux-Croix", prendere la strada dei "4 sentieri". Parcheggiare all\'ingresso del percorso "Croix Guillaume" e seguire la segnaletica "anello giallo" fino al bivio della Croix Guillaume" poi il GR5 a 200m. Il sito è puntato.', de: 'Das Hotel liegt ein paar Kilometer östlich des Dorfes, im Wald von Saint-Quirin, der Standort ist mit dem Auto (10 Minuten zu Fuß) oder zu Fuß (3/4 Stunde von St-Quirin). Zu Fuß, vom Rathaus in Richtung Gewässer, folgen Sie der Beschilderung "gelber Ring" (Kreis von 7 Rosen) bis zur Kreuzung des "Croix Guillaume", dann GR5 auf 200m. Mit dem Auto in Richtung Lettenbach, Abreschviller. Am Col de "Deux-Croix" die Route der "4 Wege" nehmen. Parken am Eingang des Weges "Croix Guillaume" und folgen der Beschilderung "gelber Ring" bis zur Kreuzung von Croix Guillaume", dann GR5 auf 200m. Die Website ist markiert.', es: 'Situado a pocos kilómetros al este del pueblo, en el bosque de Saint-Quirin, el sitio es accesible en coche (10 minutos a pie), o a pie (3/4 hora de St-Quirin). A pie, desde el ayuntamiento, hacia el plan de agua, siga la señalización "anillo amarillo" (circular de 7 rosas) hasta el cruce de la "Croix Guillaume", luego el GR5 a 200 metros. En coche, dirección Lettenbach, Abreschviller. En el paso de "Deux-Croix", tomar la carretera de los "4 caminos". Aparcar en la entrada del camino de "Croix Guillaume" y seguir el letrero "anillo amarillo" hasta el cruce de la Croix Guillaume" y luego el GR5 a 200 metros. El sitio está marcado.' }, state: 1 }, }); ``` ## Édition par un identifiant externe à OpenAgenda[​](#édition-par-un-identifiant-externe-à-openagenda "Lien direct vers Édition par un identifiant externe à OpenAgenda") ``` PUT /v2/agendas/{agendaUID}/locations/ext/{key}/{value} ``` Documenté [ici](https://developers.openagenda.com/lieux/creation.md#cr%C3%A9ation-par-un-identifiant-externe-%C3%A0-openagenda). --- # Lecture des lieux ## Lister[​](#lister "Lien direct vers Lister") ``` GET /v2/agendas/{agendaUID}/locations ``` ### En bref[​](#en-bref "Lien direct vers En bref") * `agendaUID` est l'identifiant unique de l'agenda où les lieux sont référencés * Une [authentification](https://developers.openagenda.com/authentification.md) en lecture ou par jeton d'accès est requise * La réponse contient un segment du référentiel complet des lieux de l'agenda. Si le total excède le nombre de lieux rendus en un appel, une boucle de lecture devra être mise en place. ### Paramètres[​](#paramètres "Lien direct vers Paramètres") #### Filtres[​](#filtres "Lien direct vers Filtres") | Clé | Type | Description | Valeurs possibles / Exemple | | ---------------- | ------ | ---------------------------------------------- | --------------------------------------------------- | | `updatedAt[gte]` | date | Retourne les lieux mis à jour après cette date | Format : `YYYY-MM-DD` ou `YYYY-MM-DDTHH:MM:SS+ZZZZ` | | `updatedAt[lte]` | date | Retourne les lieux mis à jour avant cette date | Idem | | `createdAt[gte]` | date | Retourne les lieux créés après cette date | Idem | | `createdAt[lte]` | date | Retourne les lieux créés avant cette date | Idem | | `search` | chaîne | Requête de recherche textuelle sur les lieux | Exemple : `"musée"` | | `state` | entier | Filtre par statut de vérification | `0` (non vérifié), `1` (vérifié) | #### Contenu[​](#contenu "Lien direct vers Contenu") | Clé | Type | Description | Valeurs possibles / Exemple | | ---------- | ------- | ---------------------------------- | --------------------------- | | `detailed` | booléen | Retourne tous les champs des lieux | `true` ou `false` | #### Navigation[​](#navigation "Lien direct vers Navigation") | Clé | Type | Description | Valeurs possibles / Exemple | | ------- | ------ | ----------------------------------- | ---------------------------------------------------------- | | `size` | entier | Nombre maximum de lieux à retourner | Exemple : `20` | | `after` | chaîne | Curseur pour pagination | Valeur fournie dans la réponse précédente (`after`) | | `order` | chaîne | Ordre de tri | `name.asc`, `name.desc`, `createdAt.asc`, `createdAt.desc` | ### Réponse[​](#réponse "Lien direct vers Réponse") Le corps de réponse présente trois clés: * `locations` : liste des lieux correspondant aux critères. * `total` : nombre total de résultats. * `after` : valeur à utiliser pour la page suivante. ## Lire un lieu[​](#lire-un-lieu "Lien direct vers Lire un lieu") ### Par son identifiant unique (uid)[​](#par-son-identifiant-unique-uid "Lien direct vers Par son identifiant unique (uid)") ``` GET /v2/agendas/{agendaUID}/locations/{locationUID} ``` La réponse contiendra toutes les données disponibles sur le lieu. **À noter**: pour se limiter à vérifier l'existence du lieu, utiliser la méthode `HEAD`, ce qui évitera un transfert de données inutile. ### Par un identifiant externe (extId)[​](#par-un-identifiant-externe-extid "Lien direct vers Par un identifiant externe (extId)") 1. Si aucune clé particulière n'est associée à l'identifiant externe (clé "default"): ``` /v2/agendas/{agendaUID}/locations/ext/{value} ``` 2. Si l'identifiant externe est associé à une clé ``` /v2/agendas/{agendaUID}/locations/ext/{key}/{velue} ``` --- # Structure d'un lieu Un lieu est un point de rencontre physique: un bâtiment, un lieu-dit, un espace ouvert... Voici la liste complète des champs définissant un lieu. | Champ | Code | Éditable | Requis | Description | | --------------------- | -------------- | -------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------- | | Identifiant | `uid` | | | Identifiant unique du lieu (non éditable) | | Nom du lieu ⁽ʳ⁾ | `name` | ✅ | ✅ | Texte (max. 100 caractères). Exemple : *Musée de la Folie Marco* | | Identifiants externes | `extIds` | ✅ | | Liste de clés/paires identifiant le lieu sur des jeux de données externes à OpenAgenda. Voir [ci-dessous](#identifiants-externes) pour des détails. | | Adresse ⁽ʳ⁾ | `address` | ✅ | ✅ | Texte (max. 255 caractères) | | Accès | `access` | ✅ | | Texte multilingue (max. 1000 caractères). Instructions d’accès (ex. `{ fr: "Métro 3, Pont de Levallois" }`) | | Description | `description` | ✅ | | Texte multilingue (max. 5000 caractères). Présentation du lieu (voir l’exemple pour Château de Villeneuve La Comtesse) | | Image | `image` | ✅ | | URL ou objet d’illustration du lieu | | Crédits image | `imageCredits` | ✅ | | Crédits liés à l’illustration | | Slug | `slug` | | | Identifiant textuel non éditable | | Jeu de lieu | `setUid` | | | Identifiant du jeu de lieux associé (non éditable) | | Ville | `city` | ✅ | | Ville ou commune | | Département | `department` | ✅ | | Département (pour lieux en France) | | Région | `region` | ✅ | | Région (pour lieux en France) | | Code postal | `postalCode` | ✅ | | Code postal | | Code INSEE | `insee` | ✅ | | Code INSEE de la commune | | Pays ⁽ʳ⁾ | `countryCode` | ✅ | ✅ | Code pays ISO 3166‑1 alpha 2 (ex. `CH`) | | Quartier | `district` | ✅ | | Quartier | | Latitude | `latitude` | ✅ | | Coordonnée géographique décimale (ex. `48.4102778`) | | Longitude | `longitude` | ✅ | | Coordonnée géographique décimale (ex. `7.4511111`) | | Fuseau horaire | `timezone` | ✅ | | Exemple : `Europe/Paris` | | Site web | `website` | ✅ | | URL principale | | Email | `email` | ✅ | | Adresse email de contact principale | | Téléphone | `phone` | ✅ | | Numéro de téléphone de contact principal | | Autres liens | `links` | ✅ | | Liste de liens hypertextes (ex. réseaux sociaux, site extérieur) | | Statut | `state` | ✅ | | Statut du lieu : `0` (à vérifier) ou `1` (vérifié) | | Date création | `createdAt` | | | Date de création (non éditable) | | Date mise à jour | `updatedAt` | | | Date de dernière mise à jour (non éditable) | | Identifiant externe | `extId` | | | **Déprequé**: référence au lieu un jeu de données externe à OpenAgenda | **(g)** généré automatiquement par géocodage si non fourni ## Identifiants externes[​](#identifiants-externes "Lien direct vers Identifiants externes") Il est possible d'associer à un lieu référencé sur OpenAgenda des identifiants autres que son identifiant unique (UID). Ce dernier est toujours défini et ne peut être édité. Les identifiants externes pour lier le lieux à des référentiels exterieurs à OpenAgenda. Par exemple, la donnée suivante montre un lieu qui porte une référence à la [base deslieux culturels du ministère de la Culture](https://basedeslieux.culture.gouv.fr/) ainsi qu'une autre d'un répertoire de la [métropole de Nantes](https://metropole.nantes.fr) ``` { ... "extIds": [{ "key": "MCCBLCID", "value": "62adc12a-3316-5d66-9e6f-ca989ada7a13?dc93fb2a-806a-45dc-90ed-b72324c12e69" }, { "key": "InfoNantes", "value": "7894" }], ... } ``` --- # Suppression d'un lieu ``` DELETE /v2/agendas/{agendaUID}/locations/{locationUID} ``` ## En bref[​](#en-bref "Lien direct vers En bref") * `agendaUID` est l'identifiant unique de l'agenda où le lieu est référencé, `locationUID` est l'identifiant unique du lieu * Une [authentification](https://developers.openagenda.com/authentification.md) en écriture par jeton d'accès est requise * La réponse contient les valeurs associées au lieu supprimé sous une clé `location` ## Suppression par un identifiant externe à OpenAgenda[​](#suppression-par-un-identifiant-externe-à-openagenda "Lien direct vers Suppression par un identifiant externe à OpenAgenda") ``` DELETE /v2/agendas/{agendaUID}/locations/ext/{key}/{value} ``` Rendez vous [ici](https://developers.openagenda.com/lieux/structure.md#identifiants-externes) pour en savoir plus sur les identifiants externes. --- # Les membres d'un agenda ## Lister[​](#lister "Lien direct vers Lister") Consulter les identifiants des membres d'un agenda ainsi que leur rôle et le détail de leurs fiches contact. ``` GET /v2/agendas/{agendaUID}/members ``` ## En bref[​](#en-bref "Lien direct vers En bref") * `agendaUID` est l'identifiant unique de l'agenda où les membres sont référencés * Une [authentification](https://developers.openagenda.com/authentification.md) en lecture ou par jeton d'accès est requise. * L'utilisateur authentifié doit être modérateur ou administrateur de l'agenda ## Navigation[​](#navigation "Lien direct vers Navigation") | Clé | Type | Description | | ----- | ------ | -------------------------------------------------------------------------------------------------------------- | | after | entier | Clé à fournir pour récupérer le jeu suivant. Elle est donnée dans la réponse du dernier appel reçu | | limit | entier | Définit le nombre de membres récupérés par appel. Valeur par défaut: **20**. Valeur maximale possible: **100** | ## Réponse[​](#réponse "Lien direct vers Réponse") | Clé | Type | Description | | ----- | -------- | --------------------------------------------------------------------------------- | | total | entier | Le nombre total de membres | | items | objet\[] | La liste des membres | | after | entier | Valeur à placer dans l'appel suivant pour récupérer le segment de membres suivant | Pour chaque item de la liste fournie, les informations suivantes sont données. | Clé | Type | Description | | ------------ | --------- | ----------------------------------------------------- | | uid | entier | Identifiant du membre | | name | texte | Nom d'utilisateur ou nom | | email | courriel | Courriel du membre | | phone | téléphone | Numéro de téléphone | | organization | texte | Organisme représenté | | role | texte | Rôle du membre: administrator, moderator, contributor | ## Inviter[​](#inviter "Lien direct vers Inviter") Inviter des utilisateurs à devenir membre d'un agenda. ``` POST /v2/agendas/{agendaUID}/members/invite ``` Les informations suivantes doivent être placées en corps de requête: * `role`: Obligatoire. Les valeurs possibles sont `contributor`, `moderator`, `administrator` * `emails`: Liste des emails à inviter * `message`: Optionnel. Le message d'invitation au format markdown. ### Réponse[​](#réponse-1 "Lien direct vers Réponse") | Clé | Type | Description | | --------- | -------- | ------------------------------------------------------------------------------------------------------------------ | | queued | entier | Le total d'invitations à traiter. Au delà d'un certain nombre d'emails, le traitement passe dans une tâche de fond | | processed | objet\[] | La liste des membres invités | #### Exemple d'un membre invité[​](#exemple-dun-membre-invité "Lien direct vers Exemple d'un membre invité") ``` { "userUid": null, "deletedUser": false, "name": null, "phone": null, "email": "gaetan.la@tou.ch", "position": null, "organization": null, "role": "moderator", } ``` --- # Portail node.js Une librairie node.js qui permet de déployer un portail événementiel en marque blanche. Elle est disponible sur [npm](https://www.npmjs.com/package/@openagenda/agenda-portal) et sur [githbub](https://github.com/OpenAgenda/oa-public/tree/main/agenda-portal). Quelques réalisations: * [L'agenda du Loiret](https://sortir.loiret.fr) * [Agenda de Senlis](https://agenda.ville-senlis.fr) * [Cap Métiers](https://agenda.cap-metiers.pro) --- # Extension Drupal Le module Drupal permet d'intégrer vos agendas hébergés chez directement sur votre site Drupal 8, 9 ou 10. Le code du module est disponible sur [drupal.org](https://www.drupal.org/project/openagenda). Une fois installé, l'intégrateur peut choisir les filtres à ajouter, personnaliser les gabarits et le style. Les filtres peuvent être ajoutés via des blocs présentés dans l'administration du site Drupal. Il est également possible de les intégrer directement via des codes HTML dans la page. Pour en savoir plus, cliquez ici: Quelques exemples d'implémentation: * [Métropole de Bordeaux](https://www.bordeaux-metropole.fr/agenda) * [Métropole de Nantes](https://metropole.nantes.fr/que-faire-nantes/agenda) * [Semaine de l'industrie](https://www.entreprises.gouv.fr/semaine-de-lindustrie) ![Installation sans personnalisation](/assets/images/integration-drupal-b05d8d64de7a3294ab82bfd95bdbd94f.png) *Installation sans personnalisation* --- # Code embed Ce code est disponible depuis la modale d'export de tout agenda publié sur OpenAgenda. Il permet d'intégrer simplement un agenda fonctionnel avec filtres, vue liste, vue détail sur un site. ![Modale d\'export d\'un agenda](/assets/images/embed-modal-82077b57bc4d251fec4b8f7ca074f21a.png) *Modale d'export d'un agenda* La modale permet de faire les ajustements les plus usuels. Cette documentation permet d'aller au delà en complétant le code de paramètres dont le fonctionnement est détaillé dans la section suivante. Suivent 2 cas d'usages qui illustrent comment arriver à certains résultats: 1. Comment ne pas rogner les images en vue liste. 2. Comment créer 2 variantes du codes pour permettre la navigation d'une prévisualisation sur une page d'accueil de site vers une page agenda détaillant l'intégralité d'une programmation. ## Paramètres[​](#paramètres "Lien direct vers Paramètres") Liste exhaustive des paramètres de configuration du code. ### Préciser l'URL de la page hébergeant l'agenda[​](#préciser-lurl-de-la-page-hébergeant-lagenda "Lien direct vers Préciser l'URL de la page hébergeant l'agenda") **Attribut**: `data-base-url` Cet attribut permet de préciser la page agenda vers laquelle seront orientés les utilisateurs lors d'un clic sur un événement de la liste. **Important :** L'URL précisée doit pointer vers une implémentation d'agenda existante: le code d'intégration se contente de renvoyer le visiteur cliquant sur une vignette événement vers ce lien, complété du code URL de l'événement. Ce fonctionnement est compatible avec une implémentation faite avec le [module Drupal](https://developers.openagenda.com/module-drupal/) ou la librairie [agenda-portal](https://www.npmjs.com/package/@openagenda/agenda-portal). En ajoutant l'attribut `data-base-url="https://mon-site.com/agenda"` au `
` du code d'intégration les événements seront ouverts dans un nouvel onglet sur la page `https://mon-site.com/agenda/slug-evenement`. Exemple : ```

Voir les événements de Fête de la musique 2024

``` En précisant **oa** comme valeur plutôt qu'une URL, le visiteur sera renvoyé vers le détail de l'événement sur [openagenda.com](https://openagenda.com) ### Préciser le mode d'ouverture des événements cliqués[​](#préciser-le-mode-douverture-des-événements-cliqués "Lien direct vers Préciser le mode d'ouverture des événements cliqués") **Attribut**: `data-base-url-target` Cet attribut spécifie si un événement doit s'ouvrir dans un nouvel onglet, la page parent ou le document le plus élevé si il y a plusieurs niveaux d'iframes, les valeurs possibles sont \_*blank*, *\_parent*, *\_top.* ```

Voir les événements de Fête de la musique 2024

``` ### Choix des filtres affichés[​](#choix-des-filtres-affichés "Lien direct vers Choix des filtres affichés") **Attribut**: `data-filters` Cet attribut permet de définir la liste de filtres à afficher dans l'intégration. Les codes à fournir, séparés par des virgules, sont les mêmes qu'utilisés en URL lorsque des filtres sont activés sur l'accueil de l'agenda ou sur son administration. Exemple : ```

Voir les événements de Limoges

``` ### Choix de la couleur primaire[​](#choix-de-la-couleur-primaire "Lien direct vers Choix de la couleur primaire") **Attribut**: `data-primary-color` Cet attribut permet de préciser une couleur principale qui sera utilisée dans l'intégration. Exemple où la couleur choisie est l'orange vif (#FF5733) ```

Voir les événements de Limoges

``` ### Ajustement des dimensions de la carte[​](#ajustement-des-dimensions-de-la-carte "Lien direct vers Ajustement des dimensions de la carte") **Attribut**: `data-map-size` Permet de spécifier une hauteur ou un ratio pour la carte. * **height**: Pour une hauteur fixe (ex: `data-map-size="height:400px"`) * **ratio**: Pour maintenir un ratio (ex: `data-map-size="ratio:16/9"`) * **maxHeight**: Avec le ratio, limiter à une hauteur maximale (ex: `data-map-size="ratio:16/9;maxHeight:400px"` ### Choix du tri des événements[​](#choix-du-tri-des-événements "Lien direct vers Choix du tri des événements") **Attribut**: `data-sort` Permet de spécifier le tri des événements affichés. La liste des possibles est donnée ici. **À noter**: quand une recherche texte est effectuée, le tri change et les résultats affichés sont donnés par ordre de pertinence. ### Cacher le logo[​](#cacher-le-logo "Lien direct vers Cacher le logo") **Attribut**: `data-logo` Permet de cacher le logo OpenAgenda lorsque la valeur "hide" est fournie à l'attribut. ### Affichage du total[​](#affichage-du-total "Lien direct vers Affichage du total") **Attribut**: `data-display-total` Permet de spécifier si le total d'événements affichés doit apparaitre en tête de liste. Il est affiché par défaut. Préciser "0" pour ne pas l'afficher. ```

Voir les événements de Limoges

``` ### Présentation des images[​](#présentation-des-images "Lien direct vers Présentation des images") **Attribut**: `data-image-list` Permet de contrôler l'apparence des images affichées dans le widget. Plusieurs valeurs agissant sur des aspects différents des images peuvent être précisées. Il faut alors les séparer par un point-virgule `;`. * **`contain` ou `cover`** : Correspond à la propriété CSS `object-fit`. * **`ratio`** : Définit le ratio d'aspect via `aspect-ratio` (exemple : `ratio:1` pour un carré). * **`maxHeight` ou `height`** : Contrôle la hauteur maximale ou fixe via `max-height` ou `height` (exemple : `maxHeight:400px`). Dans l'exemple ci-dessous, les images utiliseront le mode `contain` pour conserver leurs proportions et auront une hauteur maximale de 400 pixels. ```

Voir les événements de Limoges

``` Dans le prochain exemple, les images seront affichées en mode `cover` avec un ratio d’aspect carré (1:1). ```

Voir les événements de Limoges

``` ## Cas d'usage[​](#cas-dusage "Lien direct vers Cas d'usage") ### Ne pas rogner les images sur la vue liste[​](#ne-pas-rogner-les-images-sur-la-vue-liste "Lien direct vers Ne pas rogner les images sur la vue liste") Par défaut, le format des images est rogné, dans le but de normaliser la hauteur des vignettes affichées en vue liste. ![](/assets/images/embed-list-preview-7852ed7d81c869df94ac432292c247a2.png) Pour afficher les images dans un format non-rogné, il suffit d'ajouter un paramètre au code en précisant le mode d'affichage et la hauteur maximale de l'image: **data-image-list="contain;maxHeight:400px"** ### Afficher un aperçu sur sa page d'accueil d'une variante complète sur une page agenda de son site[​](#afficher-un-aperçu-sur-sa-page-daccueil-dune-variante-complète-sur-une-page-agenda-de-son-site "Lien direct vers Afficher un aperçu sur sa page d'accueil d'une variante complète sur une page agenda de son site") Le code d'intégration permet de simplement afficher une sélection d'événements en aperçu sur sa page d'accueil qui au clic renvoient vers une page agenda présentant une programmation plus complète. Pour créer un aperçu, 3 paramètres - documentés en détail dans la section précédente - seront utiles: * `data-display-total`: à "0" pour ne pas afficher le total dans l'aperçu * `data-base-url`: pour cibler la page où l'agenda est présenté * `&size=3` dans le lien de l'agenda pour ne présenter que 3 événements dans l'aperçu Voici un code pouvant être placé sur l'accueil d'un agenda. Il renverra les utilisateurs vers une page /agenda ou aura été placé le code de l'agenda intégré complet: ```

Voir les événements de Limoges

``` ## Configurer le gestionnaire de widgets OpenAgenda[​](#configurer-le-gestionnaire-de-widgets-openagenda "Lien direct vers Configurer le gestionnaire de widgets OpenAgenda") Le moyen le plus simple de créer un widget OpenAgenda pour sites Web (un agenda, un événement) consiste à copier et coller le code HTML généré dans la modale d'export. ### Pour des performances et une fiabilité optimales, incluez le script widgets.js dans votre modèle[​](#pour-des-performances-et-une-fiabilité-optimales-incluez-le-script-widgetsjs-dans-votre-modèle "Lien direct vers Pour des performances et une fiabilité optimales, incluez le script widgets.js dans votre modèle") Incluez le gestionnaire de widgets OpenAgenda une fois dans votre modèle de page pour optimiser les performances de votre page Web. Si votre site utilise plusieurs widgets, vous pouvez configurer une seule fois les widgets OpenAgenda dans vos pages, ce qui rendra votre site plus rapide. ``` ``` Cet extrait de code optimise le chargement de la manière suivante : * Attribue un identifiant (ID) HTML unique, `oa-wjs`, à l'élément pour vérifier facilement si le fichier JavaScript est déjà présent sur la page. Si cet ID existe déjà, le chargement est arrêté immédiatement. * Charge le JavaScript de OpenAgenda de manière asynchrone pour améliorer les performances des sites web. * Initialise une file d'attente de fonctions asynchrones pour stocker les fonctions dépendantes jusqu'à ce que le script soit disponible. * Place cet extrait avant tout autre JavaScript sur votre page qui pourrait dépendre de la file d'attente de fonctions asynchrones `oa.ready`. ### Ignorer les balises de script des intégrations[​](#ignorer-les-balises-de-script-des-intégrations "Lien direct vers Ignorer les balises de script des intégrations") Si vous incluez le chargeur JavaScript de Twitter sur chaque page, vous n'avez pas besoin d'inclure l'élément `