API d’Allez viens

GET /v1/search

Rechercher des sorties (Où, Quand, Qui)

Un résultat par événement, avec sa prochaine séance dans la plage, le prix total pour le groupe et le nombre d’événements par valeur de filtre.

GET /v1/events/{slug}

Fiche d’un événement ou d’un lieu à visiter

Tout ce que montre la fiche : séances à venir, lieux avec la précision de leur adresse et le point d’arrivée, grille tarifaire et prix total pour le groupe demandé, organisateur, série. Un doublon fusionné répond 301 vers la fiche restante ; une fiche retirée ou supprimée répond 410.

GET /v1/organizers/{slug}

Page publique d’un organisateur

La structure (nom, commune, site, réseaux, vérifiée ou non), ses sorties à venir par date avec le prix pour le groupe demandé, et ses dernières sorties passées. Une structure fusionnée répond 301 vers celle qui reste ; une structure qui a demandé à ne plus être suivie répond 410.

GET /v1/venues/{slug}

Page publique d’un lieu

Un lieu (château, musée, salle des fêtes…) : ce qu’il y a à voir (labels, cadre), ses activités ouvertes au public avec leur état d’ouverture, ses événements à venir par date avec le prix pour le groupe demandé, qui le tient. Une ancienne adresse (lieu renommé ou fusionné) répond 301.

GET /v1/places

Autocomplétion du champ Où

Communes, quartiers et lieux dont le nom ressemble à la saisie, fautes et accents tolérés. Une commune hors zone est renvoyée avec isCovered à false.

GET /v1/places/{slug}

Une commune, une zone ou un département

Ce que montre une page de lieu : rattachements (département, zone, secteurs), communes couvertes voisines, rayon de « autour de ». Un ancien nom ou le nom officiel d’une intercommunalité répond 301 vers le lieu.

GET /v1/place-pages/{slug}

Tout ce que montre une page de lieu, en une requête

Le lieu (comme /v1/places/{slug}, avec `indexing`), les sorties de la page (comme /v1/search), les 60 prochains jours du lieu, les nombres de sorties des pages de période et, pour une commune, « autour ». Une facette inconnue répond 404 ; un ancien nom répond 301 vers le lieu.

GET /v1/nearest-town

La commune couverte la plus proche

Pour « me localiser » : la commune couverte la plus proche, à 30 km au plus ; null au-delà.

GET /v1/parse

Une phrase en filtres

Recherche en langage naturel : Claude traduit la phrase en paramètres de /v1/search (lieu, dates, groupe, catégories, budget…), jamais en résultats. Sans rapport, détournée ou trop lente : understood false, chercher les mots tels quels.

GET /v1/plan

Planifier un week-end (une à trois journées)

Une journée qui s’enchaîne par jour demandé : matin, pause de midi, après-midi, soir, une sortie par créneau (quatre au plus), choisies parmi les meilleurs résultats de la recherche avec les mêmes filtres, par un calcul déterministe : horaires des séances, heures d’ouverture et durée de visite, âges, budget du groupe, trajets estimés (« environ », sans service d’itinéraire), fini avant 18 h avec de jeunes enfants, abri s’il pleut. Chaque étape propose d’autres idées pour son créneau ; un créneau vide dit pourquoi.

GET /v1/now

En ce moment, autour d’un point ou d’une commune

Les séances en cours ou qui commencent dans les deux heures (une séance sans fin est comptée deux heures) et les lieux à visiter ouverts, autour de la position (jamais gardée) ou de ma commune, dans le rayon de la zone (15 km au plus). Chaque sortie dit où elle en est (« encore 40 min », « commence dans 25 min », « ferme bientôt ») et le trajet estimé à pied et en voiture (« environ », sans service d’itinéraire). Ordre : à l’abri d’abord s’il pleut, puis les plus proches, puis par heure. Peu ou rien : la suite de la journée. La même fenêtre est le raccourci when=now de /v1/search.

GET /v1/rental-venues

Trouver un lieu pour un événement

Les lieux qui accueillent un mariage, un anniversaire, un séminaire, une assemblée générale…, seulement ceux dont le profil de location est publié, autour d’une commune ou d’une position (jamais gardée), ou dans toute la France. Un critère écarte les lieux dont on sait qu’ils n’y répondent pas ; ceux dont la réponse est inconnue restent, après les autres, avec « unknown ». Ordre : correspondance aux critères, distance (par tranches de 5 km), complétude de la fiche, puis vie du lieu (événements publics accueillis). Aucune place payée n’entre dans cet ordre. Rien dans le rayon : « wider » dit combien de lieux un rayon plus large contient. Chaque lieu a sa page, avec son formulaire de demande.

GET /v1/selection

Le choix de la rédaction

