etablissements_finess_by_categorie
List health and social establishments from the FINESS registry by category, with optional filtering by department or commune.
Instructions
Liste des établissements FINESS par famille, avec filtre département ou commune optionnel. Pas de rayon — pour énumération exhaustive d'une zone administrative. 24 familles disponibles : mco, ssr, sld, had, psychiatrie, dialyse, ambulatoire, labo, imagerie, pharmacie, msp_cpts, ehpad, residence_autonomie, senior_accompagnement, ssiad, aide_domicile, handicap_enfants, handicap_adultes, addictologie, enfance_protection, pmi, hebergement_social, prevention_sante, groupement.
V0.19.0 : accepte nom_commune (string) comme alternative à code_insee (résolu via geo.api.gouv.fr). XOR strict — passer SOIT departement SOIT code_insee SOIT nom_commune (combinable avec departement qui agit alors comme hint de désambiguïsation pour homonymes type "Saint-Martin"). Aucun param zone = France entière (acceptée).
Source : FINESS / ANS (flux quotidien, ingéré le 1ᵉʳ et le 15 ; établissements EN SERVICE uniquement). Chaque résultat porte geo_precision: "adresse" dès que coords est présent (point WGS84 ANS ou point BAN de l'adresse, jamais un centroïde ; un établissement sans coords n'a pas de point connu et est invisible des recherches par rayon) et siret_ans (SIRET déclaré par l'ANS, fait brut non vérifié SIRENE — pour le verdict : reconcilier_finess_sirene / verifier_site_actif). Note : champ email toujours null (non exposé par FINESS public). Lentille : un filtre familles compte les établissements par leur catégorie FINESS principale. Les activités hébergées dans un site d'une autre catégorie (ex. plateau de biologie d'un hôpital sous famille=labo) ne sont pas comptées — voir le champ perimetre de la réponse. La famille imagerie renvoie le plus souvent 0 résultat (FINESS ne répertorie pas les cabinets d'imagerie).
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Nombre max de résultats (1-500, défaut 100). | |
| categorie | Yes | Famille FINESS recherchée (24 valeurs disponibles, voir enum). | |
| code_insee | No | Code INSEE de commune (5 caractères). Optionnel. XOR strict avec `departement` et `nom_commune`. | |
| departement | No | Code département INSEE (ex: '75', '2A', '2B', '971'). Métropole 2 caractères (Corse '2A'/'2B', pas '20'), DOM/TOM 3 caractères. Optionnel. Combinable avec `nom_commune` comme hint resolver (filtre les homonymes), sinon XOR strict avec `code_insee` et `nom_commune`. | |
| nom_commune | No | Nom officiel de commune (alternative à `code_insee`, V0.19). Ex: "Lille", "Saint-Étienne". Le serveur résout en interne via geo.api.gouv.fr. Si ambigu (ex "Saint-Martin" → 5 villes), retourne une erreur structurée avec candidates. Combinable avec `departement` comme hint de désambiguïsation. Abréviations type "St-Martin" non reconnues — utiliser le nom officiel complet. | |
| include_freshness | No | Si true, ajoute un champ `data_freshness` au payload (dans `query_metadata` si présent, sinon à la racine) listant, par source (FINESS, Ameli, RPPS, CDS, IRIS), la dernière ingestion réussie (`last_success_at`, `staleness_days`) ET la dernière fois que la donnée a réellement changé (`last_data_change_at`, `data_age_days` — un run court-circuité « fichier amont identique » compte comme succès mais ne rajeunit pas la donnée ; c'est `data_age_days` qui dit l'âge réel de ce qui est servi). Opt-in pour ne pas alourdir les payloads par défaut. Cache 5min côté serveur — coût négligeable. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| count | Yes | Nombre d'entrées retournées dans `results` (post-troncature). | |
| total | No | Effectif réel avant troncature. Présent sur les tools de nomenclature paginés (lister_*) : `count` = échantillon, `total` = total réel, re-appeler avec un `limit` supérieur si `truncated`. | |
| results | Yes | Entrées métier (shape spécifique au tool, cf. description du tool). | |
| freshness | No | Fraîcheur des sources (présent si `include_freshness: true`). | |
| perimetre | No | Lentille de la source : ce que le comptage inclut/exclut. Lire `completeness_note` et la restituer au lecteur final. | |
| truncated | No | true si le total réel dépasse `limit` (re-paginer via `offset` si supporté, ou augmenter `limit` sur les lister_*). Optional sur les tools de listing exhaustif (lister_*). | |
| query_metadata | No | Metadata de la query (radius_km, departement, filtres appliqués, …). | |
| activite_hebergee | No | Compte juxtaposé des sites hébergeant l'activité correspondant à la famille filtrée, sous une autre catégorie FINESS. Distinct du `count` principal — lire `note` pour comprendre la sémantique et ne JAMAIS additionner les deux comptes sans préciser leur nature. |