La documentation de l'API Agenda Culturel vous permet de découvrir ce qu'il sera possible de faire avec nos outils. Pour obtenir une clé d'API vous devez en demander l'accès via ce formulaire. Pour toutes autres questions utilisez le formulaire de contact.

La clé d'API est une chaîne alphanumérique (lettres et chiffres) de 8 caractères. Elle est obligatoire pour toute requête sur l'API. Elle est le tout premier segment d'URL dans toute URL appelée.
https://api.agendaculturel.fr/qip8mak8

(Note : cette URL n'est présentée qu'à titre d'exemple : elle nécessite des segments d'URI supplémentaires pour fonctionner)
Une clé d'API absente ou non reconnue entraînera une erreur (cf. Erreurs).

Le format de données demandé est passé en second segment d'URL.
https://api.agendaculturel.fr/qip8mak8/json/[...]

(Note : cette URL n'est présentée qu'à titre d'exemple : elle nécessite des segments d'URI supplémentaires pour fonctionner)
Ce paramètre est obligatoire. Un format de données non reconnu entraînera une erreur.
Les formats acceptés par l'API sont : json.

Les catégories d'événements sont fixes, et au nombre de 7 : concert, théâtre, jeune public, danse, arts du spectacle et exposition.
Une requête par URL permet de remonter ces catégories :
http://api.agendaculturel.fr/qip8mak8/json/category

Détail des champs :

    cat_s : nom de la catégorie (qui serait affiché)
    nomcat : URI de la catégorie, à utiliser dans les URLs d'appel
    couleur : couleur héxadécimale illustrant la catégorie

Lors du choix de la ville par l'utilisateur, il entre progressivement les lettres de la ville qu'il souhaite rechercher.
La requête à effectuer est de la forme :
https://api.agendaculturel.fr/qip8mak8/json/citylist/<requête_entrée>

Par exemple, l'utilisateur cherchant "Amiens" tapera "a", puis "am", puis "ami". Pour cette dernière requête, on aurait une URL appelée de la forme :
https://api.agendaculturel.fr/qip8mak8/json/citylist/ami

Pour chaque saisie, on peut effectuer la requête, le résultat étant limité à 10 enregistrements. Si aucune ville n'est trouvée sur la recherche de l'utilisateur, l'objet cities est null.

Le résultat est un ensemble comprenant les champs suivants :

    id : ID de la ville
    ville : nom de la ville
    dep : nom du département, pour être affiché entre parenthèses avec la ville
 

Pour charger une liste de villes "par défaut", les villes les plus proches de ma position (latitude & longitude), il faut effectuer la requête suivante :
https://api.agendaculturel.fr/qip8mak8/json/geocities/<latitude,longitude>

Ce listing comprend les 10 villes les plus proches de la latitude/longitude entrée, dans un rayon de 50 Km, où il y a au moins un événement à venir. Le listing est ordonné par distance (croissante).

Le résultat comprend les champs suivants :

    id : ID de la ville
    ville : nom de la ville
    dep : nom du département, pour être affiché entre parenthèses avec la ville
    nb_events : nombre d'événements à venir dans cette ville
    distance : distance en kilomètres de cette ville par rapport à la position entrée

Une donnée de latitude & longitude dans un format incorrect entraînera une erreur (cf. Erreurs).

Limitation en excluant certaines villes de la requête

Il est possible de limiter le listing de villes les plus proches de ma position, en excluant certaines villes de la requête. Par exemple, pour ne pas afficher les villes qui ont déjà été sélectionnées par l'utilisateur. Pour cela, on ajoute un segment d'URL :
https://api.agendaculturel.fr/qip8mak8/json/geocities/<latitude,longitude>/<ID_villes_exclues>

Où ID_villes_exclues est l'ensemble des IDs de villes à exclure de la requête, séparés par des virgules.

Exemple :
https://api.agendaculturel.fr/qip8mak8/json/geocities/50.1097209,1.8277980/1,37,6,465

 
Limitation par catégories

On peut également passer dans l'URL les catégories d'événements sélectionnées par l'utilisateurs comme catégories à afficher, pour ne pas remonter par exemple une ville où il n'y a que des expositions, si Exposition ne fait pas partie des catégories à remonter. Car dans ce cas, le listing pour cette ville serait vide.
Pour cela, on ajoute un segment d'URL :
https://api.agendaculturel.fr/qip8mak8/json/geocities/<ID_villes_exclues>/<uri_categories>

