{"openapi":"3.1.0","info":{"title":"Kranli : demandes de permis de construire en Suisse","version":"1.0.0","summary":"Les nouvelles demandes de permis de construire publiées en Suisse, par commune et par métier, en lecture libre.","description":"API publique en lecture de Kranli : les demandes de permis de construire publiées dans les cantons couverts (liste dans /cantons), classées par commune et par métier. Sans clé, sans inscription. CORS ouvert en lecture.\n\nRègles : seules les demandes publiées ces 90 derniers jours sont servies ; chaque demande porte sa source officielle et sa formule, à reprendre telles quelles quand tu republies une demande (portail fédéral : « Ceci n'est pas une publication officielle. Seules font foi les données du Portail des feuilles officielles que le SECO a pourvues d'une signature ou d'un cachet électroniques. »). Les métiers sont un classement de Kranli, pas une donnée officielle. Kranli n’est pas un service de l’État. Seule la publication officielle fait foi.\n\nPlafond d’appels par connexion (réponse 429 avec Retry-After au-delà) ; réponses en cache cinq minutes, avec ETag.\n\nAbonnement : Kranli sur abonnement : les matins où il y a du nouveau, les demandes de ton métier autour de ta commune, avec ce qu’en disent les registres publics du bâtiment, le suivi du statut et une fiche privée pour chaque chantier ; 19 CHF par mois ou 190 CHF par an, 7 jours d’essai. https://kranli.ch/inscription?src=api\n\nEnglish: public read-only API of Kranli, new Swiss building permit applications by municipality and trade, last 90 days only, no key needed. Always keep the official source and the \"formule\" field when you show an application. MCP server: https://kranli.ch/mcp","contact":{"name":"Kranli","url":"https://kranli.ch/developpeurs"},"termsOfService":"https://kranli.ch/fr/conditions/"},"servers":[{"url":"https://kranli.ch/api/v1","description":"Kranli"}],"externalDocs":{"description":"Page des développeurs et des agents d’IA","url":"https://kranli.ch/developpeurs"},"x-kranli":{"abonnement":"Kranli sur abonnement : les matins où il y a du nouveau, les demandes de ton métier autour de ta commune, avec ce qu’en disent les registres publics du bâtiment, le suivi du statut et une fiche privée pour chaque chantier ; 19 CHF par mois ou 190 CHF par an, 7 jours d’essai.","inscription":"https://kranli.ch/inscription?src=api","periode_max_jours":90,"mcp":"https://kranli.ch/mcp"},"tags":[{"name":"demandes","description":"Les demandes de permis de construire"},{"name":"referentiels","description":"Communes, métiers et cantons"}],"paths":{"/demandes":{"get":{"operationId":"listerDemandes","tags":["demandes"],"summary":"Les demandes de permis de construire, filtrées par commune, canton, métier et date","description":"Les plus récentes d’abord. Sans `depuis` ni `jours` : les 30 derniers jours. Un `depuis` plus ancien que 90 jours est ramené à la limite (dit dans `notes`).","parameters":[{"$ref":"#/components/parameters/commune"},{"$ref":"#/components/parameters/canton"},{"$ref":"#/components/parameters/metier"},{"$ref":"#/components/parameters/depuis"},{"$ref":"#/components/parameters/jours"},{"$ref":"#/components/parameters/rayon_km"},{"$ref":"#/components/parameters/limite"},{"$ref":"#/components/parameters/langue"}],"responses":{"200":{"description":"Les demandes trouvées","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReponseDemandes"}}},"headers":{"ETag":{"$ref":"#/components/headers/ETag"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"}}},"304":{"description":"Pas de changement depuis l’ETag envoyé dans If-None-Match."},"400":{"$ref":"#/components/responses/Invalide"},"404":{"$ref":"#/components/responses/CommuneInconnue"},"429":{"$ref":"#/components/responses/TropDeRequetes"}}}},"/communes":{"get":{"operationId":"chercherCommunes","tags":["referentiels"],"summary":"Trouver une commune par son nom ou son numéro postal","description":"Sans `q` : les communes qui ont le plus de demandes ces 30 derniers jours.","parameters":[{"name":"q","in":"query","required":false,"description":"Nom de la commune (« Sion », « Buchs AG ») ou numéro postal (« 1950 »).","schema":{"type":"string","maxLength":80}},{"$ref":"#/components/parameters/canton"},{"$ref":"#/components/parameters/langue"}],"responses":{"200":{"description":"Les communes trouvées","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReponseCommunes"}}},"headers":{"ETag":{"$ref":"#/components/headers/ETag"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"}}},"304":{"description":"Pas de changement depuis l’ETag envoyé dans If-None-Match."},"400":{"$ref":"#/components/responses/Invalide"},"429":{"$ref":"#/components/responses/TropDeRequetes"}}}},"/metiers":{"get":{"operationId":"listerMetiers","tags":["referentiels"],"summary":"Les dix familles de métiers et leurs demandes récentes","parameters":[{"$ref":"#/components/parameters/langue"}],"responses":{"200":{"description":"Les métiers","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReponseMetiers"}}},"headers":{"ETag":{"$ref":"#/components/headers/ETag"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"}}},"304":{"description":"Pas de changement depuis l’ETag envoyé dans If-None-Match."},"400":{"$ref":"#/components/responses/Invalide"},"429":{"$ref":"#/components/responses/TropDeRequetes"}}}},"/cantons":{"get":{"operationId":"listerCantons","tags":["referentiels"],"summary":"Les cantons couverts, leurs sources et leurs demandes récentes","parameters":[{"$ref":"#/components/parameters/langue"}],"responses":{"200":{"description":"Les cantons","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReponseCantons"}}},"headers":{"ETag":{"$ref":"#/components/headers/ETag"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"}}},"304":{"description":"Pas de changement depuis l’ETag envoyé dans If-None-Match."},"400":{"$ref":"#/components/responses/Invalide"},"429":{"$ref":"#/components/responses/TropDeRequetes"}}}},"/openapi.json":{"get":{"operationId":"decrireApi","tags":["referentiels"],"summary":"Cette description OpenAPI","responses":{"200":{"description":"Le document OpenAPI 3.1","content":{"application/json":{"schema":{"type":"object"}}}}}}}},"components":{"parameters":{"commune":{"name":"commune","in":"query","required":false,"description":"Identifiant (voir /communes), nom ou numéro postal de la commune.","schema":{"type":"string","maxLength":80},"example":"sion"},"canton":{"name":"canton","in":"query","required":false,"description":"Sigle officiel du canton.","schema":{"type":"string","enum":["AG","AI","AR","BE","BL","BS","FR","GE","GL","GR","JU","LU","NE","NW","OW","SG","SH","SO","SZ","TG","TI","UR","VD","VS","ZG","ZH"]},"example":"VS"},"metier":{"name":"metier","in":"query","required":false,"description":"Identifiant du métier (voir /metiers) ; quelques mots sont aussi compris (« pompe à chaleur », « Wärmepumpe », « heat pump »).","schema":{"type":"string","maxLength":80},"example":"chauffage-pompes-a-chaleur"},"depuis":{"name":"depuis","in":"query","required":false,"description":"Première date, AAAA-MM-JJ (ramenée à 90 jours au plus).","schema":{"type":"string","format":"date"}},"jours":{"name":"jours","in":"query","required":false,"description":"Nombre de jours en arrière (sans `depuis`).","schema":{"type":"integer","minimum":1,"maximum":90,"default":30}},"rayon_km":{"name":"rayon_km","in":"query","required":false,"description":"Avec `commune` : les communes dont le centre officiel est à moins de ce nombre de kilomètres.","schema":{"type":"integer","minimum":0,"maximum":50,"default":0}},"limite":{"name":"limite","in":"query","required":false,"description":"Nombre de demandes rendues.","schema":{"type":"integer","minimum":1,"maximum":100,"default":20}},"langue":{"name":"langue","in":"query","required":false,"description":"Langue des libellés (fr par défaut). Les descriptions restent dans la langue de la publication officielle.","schema":{"type":"string","enum":["fr","de","it","en","pt","sq","bs","tr","es"],"default":"fr"}}},"headers":{"ETag":{"description":"Empreinte de la réponse, à renvoyer dans If-None-Match.","schema":{"type":"string"}},"CacheControl":{"description":"public, max-age=300","schema":{"type":"string"}},"RetryAfter":{"description":"Secondes à attendre avant de réessayer.","schema":{"type":"integer"}}},"responses":{"Invalide":{"description":"Paramètre invalide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReponseErreur"}}}},"CommuneInconnue":{"description":"Commune introuvable (avec des suggestions)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReponseErreur"}}}},"TropDeRequetes":{"description":"Plafond d’appels atteint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReponseErreur"}}},"headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}}},"schemas":{"Kranli":{"type":"object","required":["abonnement","inscription"],"description":"L’abonnement de Kranli : alerte, enrichissements et fiche privée, réservés aux abonnés.","properties":{"abonnement":{"type":"string"},"inscription":{"type":"string","format":"uri"}}},"Enveloppe":{"type":"object","required":["periode_max_jours","avertissement","kranli"],"properties":{"periode_max_jours":{"type":"integer","const":90,"description":"Rien n’est servi au-delà de cette période."},"avertissement":{"type":"string"},"kranli":{"$ref":"#/components/schemas/Kranli"}}},"Source":{"type":"object","required":["code","libelle"],"properties":{"code":{"type":"string","examples":["portail","ge-sitg","fr-friac","gl-amtsblatt","regbl","ne-sitn"]},"libelle":{"type":"string"},"url":{"type":["string","null"],"format":"uri"}}},"MetierCourt":{"type":"object","required":["slug","libelle"],"properties":{"slug":{"type":"string","enum":["chauffage-pompes-a-chaleur","solaire-photovoltaique","fenetres-portes-vitrages","toiture-etancheite","facades-isolation","renovation-interieure","exterieurs-piscines","construction-neuve","genie-civil-reseaux","electricite-bornes"]},"libelle":{"type":"string"}}},"Demande":{"type":"object","required":["id","canton","date","date_nature","metiers","source","formule"],"properties":{"id":{"type":"string","description":"Identifiant de la publication ou du dossier officiel."},"commune":{"type":["string","null"]},"commune_slug":{"type":["string","null"]},"canton":{"type":"string"},"date":{"type":"string","format":"date"},"date_nature":{"type":"string","enum":["depot","publication","registre"],"description":"Date du dépôt (Genève, Fribourg), de la première publication (feuilles officielles), ou, pour « registre » (Vaud, Appenzell Rhodes-Intérieures, Argovie, en partie), date approchée de l’inscription d’un bâtiment neuf autorisé au registre fédéral des bâtiments : ni une date d’enquête, ni un délai."},"type":{"type":["string","null"],"description":"Type de procédure, tel que publié."},"description":{"type":["string","null"],"description":"Description officielle, dans la langue de la publication (registre fédéral des bâtiments : phrase écrite par Kranli d’après les codes du registre)."},"langue":{"type":"string","enum":["fr","de","it"]},"statut":{"type":["string","null"],"enum":["depose","en_examen","enquete","autorise","refuse","retire","irrecevable","renvoye","suspendu","chantier_ouvert","termine","decision",null]},"statut_libelle":{"type":["string","null"]},"fin_opposition":{"type":["string","null"],"format":"date","description":"Fin du délai d’opposition, quand la publication la donne."},"metiers":{"type":"array","items":{"$ref":"#/components/schemas/MetierCourt"},"description":"Classement de Kranli (commentaire, pas une donnée officielle)."},"lien_officiel":{"type":["string","null"],"format":"uri","description":"La publication officielle ; null pour le registre fédéral des bâtiments (aucun lien par bâtiment : les avis officiels de la commune sont sur sa page Kranli, champ page_commune)."},"page_commune":{"type":["string","null"],"format":"uri","description":"La page publique de la commune sur Kranli."},"source":{"$ref":"#/components/schemas/Source"},"formule":{"type":"string","description":"Mention à reprendre avec la demande (formule exacte des conditions du portail fédéral pour ses publications)."}}},"ReponseDemandes":{"allOf":[{"$ref":"#/components/schemas/Enveloppe"},{"type":"object","required":["demandes","total","depuis","jusqu_au"],"properties":{"demandes":{"type":"array","items":{"$ref":"#/components/schemas/Demande"}},"total":{"type":"integer","description":"Tous les éléments trouvés : demandes de permis et bâtiments du registre fédéral."},"total_demandes":{"type":"integer","description":"Les demandes de permis de construire parmi eux."},"total_registre":{"type":"integer","description":"Les bâtiments neufs autorisés du registre fédéral des bâtiments (Vaud, Appenzell Rhodes-Intérieures, Argovie, en partie) : pas des demandes."},"nombre":{"type":"integer"},"limite":{"type":"integer"},"depuis":{"type":"string","format":"date"},"jusqu_au":{"type":"string","format":"date"},"filtres":{"type":"object"},"notes":{"type":"array","items":{"type":"string"}}}}]},"Commune":{"type":"object","required":["slug","commune","canton"],"properties":{"slug":{"type":"string"},"commune":{"type":"string"},"canton":{"type":"string"},"canton_libelle":{"type":"string"},"distance_km":{"type":"integer"},"demandes_7j":{"type":"integer"},"demandes_30j":{"type":"integer"},"demandes_90j":{"type":"integer"},"page":{"type":["string","null"],"format":"uri"}}},"ReponseCommunes":{"allOf":[{"$ref":"#/components/schemas/Enveloppe"},{"type":"object","required":["communes"],"properties":{"communes":{"type":"array","items":{"$ref":"#/components/schemas/Commune"}},"nombre":{"type":"integer"}}}]},"Metier":{"type":"object","required":["slug","libelle"],"properties":{"slug":{"type":"string"},"libelle":{"type":"string"},"libelle_court":{"type":"string"},"libelles":{"type":"object","additionalProperties":{"type":"string"}},"demandes_7j":{"type":"integer"},"demandes_30j":{"type":"integer"},"demandes_90j":{"type":"integer"}}},"ReponseMetiers":{"allOf":[{"$ref":"#/components/schemas/Enveloppe"},{"type":"object","required":["metiers"],"properties":{"metiers":{"type":"array","items":{"$ref":"#/components/schemas/Metier"}},"notes":{"type":"array","items":{"type":"string"}}}}]},"Canton":{"type":"object","required":["canton","libelle"],"properties":{"canton":{"type":"string"},"libelle":{"type":"string"},"libelles":{"type":"object","additionalProperties":{"type":"string"}},"demandes_7j":{"type":"integer"},"demandes_30j":{"type":"integer"},"demandes_90j":{"type":"integer"},"derniere_publication":{"type":["string","null"],"format":"date"},"sources":{"type":"array","items":{"$ref":"#/components/schemas/Source"}}}},"ReponseCantons":{"allOf":[{"$ref":"#/components/schemas/Enveloppe"},{"type":"object","required":["cantons"],"properties":{"cantons":{"type":"array","items":{"$ref":"#/components/schemas/Canton"}}}}]},"ReponseErreur":{"allOf":[{"$ref":"#/components/schemas/Enveloppe"},{"type":"object","required":["erreur"],"properties":{"erreur":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"}}},"suggestions":{"type":"array","items":{"$ref":"#/components/schemas/Commune"}}}}]}}}}