Couche de données d'une carte dsfr-data-map : markers, zones géographiques (geoshape), cercles proportionnels ou heatmap. Chaque couche est connectée à sa propre source — le multi-source est naturel.

Attributs

Source et géolocalisation

Sans lat-field/geo-field, la couche auto-détecte les champs geo_point_2d, geopoint, geo_point (points) puis geo_shape, geometry, geom (formes).

Couche geoshape sans geo-field (#1053) : la couche trace la première colonne geo_shape, geometry ou geom qui porte du GeoJSON, objet ou chaîne sérialisée, sur l'une des vingt premières lignes. geo_point_2d n'est jamais retenu pour tracer des formes : un jeu Opendatasoft porte le point et la forme, et c'est la forme qui est dessinée. Les Feature d'une source transform="features" sont lues par leur geometry. La colonne détectée est nommée dans l'avertissement des lignes ignorées. Si aucune ne convient, la couche ne trace rien et le dit en console (« aucune colonne géométrique détectée ») : poser alors geo-field. Le calcul d'emprise (bbox) garde sa propre détection, qui commence par geo_point_2d : voir bbox-field.

Affichage

Symboles proportionnels : l'échelle du rayon

radius-field fait varier le rayon des cercles (type="circle") selon un champ numérique. radius-scale dit comment :

• linear (défaut) — le rayon suit la valeur, de radius-min pour la plus petite à radius-max pour la plus grande. La plus petite valeur a donc toujours un cercle, même quand elle vaut zéro, et une valeur dix fois plus grande peut occuper jusqu'à cent fois plus de surface. Convient à un indice ou à un rang, pas à une quantité.
• sqrt — l'aire du cercle est proportionnelle à la valeur, et l'échelle est ancrée à zéro : rayon = radius-max × √(valeur / plus grande valeur). Une valeur quatre fois plus grande a un rayon double ; la plus grande prend radius-max.

Pour des symboles proportionnels, utilisez radius-scale="sqrt" : l'œil compare des surfaces, pas des rayons. L'échelle linéaire reste le défaut pour que les cartes existantes ne bougent pas.

En sqrt :

• une valeur nulle, négative ou absente a un rayon nul — le cercle se réduit à un point d'un pixel, qui reste cliquable et compté ; les valeurs négatives sont signalées en console (une aire ne représente pas une valeur négative) ;
• radius-min est sans effet : un plancher fausserait le rapport des petites valeurs. Si les plus petits cercles sont illisibles, relevez radius-max ;
• les rayons sont tracés au pixel entier : avec radius-max="30", les valeurs 1, 4 et 100 donnent 3, 6 et 30 px ;
• l'échelle se cale sur les éléments tracés (après max-items) et se recalcule à chaque nouvelle donnée : un filtre amont change la plus grande valeur, donc la taille de tous les cercles.

radius-scale ne s'applique pas avec radius-unit="m", où le champ donne directement un rayon en mètres. Une valeur inconnue (radius-scale="log") est signalée en console et l'échelle linéaire s'applique.

<dsfr-data-map-layer source="musees" type="circle" geo-field="position"
  radius-field="entrees" radius-scale="sqrt" radius-max="30"
  color="#000091" fill-opacity="0.4" tooltip-field="nom"></dsfr-data-map-layer>

Valeurs absentes de color-map

Une valeur de color-field qui n'a pas de paire dans color-map prend la couleur de repli color, et la légende (dsfr-data-map-legend) lui ajoute une entrée dès que le repli a servi. Son libellé est celui de color-other-label, « Autres valeurs » par défaut :

<dsfr-data-map-layer id="reseau" source="communes" type="circle" geo-field="position"
  color-field="etat" color-map="Fermé:#00A95F,En cours:#FF9940" color="#929292"
  color-other-label="État inconnu"></dsfr-data-map-layer>
<dsfr-data-map-legend for="reseau" label="Fermeture du réseau"></dsfr-data-map-legend>

Ce libellé nomme des valeurs hors de la table des couleurs, pas des valeurs vides : c'est pourquoi l'attribut ne s'appelle pas empty-label, qui sur dsfr-data-chart, dsfr-data-facets et dsfr-data-a11y nomme une valeur absente. Sur un champ ouvert, une modalité nouvelle du jeu tombe elle aussi dans le repli : l'appeler « Non renseigné » serait faux. Pour distinguer les valeurs vides, les recoder en amont (dsfr-data-normalize) et leur donner leur propre paire dans color-map.

Filtrage au clic

Regroupement : un élément par groupe (format long)

Quand les données sont au format long — une ligne par couple ville × aide, coordonnées répétées sur chaque ligne —, group-field="Ville" trace un seul marqueur (ou cercle, ou forme) par valeur distincte du champ, au lieu de N marqueurs empilés. Au clic, la popup, le volet (panel-left / panel-right) ou la modale de dsfr-data-map-popup reçoivent toutes les lignes du groupe : en titre la valeur du groupe (ou le title-field du compagnon, lu sur le premier enregistrement), puis un tableau des popup-fields avec une ligne par enregistrement. Si popup-template (ou le <template> du compagnon) est posé, il s'applique à chaque ligne, en liste. Sans popup-fields ni gabarit, le compagnon montre les colonnes scalaires du jeu, hors géométrie et hors champ de regroupement. Au plus 200 lignes, puis « … et N autres ». Toutes les valeurs sont échappées.

• Position : celle du premier enregistrement du groupe qui porte des coordonnées exploitables (la première forme pour geoshape). Des coordonnées différentes au sein d'un groupe sont signalées une fois en console.
• tooltip-field, color-field, radius-field, fill-field : la valeur de ce même premier enregistrement. Pour un rayon ou une couleur proportionnels à un total par groupe, agréger en amont (dsfr-data-query group-by) sur une seconde couche.
• max-items, getRenderedCount(), le bandeau de troncature et le total de dsfr-data-map-layer-render comptent des groupes.
• refine-on-click : à poser sur le même champ, il filtre sur la valeur du groupe. L'événement dsfr-data-map-select porte en plus group et records (toutes les lignes).
• cluster : compatible, chaque groupe est un point de la grappe. Une ligne sans valeur de regroupement reste un élément à part.
• heatmap : group-field est sans effet (chaque ligne reste un point de chaleur) et un avertissement le dit en console.

<dsfr-data-map center="46.6,2.3" zoom="6">
  <dsfr-data-map-layer id="aides" source="src-aides" type="marker"
    lat-field="Latitude" lon-field="Longitude"
    group-field="Ville" popup-fields="Action,Domaine"></dsfr-data-map-layer>
  <dsfr-data-map-popup for="aides" mode="panel-right"></dsfr-data-map-popup>
</dsfr-data-map>

Heatmap

Clustering

Zoom et viewport

Animation temporelle

Performance

Bandeau « N affichés sur M » (#1020). Dès que la carte ne montre qu'une partie du jeu, la couche pose sous la carte un bandeau role="status", sans aucun contrôle interactif, qui donne les deux chiffres — éléments affichés et total connu — et le biais : ce sont les premiers enregistrements, dans l'ordre du fichier (ou du tri order-by de la source), leur répartition n'est donc pas représentative. Deux cas le déclenchent :

• plafond de rendu : la couche a reçu plus de lignes que max-items ; le total est le nombre de lignes reçues ;
• troncature amont : la source n'a chargé qu'une partie du jeu (limit, max-records, plafond de pages de l'adaptateur) ; la couche lit la meta de la source, et le total est celui que l'API annonce.

C'est ce second cas qui rend sûr d'aligner le limit de la source sur max-items : la source ne charge plus de lignes que la couche ne dessinerait pas, et le bandeau reste là. Le Builder Carto le fait par défaut, avec un plafond de 1 000 points (la bibliothèque garde 5 000). Pas de bandeau sur une carte verrouillée (encarts) ; plusieurs couches tronquées empilent leurs bandeaux.

<dsfr-data-source id="elus" api-type="tabular" resource="…" limit="1000"></dsfr-data-source>
<dsfr-data-map>
  <dsfr-data-map-layer source="elus" lat-field="lat" lon-field="lon" max-items="1000"></dsfr-data-map-layer>
</dsfr-data-map>
<!-- Bandeau : « 1 000 premiers enregistrements affichés sur 34 826, dans l'ordre du fichier :
     la répartition affichée n'est pas représentative. La source n'a chargé qu'une partie du jeu. » -->

Attribut retiré : filter (retiré en #297, warn console s'il est présent) — filtrer en amont avec dsfr-data-query ou l'attribut where de la source.

Résolution des coordonnées

La couche résout les coordonnées dans cet ordre de priorité :

1. lat-field + lon-field — coordonnées séparées (CSV, API)
2. geo-field vers un Point — GeoJSON Point, objet {lat, lon} ou tableau [lat, lon]
3. geo-field vers Polygon/MultiPolygon — rendu via L.geoJSON()
4. Auto-détection — geo_point_2d, geopoint, geo_point, puis geo_shape, geometry, geom

À chaque étape, une chaîne JSON sérialisée est acceptée et parsée automatiquement (#426) — le cas des colonnes Text de Grist ou d'un CSV embarquant du GeoJSON.

Événements

API JavaScript

Exemples

<dsfr-data-source id="bornes" api-type="opendatasoft"
  base-url="https://odre.opendatasoft.com" dataset-id="bornes-irve"
  select="geo_point_2d,nom_station,puissance_nominale,adresse"
  limit="5000">
</dsfr-data-source>

<dsfr-data-map center="46.6,2.3" zoom="6" tiles="ign-plan" fit-bounds>
  <dsfr-data-map-layer source="bornes" type="marker"
    geo-field="geo_point_2d"
    tooltip-field="nom_station"
    cluster cluster-radius="60">
  </dsfr-data-map-layer>
</dsfr-data-map>

<dsfr-data-source id="regions" api-type="opendatasoft"
  base-url="https://public.opendatasoft.com" dataset-id="georef-france-region"
  select="geo_shape,reg_name,population" limit="20">
</dsfr-data-source>

<dsfr-data-source id="communes" api-type="opendatasoft"
  base-url="https://public.opendatasoft.com" dataset-id="georef-france-commune"
  select="geo_shape,com_name,population" limit="500" server-side page-size="500">
</dsfr-data-source>

<dsfr-data-map center="46.6,2.3" zoom="6" tiles="ign-plan" height="600px">

  <!-- Contours de référence, purement décoratifs -->
  <dsfr-data-map-layer source="regions" type="geoshape"
    geo-field="geo_shape" no-interactive
    color="#7b7b7b" fill-opacity="0">
  </dsfr-data-map-layer>

  <!-- Zoom 1-9 : régions -->
  <dsfr-data-map-layer source="regions" type="geoshape"
    geo-field="geo_shape" fill-field="population"
    selected-palette="sequentialAscending"
    tooltip-field="reg_name"
    min-zoom="1" max-zoom="9">
  </dsfr-data-map-layer>

  <!-- Zoom 10+ : communes dans le viewport (in_bbox côté ODS) -->
  <dsfr-data-map-layer source="communes" type="geoshape"
    geo-field="geo_shape" fill-field="population"
    selected-palette="sequentialAscending"
    tooltip-field="com_name"
    min-zoom="10" bbox bbox-debounce="500">
  </dsfr-data-map-layer>

</dsfr-data-map>

<!-- Rayon écran : l'aire suit la valeur (radius-scale="sqrt"), radius-max en pixels -->
<dsfr-data-map-layer source="villes" type="circle"
  lat-field="latitude" lon-field="longitude"
  radius-field="population" radius-unit="px" radius-scale="sqrt" radius-max="35"
  color="#000091" fill-opacity="0.4"
  tooltip-field="nom">
</dsfr-data-map-layer>

<!-- Rayon terrain : la valeur du champ est un rayon en mètres (L.circle) -->
<dsfr-data-map-layer source="antennes" type="circle"
  lat-field="lat" lon-field="lon"
  radius-field="portee_m" radius-unit="m"
  color="#C9191E" fill-opacity="0.15">
</dsfr-data-map-layer>

<dsfr-data-source id="bornes-trim" data='[
  {"region":"Paris","lat":48.85,"lon":2.35,"bornes":120,"date":"2025-T1"},
  {"region":"Lyon","lat":45.76,"lon":4.83,"bornes":85,"date":"2025-T1"},
  {"region":"Paris","lat":48.85,"lon":2.35,"bornes":250,"date":"2025-T2"},
  {"region":"Lyon","lat":45.76,"lon":4.83,"bornes":160,"date":"2025-T2"}
]'></dsfr-data-source>

<dsfr-data-map center="46.6,2.3" zoom="6" height="550px">
  <dsfr-data-map-layer source="bornes-trim" type="circle"
    lat-field="lat" lon-field="lon"
    radius-field="bornes" radius-min="6" radius-max="35"
    color="#000091" fill-opacity="0.5"
    tooltip-field="region"
    time-field="date" time-mode="snapshot">
  </dsfr-data-map-layer>
  <dsfr-data-map-timeline speed="1" interval="1500"></dsfr-data-map-timeline>
</dsfr-data-map>

Voir aussi

• dsfr-data-map — le conteneur et la vue d'ensemble de la famille
• dsfr-data-map-popup — l'affichage au clic déclaratif
• dsfr-data-map-timeline — les contrôles de lecture temporelle