La sélection de la semaine d’une zone, faite par l’équipe : un titre, un mot, et les sorties (identifiants à passer à /v1/search?ids=). Rien tant qu’elle n’est pas publiée.

GET /v1/ambassadors/picks

Les choix des ambassadeurs du coin

Les sorties choisies cette semaine par les ambassadeurs d’une zone (habitants choisis par l’équipe), chacune avec son pourquoi et qui l’a choisie (prénom, commune). Les sorties elles-mêmes viennent de /v1/search?ids=.

GET /v1/ambassadors/{slug}

Profil public d’un ambassadeur

Prénom, commune, quelques mots et les choix de la semaine. Seulement le profil que la personne a accepté de montrer.

GET /v1/pulse

Une zone en chiffres

Pour une zone ou un secteur : sorties des 30 prochains jours, communes où elles ont lieu, et celles qu’une source a confirmées ces dernières 24 heures. Agrégats seulement.

GET /v1/coverage

La carte de France

Les zones couvertes (statut, départements, centre, séances des 30 prochains jours) et le nombre de personnes en liste d’attente par département. Agrégats seulement.

GET /v1/sitemap

Pages à lister pour les moteurs de recherche

Zones couvertes et secteurs, départements, communes au-dessus du seuil d’indexation (3 sorties sur 60 jours), fiches publiées à venir avec leur dernière modification, organisateurs, et les pages publiées du centre d’aide avec leurs langues.

GET /v1/taxonomy

Familles, catégories et étiquettes

Les libellés des filtres de recherche. Change rarement : à mettre en cache une heure.

GET /v1/help

Accueil du centre d’aide

Pour un public (`audience`, les habitants par défaut) : ses guides « Pour bien démarrer » et ses articles principaux ; puis les catégories et leurs premiers articles. Un article pas encore traduit dans la langue demandée vient en français (`locale` le dit).

GET /v1/help/topics

Tous les sujets du centre d’aide

Les catégories et tous leurs articles. Avec `audience` : les articles de ce public seulement, ses catégories d’abord.

GET /v1/help/search

Chercher dans le centre d’aide

Dès la deuxième lettre : chaque mot compte (début d’un mot du titre, du résumé ou du texte), les articles qui en contiennent le plus d’abord.

GET /v1/help/categories/{slug}

Une catégorie du centre d’aide et ses articles

GET /v1/help/articles/{slug}

Un article du centre d’aide

Le texte en Markdown léger, sa catégorie, ses langues publiées et jusqu’à quatre articles liés. Sans traduction dans la langue demandée : le français, avec `isFallback`.

GET /v1/feeds/places/{file}

Agenda abonnable d’une commune, d’une zone ou d’un secteur (iCalendar)

Les séances des trois prochains mois (et de la semaine passée), 1 500 au plus, à ajouter dans Google Agenda, Apple Calendrier ou Outlook : identifiant stable par séance, SEQUENCE et LAST-MODIFIED à chaque changement, séance annulée gardée avec STATUS:CANCELLED, à relire toutes les 6 heures. Les lieux à visiter n’y sont pas. Accepte les filtres d’une page de lieu (famille, catégorie, gratuit, en famille, accessible, rendez-vous du pays).

GET /v1/feeds/organizers/{file}

Agenda abonnable d’un organisateur (iCalendar)

Les séances des trois prochains mois (et de la semaine passée), 1 500 au plus, à ajouter dans Google Agenda, Apple Calendrier ou Outlook : identifiant stable par séance, SEQUENCE et LAST-MODIFIED à chaque changement, séance annulée gardée avec STATUS:CANCELLED, à relire toutes les 6 heures. Les lieux à visiter n’y sont pas. Une structure qui a demandé à ne plus être suivie répond 410.

GET /v1/feeds/favorites/{file}

Agenda abonnable privé d’un compte (iCalendar)

Les séances des trois prochains mois (et de la semaine passée), 1 500 au plus, à ajouter dans Google Agenda, Apple Calendrier ou Outlook : identifiant stable par séance, SEQUENCE et LAST-MODIFIED à chaque changement, séance annulée gardée avec STATUS:CANCELLED, à relire toutes les 6 heures. Les lieux à visiter n’y sont pas. La clé est le jeton secret du compte (« Mon compte » → agenda) : le flux reprend ses sorties enregistrées et ses « J'y vais », n’est jamais mis en cache, et un jeton supprimé répond 410 (pour décrocher les agendas abonnés).

GET /v1/health

L’API répond

GET /v1/health/search

Le moteur de recherche répond (sonde sans clé, jamais en cache)

GET /v1/health/db

La base répond (sonde bornée, au plus une par 15 s, jamais en cache)

GET /v1/openapi.json

Cette spécification