Où uri_categories est l'ensemble des URIs séparées par des virgules (liste des types : voir Limitation du listing à une ou plusieurs catégories).

Exemple :
https://api.agendaculturel.fr/qip8mak8/json/geocities/50.1097209,1.8277980/1,37,6,465/concert,theatre,art-du-spectacle

 
Arguments optionnels

Il est possible de limiter (ou élargir) les résultats remontés dans les villes les plus proches de ma position.Ces arguments sont optionnels.

    distance_max : distance maximale de rayon dans lequel rechercher
    offset,limit : offset et limit, pour limiter ou élargir la requête, au format offset,limit

https://api.agendaculturel.fr/qip8mak8/json/geocities/50.1097209,1.8277980/1,37,6,465/concert,theatre/<distance_max>/<offset_limit>

Pour obtenir le listing des événements sur une ville donnée, l'ID de la ville doit être passé en 3è segment dans l'URL appelée.
Par exemple, "Amiens" ayant l'ID "2", on appelera alors l'URL :
https://api.agendaculturel.fr/qip8mak8/json/2

Comme la clé et le format, ce paramètre est obligatoire dans le cas d'un listing d'événements.
Un ID de ville non reconnu entraînera une erreur (cf. Erreurs).
Les événements remontés sont regroupés (GROUP BY) sur le champ nextdate, correspondant à la prochaine date pour un événement donné, à compter du jour courant.
De ce fait, un même événement peut remonter plusieurs fois dans un même listing, à plusieurs dates différentes.
Limitation du listing à une ou plusieurs catégories données

Il est possible de limiter un listing d'événements dans une ville à une ou plusieurs catégories. On distingue 7 catégories d'événements : concert, théâtre, festival, jeune public, danse, arts du spectacle, exposition.
Ce paramètre doit être passé en 4è segment d'URL, dans le cas d'un listing d'événements. Il est optionnel (à défaut, toutes les catégories seront remontées).
Pour limiter le listing souhaité à une ou plusieurs catégories données, on passe leurs URIs séparées par des virgules dans l'URL appelée. Ces URIs sont les suivantes :

    Concert : concert
    Théâtre : theatre
    Festival : festival
    Jeune public : jeune-public
    Danse : danse
    Arts du spectacle : arts-du-spectacle
    Exposition : exposition

Exemple d'URL pour un listing d'événements à Amiens (ID = 2), au format JSON, et ne regroupant que Concert, Théâtre et Exposition :
https://api.agendaculturel.fr/qip8mak8/json/2/concert,theatre,exposition

Une URI de catégorie non reconnue passée dans l'URL entraînera une erreur (cf. Erreurs).
Limitation du nombre d'événements remontés : offset et limit

Ce paramètre est optionnel, à l'image de la limitation du listing par catégories. Il est à entrer en 5è segment d'URL. S'il n'est pas renseigné, alors les 15 premiers événements à partir du premier trouvé seront remontés (équivalent à "0,15"). Le format à adopter pour ce paramètre est /offset,limit/ : les limit événements à partir de l'événement offset (système similaire au LIMIT x,y en SQL).
Par exemple, pour charger les 15 événements à partir du 30è trouvé :
https://api.agendaculturel.fr/qip8mak8/json/2/concert,theatre,exposition/30,15

Un mauvais paramètre entré entraînera une erreur (cf. Erreurs).

 
Les champs d'un événement dans un listing de ville

Chaque élément d'un listing, correspondant à un événement, comporte les champs suivants :

    id_agenda : ID de l'événement
    titre : titre de l'événement
    description : description de l'événement (format HTML avec limitation des balises autorisées)
    gratuit : 1 si événement gratuit - url_resa : lien HTTP d'affiliation pour le bouton "Réserver"
    visuel : chemin absolu vers le visuel de l'événement, redimensionné aux dimensions définies dans l'API
    cat_url : URI de la catégorie (cf. Catégories)
    couleur : couleur hexadécimale de la catégorie
    cat_nom : nom de la catégorie (nom qui serait affiché)
    date_debut : date de début de l'événement
    date_fin : date de fin de l'événement
    etat : "ok" = événement validé à venir, "annule" = événement annulé
    nextdate : prochaine date à venir pour cet événement
    lieu : libellé du lieu où se déroule cet événement
    sponsored : 1 si événement "mis en avant"
    artistes : liste des noms d'artistes pour cet événement, séparés par des virgules
    nb_artistes : nombre d'artistes concernés
 

