Développeurs, médias, offices, assistants

Le catalogue des sorties, par programme

Recherche avec temps de trajet, fiches complètes, communes et catégories : en JSON, en widget, ou dans votre assistant.

  • Accès nominatif
  • Aucune donnée personnelle
  • Attribution incluse
curl -H "Authorization: Bearer szc_…" \
  "https://sortonzici.fr/api/v1/sorties?commune=44109&minutes=20"

{ "data": [ {
    "type": "evenement",
    "titre": "Comptines et tintamarre",
    "commune": { "nom": "Orvault", "code_insee": "44114" },
    "lieu": "Espace Anne Sylvestre",
    "categorie": { "code": "cat_famille", "libelle": "Famille et jeux" },
    "gratuit": false,
    "trajet_minutes": 10,
    "debut": "2026-09-28T09:30:00+02:00",
    …
  } ],
  "attribution": "Données : OpenAgenda (licence ouverte), …"
}

Une vraie réponse, abrégée.

Trois formes

Le même accès, selon ce que vous construisez

L'APIDu JSON pour votre application ou votre site : recherche, fiche, communes, catégories.

Le widgetUn bloc tout fait à coller dans une page, réglé depuis votre espace.

Le connecteur MCPPour qu'un assistant conversationnel réponde à partir du catalogue, avec les liens.

Le widget a sa propre page

Pour afficher l'agenda de votre territoire sans écrire de code : Agenda pour mon site.

L'accès est nominatif

Trois paliers, selon l'usage

Il n'y a pas d'API publique : nous ouvrons l'accès compte par compte, puis vous créez et révoquez vos clés vous-même. Ce n'est pas le contenu qu'on protège — il est public — c'est la machine qui le sert.

Découverte

10 requêtes / minute

2 clés · De quoi essayer et brancher un assistant personnel.

Standard

30 requêtes / minute

5 clés · Un site ou un service qui interroge régulièrement.

Partenaire

60 requêtes / minute

10 clés · Une relation établie : office de tourisme, collectivité, média.

Une requête par seconde et par clé, au plus

Chaque appel compose une recherche géographique complète, sur un hébergement mutualisé. Une page qui porte le widget vaut une requête : c'est l'échelle d'un affichage humain. Si votre usage sort de ces bornes, parlons-en plutôt que de les contourner.

Ce qui ne sort jamais

Un catalogue, pas des personnes

Aucune donnée personnelleNi compte, ni « j'aime », ni vues : l'API expose ce qui est déjà public sur le site.

Rien de ce qui a été déduitLes goûts appris par le moteur ne s'affichent nulle part, et aucun assistant ne peut les lire.

L'attribution voyageChaque réponse porte ses sources. La conserver est la seule contrepartie.

La référence

S'authentifier

La clé se présente en en-tête, au choix :

Authorization: Bearer szk_votre_cle
X-API-Key: szk_votre_cle

Le secret n'est montré qu'une fois, à la création : nous n'en gardons que l'empreinte, et nous ne pouvons pas vous le redonner. Perdue, une clé se révoque et se remplace.

Les points d'entrée

Tout est en lecture, sur https://sortonzici.fr/api/v1.

GET /sorties

La recherche. Une commune de départ est obligatoire : c'est elle qui donne les temps de trajet, et sans elle le classement n'a pas de sens.

Paramètre Valeur Défaut
commune le slug d'une commune (nantes) obligatoire
minutes temps de trajet maximum, 10 à 90 30
quand aujourdhui, demain, week-end, semaine, ou une date AAAA-MM-JJ sans contrainte
type evenement ou lieu les deux
a[] codes d'attributs, cumulables (cat_musique, bud_gratuit) aucun
q recherche libre —
page numéro de page 1
par_page 1 à 100 20

GET /sorties/{slug}

Une fiche complète : description, horaires détaillés, lieu, coordonnées, attributs, lien vers l'organisateur, source et licence.

GET /communes

La liste des communes couvertes, avec leur slug. Le paramètre q filtre par nom — c'est ce qu'il faut appeler avant /sorties quand on part d'un nom saisi par quelqu'un.

GET /categories

Les catégories et les attributs filtrables, avec leurs codes — ceux qui alimentent a[].

Ce qui ne sort jamais de l'API

Aucune donnée personnelle. Ni compte, ni « j'aime », ni décompte de vues, ni sortie à plusieurs. Les points d'entrée /api/v1 exposent ce qui est déjà public sur le site, rien de plus — une clé d'API branchée dessus ne peut rien apprendre de personne.

Le connecteur MCP est autre chose : il agit au nom de quelqu'un, et peut donc toucher à son compte si cette personne l'a accordé. C'est la différence entre consulter un catalogue et faire agir un assistant à sa place. Voir plus bas.

L'attribution voyage avec les données

