professionnels_in_radius
Find liberal healthcare professionals within a given radius of coordinates, filterable by specialty code, type code, precision level, and deduplication.
Instructions
Recherche de professionnels de santé libéraux conventionnés dans un rayon géographique. Précision géo HYBRIDE depuis le géocodage BAN (Chantier C) : ~77 % des PS sont géolocalisés à l'adresse précise (rue/bâtiment, distance_km exacte au m près), ~23 % restent au centroïde commune (~3 km, repli pour adresses non géocodables — DROM, Monaco, CEDEX, lieux-dits). Lire geo_precision PAR résultat — ne pas présumer une précision uniforme. Codes type_ps Ameli présents en base (3) : '1' médecins, '2' auxiliaires médicaux (fourre-tout : IDE, kinés, sages-femmes, podologues, orthophonistes, orthoptistes, IPA), '5' chirurgiens-dentistes. Pour cibler une profession précise (ex: IDE seuls, kinés seuls, podologues seuls), passer par specialite_codes plutôt que type_ps_codes qui ratisse plus large. Liste exhaustive des codes spécialité disponibles via le tool lister_nomenclature(referentiel:'ameli_specialites'). Multi-sites : par défaut un PS exerçant sur N adresses apparaît N fois — utiliser dedupe_by_ps=true pour regrouper par praticien et lister les sites en sous-objet. Distance retournée en km vol d'oiseau (haversine PostGIS) — pour distance routière, croiser avec un service externe (OSRM, ORS). Chaque PS géolocalisé porte geo_precision ∈ {"adresse", "centroide_commune"} : "adresse" = coords BAN précises, distance_km exacte, classement individuel fiable ; "centroide_commune" = ~3 km, distance_km IDENTIQUE pour tous les PS d'une même commune (non discriminante intra-commune — filtre de zone uniquement, pas de classement/choix d'un PS individuel). Param precise_only (défaut false) : à true, exclut les PS au centroïde commune et ne renvoie que les ~77 % géocodés à l'adresse BAN (distance_km exacte) — recommandé pour les rayons courts (<3 km) et le classement intra-commune. PÉRIMÈTRE : libéraux conventionnés UNIQUEMENT. HORS PÉRIMÈTRE : médecins exclusivement hospitaliers/salariés, biologistes médicaux salariés en LBM, anatomopathologistes hospitaliers, médecins du travail, médecine légale. Pour effectifs tous statuts, voir Annuaire Santé ANS (RPPS, esante.gouv.fr) — non couvert par ce serveur. Source : Annuaire santé Ameli (Assurance Maladie), MAJ hebdomadaire. Réutilisation soumise à l'art. L.1461-2 CSP — citer la source et la date de sync.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| lat | Yes | Latitude du centre (WGS84). | |
| lon | Yes | Longitude du centre (WGS84). | |
| limit | No | Nombre max de résultats (1-500, défaut 100). Appliqué AVANT déduplication. | |
| radius_km | No | Rayon en km (0.1-50, défaut 5). | |
| dedupe_by_ps | No | Regrouper les entrées par praticien (nom + prénom + code spécialité) et lister chaque adresse d'exercice dans `sites[]`. Défaut false (comportement V0.4 historique : un PS multi-sites = N entrées). | |
| precise_only | No | Si true, exclut les PS au centroïde commune et ne renvoie que ceux géocodés à l'adresse BAN, à `distance_km` exacte (cf. description du tool pour la sémantique complète). Défaut false. | |
| type_ps_codes | No | Liste de codes type PS Ameli (3 valeurs présentes en base : '1' médecins, '2' auxiliaires médicaux fourre-tout — IDE/kinés/sages-femmes/podologues/orthophonistes/orthoptistes/IPA, '5' chirurgiens-dentistes). Pour cibler une seule profession, préférer `specialite_codes`. Si omis, tous types. | |
| specialite_codes | No | Liste de codes spécialité Ameli (ex: ['01'] MG, ['03'] cardio). Si omis, toutes spécialités. | |
| 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. |