Pour obtenir le détail d'un événement, l'URL appelée doit être de la forme :
https://api.agendaculturel.fr/qip8mak8/json/event/id_agenda

Le segment d'URL /event/ est obligatoire et fixe, et le paramètre id_agenda doit être au format numérique.
Un paramètre ID événement dans un format non numérique ou correspondant à un événement inexistant entraînera une erreur (cf. Erreurs).
Les champs d'un détail d'événement

Chaque objet de détail d'événement comporte les champs suivants :

     id_agenda : ID de l'événement
    titre : titre de l'événement
    url_resa : lien HTTP d'affiliation pour le bouton "Réserver"
    date_debut : date de début de l'événement
    date_fin : date de fin de l'événement
    description : description de l'événement (format HTML avec limitation des balises autorisées)
    visuel : chemin absolu vers le visuel de l'événement, redimensionné aux dimensions définies dans l'API
    tarifmin : Tarif, sous forme de chaîne ("15.00", ou "10.00 à 12.00")
    dep : numéro de département
    id_ville : ID de la ville
    etat : "ok" = événement validé à venir, "annule" = événement annulé - heure1 à heure5 : horaires des différentes représentations (s'il y a lieu)
    inforesa : informations de réservation (texte)
    gratuit : 1 si événement gratuit
    arrondissement : numéro d'arrondissement (s'il y a lieu)
    url : URL absolue de l'événement sur AgendaCulturel.fr
    weight : note de l'événement (algo)
    lieux_lieu : libellé du lieu où se déroule cet événement
    lieux_adresse : adresse du lieu où se déroule cet événement
    cat_url : URI de la catégorie (cf. Catégories)
    couleur : couleur hexadécimale de la catégorie
    cat_nom : nom de la catégorie (nom qui serait affiché)
    villes_ville : nom de la ville
    villes_cp : code postal de la ville
    org_name : nom de l'organisateur de l'événement
    sponsored : 1 si événement "mis en avant"
    artistes : liste d'objets contenant les noms des artistes, ou null si aucun artiste référencé
    nb_artistes : nombre d'artistes concernés
    dates_inter : tableau contenant chaque date de représentation, avec le cas échéant des horaires spécifiques définies pour chaque jour. Si ces horaires sont renseignées pour un jour donné, alors pour ce jour les horaires à prendre en compte sont celles-ci, et non plus les heures par défaut heure1 à heure5.
    next_shows : tableau de chaînes de caractères, contenant les dates (en lettres) des prochaines représentations (limitées à 5).
 

Chaque événement se tient dans un lieu indexé dans la base de données, et chacun de ces lieux possède une information de latitude et de longitude.
Pour remonter les événements culturels du site en tenant compte d'un rayon géographique, on utilise une URL de la forme :
https://api.agendaculturel.fr/qip8mak8/json/geo/<latitude,longitude>/<distance>

    Le paramètre geo est obligatoire pour ce type de requête, et invariable
    Le paramètre latitude,longitude est obligatoire et doit être de la forme 49.897455,2.301060
    Le paramètre distance est obligatoire et s'exprime en Kilomètres. Il est le rayon de distance maximal pour lequel on souhaite remonter des événements.

La distance n'est pas nécessairement un nombre entier, elle peut être un nombre décimal de la forme 1.5. Une distance dans un format incorrect entraînera une erreur (cf. Erreurs)

Exception : Clé d'API auto-limitée à un rayon géographique :

Si vous disposez d'une clé d'API qui est auto-limitée à une position géographique, il est inutile d'entrer la latitude et la longitude dans l'URL.
Dans ce cas, l'URL est très simplifiée :
https://api.agendaculturel.fr/qip8mak8/json/geo/

Le listing d'événements résultant prendra alors automatiquement en compte les données GPS liées à votre clé d'API, ainsi que le rayon de distance.

 
Limitation du listing à une ou plusieurs catégories données

Ce paramètre est optionnel, et fonctionne exactement de la même manière que dans le cadre de la limitation du listing à une ou plusieurs catégories données dans un listing d'événements par ville.
Si ce segment d'URL n'est pas renseigné, toutes les catégories seront prises en compte et remontées.
Ce paramètre intervient en 6è segment d'URL.

