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 http://localhost:3016/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 n’est publiée que si son lien HTTPS public confirme le nom, la date et le lieu. Les contrôles automatiques refusent les textes contenant des coordonnées ou des liens, ainsi que les doublons. Une sortie acceptée retourne le statut approved et son slug public. Un refus renvoie une erreur 422. Les routes /admin/submissions exigent un jeton administrateur de 32 caractères minimum pour retirer une sortie après publication.
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.