Chaque réponse porte la mention des sources, et chaque fiche la sienne. Ce n'est pas une politesse : les licences ODbL et ouverte l'exigent, et une API qui laisserait à son utilisateur le soin de retrouver l'attribution fabriquerait des violations en série.

Vous devez la conserver partout où vous affichez ces données. C'est la seule contrepartie, et elle n'est pas négociable.

Le connecteur MCP

Le Model Context Protocol permet à un assistant conversationnel d'interroger un service directement. Le nôtre est à https://sortonzici.fr/mcp, en JSON-RPC 2.0, avec la même clé que l'API.

Le catalogue, toujours accordé :

  • chercher_sorties — la recherche, mêmes filtres que /sorties ;
  • detail_sortie — une fiche ;
  • communes — la recherche de commune, pour convertir un nom en slug.

Concrètement : « qu'est-ce qu'on peut faire à moins de vingt minutes de Guérande ce week-end, gratuit et à l'abri ? » devient une réponse fondée sur le catalogue, avec les liens.

Votre compte, si vous l'accordez. Quatre permissions séparées, à cocher une par une au moment de l'autorisation :

Permission Ce qu'elle ouvre
Chercher dans le catalogue Les trois outils ci-dessus. Données publiques.
Lire vos goûts et vos proches mes_gouts, mes_proches, mes_sorties_a_plusieurs
Aimer et écarter en votre nom noter_sortie
Organiser et voter en votre nom creer_sortie_a_plusieurs, voter

Un assistant qui compose une soirée n'a aucun besoin de poser des « j'aime » : lui donner l'écriture parce qu'il demande la lecture est le défaut qui rend tous les écrans d'accord illisibles. Vous décochez ce que vous ne voulez pas laisser, et ce qui n'est pas accordé n'existe pas pour le connecteur — les outils correspondants ne lui sont même pas montrés.

Ce qui ne sort jamais, quoi qu'on accorde : votre adresse e-mail, vos appareils, et ce que le moteur a déduit de vous. Les poids appris, les catégories inférées : ils orientent votre fil et ne s'affichent nulle part, pas même pour vous. Un assistant ne peut pas les lire, et il lui est explicitement demandé de ne pas les reconstituer.

Vos proches ne livrent que leur prénom et un identifiant, de quoi composer une sortie. Pas leur adresse, pas leur commune, pas leurs goûts — ces personnes-là n'ont rien autorisé, elles apparaissent parce que vous êtes liés.

Deux façons de s'authentifier, selon ce que votre client sait faire.

Avec une clé, en en-tête — la même que l'API. Pour les clients qui permettent de poser un en-tête : Claude Code, Cursor, un script à vous.

claude mcp add --transport http sortonzici https://sortonzici.fr/mcp --header "Authorization: Bearer szc_votre_cle"

Sans rien à copier, pour les connecteurs qui ne le permettent pas — celui de claude.ai, notamment. Donnez-lui l'adresse https://sortonzici.fr/mcp : il découvre notre serveur d'autorisation, s'y inscrit tout seul, et vous ouvre une page où vous donnez votre accord. Vous voyez ce qu'il pourra faire, vous autorisez, c'est branché.

L'accès reste nominatif dans les deux cas. N'importe quel logiciel peut s'inscrire — c'est le principe du protocole — mais s'inscrire ne donne rien : il faut qu'une personne autorise, et que cette personne ait elle-même l'accès à l'API. Le connecteur est un intermédiaire, jamais un ayant droit.

Un accès autorisé se retire à tout moment depuis l'écran « API » de votre compte, et le retrait est immédiat.

Les limites, et ce qui arrive quand on les touche

Le débit se compte par clé et par minute. Au-delà, les réponses passent en 429 avec le délai d'attente. Ce n'est pas une sanction : c'est ce qui garantit que le service tient pour les autres.

Une clé révoquée, un compte suspendu ou un droit retiré donnent 401. La réponse dit laquelle des trois.

Ce que nous demandons

  • Mettez les résultats en cache. Le catalogue bouge au rythme des publications, pas des secondes. Rappeler la même recherche toutes les minutes ne vous apprendra rien de neuf.
  • Ne reconstituez pas la base. Un usage de lecture est bienvenu, y compris volumineux. Aspirer le catalogue pour en faire un service concurrent ne l'est pas — c'est écrit dans les conditions d'utilisation.
  • Dites-nous ce que vous en faites. Pas par curiosité : savoir à quoi sert un accès est la seule façon de ne pas le casser en le faisant évoluer.

Demander un accès

Écrivez-nous en indiquant qui vous êtes, ce que vous voulez construire, et le volume que vous anticipez. Nous ouvrons l'accès et vous créez vos clés.

Dites-nous ce que vous construisez

Qui vous êtes, ce que vous voulez faire du catalogue, et le volume que vous anticipez. Nous ouvrons l'accès, vous créez vos clés.

Demander un accès