Par exemple, pour les concerts + théâtre à 10km de ma latitude et longitude:

https://api.agendaculturel.fr/vz536fwz/json/geo/49.897455,2.301060/10/concert,theatre/

Une ou plusieurs URIs de catégories renseignées et non reconnues par l'application entraînera une erreur (cf. Erreurs).
Limitation du nombre d'événements remontés : offset et limit

Ce paramètre est optionnel, et fonctionne exactement de la même manière que dans le cadre de la limitation du listing à une ou plusieurs catégories données dans un listing d'événements par ville.
Si ce segment d'URL n'est pas renseigné, les 15 premiers événements à partir du premier enregistrement seront remontés (équivalent à "0,15").
Ce paramètre intervient en 7è segment d'URL.

Par exemple, pour les 20 concerts + théâtre, à partir du 10è trouvé, à 10km de ma latitude et longitude :
https://api.agendaculturel.fr/vz536fwz/json/geo/49.897455,2.301060/10/concert,theatre/10,30
Les champs d'un événement, dans un listing par positionnement GPS

Chaque élément d'un listing par positionnement GPS, correspondant à un événement, comporte les mêmes champs qu'un listing d'événements par ville. Cependant un champ supplémentaire est ajouté : la distance
Ainsi : voir Champs d'un événement dans un listing par ville, avec en complément :

    distance : distance en Kilomètres du lieu de l'événement, par rapport à la position actuelle de l'utilisateur
    id_ville : ID de la ville de l'événement
    ville : nom de la ville de l'événement  
 

Les visuels remontés dans les champs dédiés peuvent être retaillés "à la volée", en cas de besoin d'une dimension spécifique, ponctuellement. Il faut pour cela faire appel à une URL spécifique qui va générer un visuel de la taille désireé, et qui sera mis en cache sur le serveur :
https://api.agendaculturel.fr/static/im/thumb.php?src=<URL_absolue_image>&w=<largeur_max_pixels>&h=<hauteur_max_pixels>&zc=<bool_crop>

    URL_absolue_image : chemin absolu de l'image, tel qu'il est défini dans le champ du flux remonté
    largeur_max_pixels : (optionnel) valeur en pixels pour la largeur maximale souhaitée (si la largeur originale est inférieure, elle reste inchangée)
    hauteur_max_pixels : (optionnel) valeur en pixels pour la hauteur maximale souhaitée (si la hauteur originale est inférieure, elle reste inchangée)
    bool_crop : (optionnel) 1 ou 0. Si ce paramètre est à 1, l'image sera recadrée en fonction des dimensions souhaitées
 

Code d'erreur    Signification
Ax001     La clé d'API passée dans l'URL est incorrecte
Ax002     Le format de données demandé dans l'URL est inconnu
Ax003     Une ou plusieurs des catégories demandées dans l'URL sont inconnues ou dans un format invalide
Ax004     L'ID de la ville demandé dans l'URL correspond à une ville inconnue ou est dans un format invalide
Ax005     Le paramètre offset/limit "X,Y" est dans un format invalide
Ax006     L'identifiant de l'événement demandé est dans un format invalide
Ax007     L'événement demandé est introuvable
Ax008     Le billet du Mag' demandé est introuvable
Ax009     Les coordonnées 'latitude,longitude' passées dans l'URL sont incorrectes
Ax010     Le paramètre de rayon de distance passé dans l'URL est incorrect
Ax011     Une erreur PHP est survenue
Ax012     Un ou plusieurs caractères non autorisés ont été trouvés dans l'URI
Ax013     Un ou plusieurs ID de villes à exclure de la requête sont dans un format incorrect (non numérique)
Ax014     Le chargement du fichier XML pour l'écran d'accueil est impossible
Ax015     La requête demandée a renvoyé un résultat vide
Ax016     Les restrictions sur la clé d'API utilisée ne permettent pas de charger les informations pour la ville demandée
Ax017     Cette URI n'est accessible que pour les clés d'API restreintes à un rayon GPS donné
Ax018     La clé d'API ne permet pas d'accéder aux contenus de « Agenda Culturel Le Mag' »
Ax019     La clé d'API a été désactivée par Agenda Culturel