Un catalogue.
Tous vos écrans.
Le site utilise la même API que votre future application mobile. Un service indépendant, des identifiants stables et des réponses JSON documentées.
Votre première requête
Les prochaines sorties gratuites à Paris, avec dix résultats par page :
GET https://quoifaireaujourdhui.fr/api/v1/events
?city=75056
&when=upcoming
&price=free
&limit=10Les lectures publiques ne demandent pas de clé. Les identifiants des sources restent sur le serveur. L’API indépendante écoute sur le port 4016 en développement ; le site expose aussi un proxy sous /api/v1.
Les routes utiles
| GET /events | Rechercher et filtrer les sorties |
| GET /events/{id} | Une fiche avec toutes ses séances |
| GET /cities?q=lyon | Autocomplétion des communes |
| GET /cities/covered | Les villes actuellement alimentées |
| GET /sources | Provenance et actualisation |
| GET /stats | Compteurs réels du catalogue |
| GET /sync/status | Planification et suivi des actualisations |
| POST /submissions | Proposer un événement |
| POST /reports | Signaler une information erronée |
Une donnée explicite
priceType distingue gratuit, payant, gratuit sous conditions et inconnu. Les séances exposent start, end et une précision : horaire exact, début connu seul, date seule ou période. Les dates sont en UTC ; timezone donne le fuseau de l’événement.
Les filtres « aujourd’hui » et « ce week-end » suivent le fuseau de la commune. Sans commune, le fuseau de référence est Europe/Paris. Les périodes dont les horaires ne sont pas connus n’entrent pas dans les résultats d’un jour précis.
Avec precision: "start", seule l’heure de début est annoncée : end est une borne technique de fin de journée, à ne pas afficher comme une heure de fin. Ces séances quittent les recherches courantes après leur début, faute de durée connue.
Autour d’une position
Envoyez lat=48.86&lon=2.35&radius=10&sort=distance pour chercher dans un rayon de 10 km. Les deux coordonnées sont obligatoires ensemble et prennent la priorité sur la commune. Le fuseau horaire est celui de la commune la plus proche. Vous pouvez aussi utiliser city=75056&radius=25 pour partir du centre de Paris.
Chaque résultat comprend alors distanceKm, une estimation à vol d’oiseau. coordinatePrecision distingue le lieu réel du centre de commune quand cette information est disponible. Les réponses géolocalisées ne sont pas mises en cache. La position n’est pas enregistrée dans la base.
meta.categories donne les compteurs pour chaque catégorie avec les autres filtres actifs. Le tri date privilégie la prochaine séance ; distance privilégie la proximité lorsque le rayon est actif. « À venir » couvre les 365 prochains jours.
Pagination et limites
Les résultats comprennent data et meta : total, page, nombre de pages, limites du créneau et date de génération. La taille maximale est de 50 résultats ; la pagination est par numéro de page. Les événements pouvant changer entre deux appels, une page ne constitue pas un instantané durable.
Les lectures sont limitées à 180 requêtes par minute et par adresse réseau ; les contributions à 5 par heure. Les réponses peuvent être mises en cache 30 secondes. Les erreurs utilisent les codes HTTP 400, 404, 409, 422, 429 ou 500 et un objet JSON error.
Contributions et modération
Une contribution valide retourne un identifiant et le statut pending. Elle est persistée et attend une validation. Les routes /admin/submissions exigent un jeton administrateur de 32 caractères minimum, configuré sur le serveur.
Respecter les producteurs
Chaque fiche expose sa source, sa licence et sa date de récupération. Consultez les licences et la couverture avant de réutiliser les données ou les images dans une autre application.