DV3F - principaux endpoints

Permet d'interroger les mutations DV3F et leurs géométries.

Clef API

Une clé API est requise pour accéder aux endpoints DV3F. Vous pouvez obtenir une clé via le Portail Données foncières.

from apifoncier.client import ApiFoncierClient

api_key = "VOTRE_CLE_API"  # Clé API requise pour accéder aux endpoints DV3F
client = ApiFoncierClient({"api_key": api_key})

📂 `dv3f.mutations`

Description

Retourne les mutations issues de DV3F pour la commune ou l'emprise rectangulaire demandée.

Parameters:

Name	Type	Description	Default
`code_insee`	`(str, optionnel)`	Code INSEE communal ou d'arrondissement municipal (max 10, séparés par virgule).	`None`
`codes_insee`	`(List[str], optionnel)`	Liste de codes INSEE.	`None`
`in_bbox`	`(List[float], optionnel)`	[xmin, ymin, xmax, ymax], max 0.02° x 0.02°.	`None`
`lon_lat`	`(List[float], optionnel)`	Coordonnées [lon, lat].	`None`
`contains_lon_lat`	`(List[float], optionnel)`	Coordonnées à contenir [lon, lat].	`None`
`anneemut`	`(str, optionnel)`	Année de mutation (>=2010).	`None`
`anneemut_min`	`(str, optionnel)`	Année minimale.	`None`
`anneemut_max`	`(str, optionnel)`	Année maximale.	`None`
`codtypbien`	`(str, optionnel)`	Typologie de bien (séparés par virgule).	`None`
`idnatmut`	`(str, optionnel)`	Nature de mutation (séparés par virgule).	`None`
`vefa`	`(str, optionnel)`	Vente en l'état futur d'achèvement.	`None`
`codtypproa`	`(str, optionnel)`	Typologie acheteur (séparés par virgule).	`None`
`codtypprov`	`(str, optionnel)`	Typologie vendeur (séparés par virgule).	`None`
`filtre`	`(str, optionnel)`	Code pour exclure des transactions particulières.	`None`
`segmtab`	`(str, optionnel)`	Note de segment terrain à bâtir.	`None`
`sbati_min`	`(float, optionnel)`	Surface bâtie minimale.	`None`
`sbati_max`	`(float, optionnel)`	Surface bâtie maximale.	`None`
`sterr_min`	`(float, optionnel)`	Surface terrain minimale.	`None`
`sterr_max`	`(float, optionnel)`	Surface terrain maximale.	`None`
`valeurfonc_min`	`(float, optionnel)`	Valeur foncière minimale (€).	`None`
`valeurfonc_max`	`(float, optionnel)`	Valeur foncière maximale (€).	`None`
`fields`	`(str, optionnel)`	'all' pour obtenir tous les champs, None sinon.	`None`
`ordering`	`(str, optionnel)`	Champ de tri.	`None`
`page`	`(int, optionnel)`	Page de résultats.	`None`
`page_size`	`(int, optionnel)`	Nombre de résultats par page.	`500`
`paginate`	`(bool, optionnel)`	Pagination automatique.	`True`
`format_output`	`(str, optionnel)`	'dataframe' ou 'dict'.	`'dataframe'`

Returns:

Type	Description
`Union[DataFrame, List[dict]]`	DataFrame ou liste de dictionnaires des mutations.

Source code in apifoncier\endpoints\dv3f.py

def mutations(
    self,
    code_insee: Optional[str] = None,
    codes_insee: Optional[List[str]] = None,
    in_bbox: Optional[List[float]] = None,
    lon_lat: Optional[List[float]] = None,
    contains_lon_lat: Optional[List[float]] = None,
    anneemut: Optional[str] = None,
    anneemut_min: Optional[str] = None,
    anneemut_max: Optional[str] = None,
    codtypbien: Optional[str] = None,
    idnatmut: Optional[str] = None,
    vefa: Optional[str] = None,
    codtypproa: Optional[str] = None,
    codtypprov: Optional[str] = None,
    filtre: Optional[str] = None,
    segmtab: Optional[str] = None,
    sbati_min: Optional[float] = None,
    sbati_max: Optional[float] = None,
    sterr_min: Optional[float] = None,
    sterr_max: Optional[float] = None,
    valeurfonc_min: Optional[float] = None,
    valeurfonc_max: Optional[float] = None,
    fields: Optional[str] = None,
    ordering: Optional[str] = None,
    page: Optional[int] = None,
    page_size: Optional[int] = 500,
    paginate: bool = True,
    format_output: str = "dataframe",
) -> Union[pd.DataFrame, List[dict]]:
    """
    Retourne les mutations issues de DV3F pour la commune ou l'emprise rectangulaire demandée.

    Args:
        code_insee (str, optionnel): Code INSEE communal ou d'arrondissement municipal (max 10, séparés par virgule).
        codes_insee (List[str], optionnel): Liste de codes INSEE.
        in_bbox (List[float], optionnel): [xmin, ymin, xmax, ymax], max 0.02° x 0.02°.
        lon_lat (List[float], optionnel): Coordonnées [lon, lat].
        contains_lon_lat (List[float], optionnel): Coordonnées à contenir [lon, lat].
        anneemut (str, optionnel): Année de mutation (>=2010).
        anneemut_min (str, optionnel): Année minimale.
        anneemut_max (str, optionnel): Année maximale.
        codtypbien (str, optionnel): Typologie de bien (séparés par virgule).
        idnatmut (str, optionnel): Nature de mutation (séparés par virgule).
        vefa (str, optionnel): Vente en l'état futur d'achèvement.
        codtypproa (str, optionnel): Typologie acheteur (séparés par virgule).
        codtypprov (str, optionnel): Typologie vendeur (séparés par virgule).
        filtre (str, optionnel): Code pour exclure des transactions particulières.
        segmtab (str, optionnel): Note de segment terrain à bâtir.
        sbati_min (float, optionnel): Surface bâtie minimale.
        sbati_max (float, optionnel): Surface bâtie maximale.
        sterr_min (float, optionnel): Surface terrain minimale.
        sterr_max (float, optionnel): Surface terrain maximale.
        valeurfonc_min (float, optionnel): Valeur foncière minimale (€).
        valeurfonc_max (float, optionnel): Valeur foncière maximale (€).
        fields (str, optionnel): 'all' pour obtenir tous les champs, None sinon.
        ordering (str, optionnel): Champ de tri.
        page (int, optionnel): Page de résultats.
        page_size (int, optionnel): Nombre de résultats par page.
        paginate (bool, optionnel): Pagination automatique.
        format_output (str, optionnel): 'dataframe' ou 'dict'.

    Returns:
        DataFrame ou liste de dictionnaires des mutations.
    """
    checked_codes_insee, bbox_result, auto_contains_geom = (
        self._validate_location_params(
            code_insee=code_insee,
            codes_insee=codes_insee,
            coddep=None,
            in_bbox=in_bbox,
            lon_lat=lon_lat,
            contains_lon_lat=contains_lon_lat,
            max_bbox_size=0.02,
            max_codes=10,
        )
    )
    params = self._build_params(
        code_insee=checked_codes_insee,
        in_bbox=",".join(map(str, bbox_result)) if bbox_result else None,
        contains_geom=auto_contains_geom,
        anneemut=anneemut,
        anneemut_min=anneemut_min,
        anneemut_max=anneemut_max,
        codtypbien=codtypbien,
        idnatmut=idnatmut,
        vefa=vefa,
        codtypproa=codtypproa,
        codtypprov=codtypprov,
        filtre=filtre,
        segmtab=segmtab,
        sbati_min=sbati_min,
        sbati_max=sbati_max,
        sterr_min=sterr_min,
        sterr_max=sterr_max,
        valeurfonc_min=valeurfonc_min,
        valeurfonc_max=valeurfonc_max,
        fields=fields,
        ordering=ordering,
        page=page,
        page_size=page_size,
    )
    return self._fetch(
        endpoint="/dv3f/mutations",
        params=params,
        format_output=format_output,
        geo=False,
        paginate=paginate,
    )

Exemples d'utilisation

Mutations DV3F pour une commune :

client.dv3f.mutations(code_insee="59001")

Mutations DV3F dans une emprise géographique :

client.dv3f.mutations(in_bbox=[2.76, 49.73, 2.779, 49.749])

Mutations DV3F pour plusieurs communes :

client.dv3f.mutations(codes_insee=["59001", "62001"])

Mutations DV3F pour une commune donnée (ici, via le code INSEE 59350) en 2022, pour des biens de type maison ancienne(codtypbien=1113) et dont la surface est comprise entre 1000 et 5000 m2, en récupérant tous les champs disponibles :

client.dvf_opendata.mutations(
    code_insee="59350",
    anneemut="2022",
    fields="all",
    sterr_min=1000,
    sterr_max=5000,
    codtypbien="1113",
)

📂 `dv3f.geomutations`

Description

Retourne, en GeoJSON, les mutations issues de DV3F pour la commune ou l'emprise rectangulaire demandée.

Parameters:

Name	Type	Description	Default
`code_insee`	`(str, optionnel)`	Code INSEE communal ou d'arrondissement municipal (max 10, séparés par virgule).	`None`
`codes_insee`	`(List[str], optionnel)`	Liste de codes INSEE.	`None`
`in_bbox`	`(List[float], optionnel)`	[xmin, ymin, xmax, ymax], max 0.02° x 0.02°.	`None`
`lon_lat`	`(List[float], optionnel)`	Coordonnées [lon, lat].	`None`
`contains_lon_lat`	`(List[float], optionnel)`	Coordonnées à contenir [lon, lat].	`None`
`anneemut`	`(str, optionnel)`	Année de mutation (>=2010).	`None`
`anneemut_min`	`(str, optionnel)`	Année minimale.	`None`
`anneemut_max`	`(str, optionnel)`	Année maximale.	`None`
`codtypbien`	`(str, optionnel)`	Typologie de bien (séparés par virgule).	`None`
`idnatmut`	`(str, optionnel)`	Nature de mutation (séparés par virgule).	`None`
`vefa`	`(str, optionnel)`	Vente en l'état futur d'achèvement.	`None`
`codtypproa`	`(str, optionnel)`	Typologie acheteur (séparés par virgule).	`None`
`codtypprov`	`(str, optionnel)`	Typologie vendeur (séparés par virgule).	`None`
`filtre`	`(str, optionnel)`	Code pour exclure des transactions particulières.	`None`
`segmtab`	`(str, optionnel)`	Note de segment terrain à bâtir.	`None`
`sbati_min`	`(float, optionnel)`	Surface bâtie minimale.	`None`
`sbati_max`	`(float, optionnel)`	Surface bâtie maximale.	`None`
`sterr_min`	`(float, optionnel)`	Surface terrain minimale.	`None`
`sterr_max`	`(float, optionnel)`	Surface terrain maximale.	`None`
`valeurfonc_min`	`(float, optionnel)`	Valeur foncière minimale (€).	`None`
`valeurfonc_max`	`(float, optionnel)`	Valeur foncière maximale (€).	`None`
`fields`	`(str, optionnel)`	'all' pour obtenir tous les champs, None sinon.	`None`
`page`	`(int, optionnel)`	Page de résultats.	`None`
`page_size`	`(int, optionnel)`	Nombre de résultats par page.	`500`
`paginate`	`(bool, optionnel)`	Pagination automatique.	`True`
`format_output`	`(str, optionnel)`	'dataframe' ou 'dict'.	`'dataframe'`

Returns:

Type	Description
`GeoDataFrame`	GeoDataFrame des mutations géolocalisées.

Source code in apifoncier\endpoints\dv3f.py

def geomutations(
    self,
    code_insee: Optional[str] = None,
    codes_insee: Optional[List[str]] = None,
    in_bbox: Optional[List[float]] = None,
    lon_lat: Optional[List[float]] = None,
    contains_lon_lat: Optional[List[float]] = None,
    anneemut: Optional[str] = None,
    anneemut_min: Optional[str] = None,
    anneemut_max: Optional[str] = None,
    codtypbien: Optional[str] = None,
    idnatmut: Optional[str] = None,
    vefa: Optional[str] = None,
    codtypproa: Optional[str] = None,
    codtypprov: Optional[str] = None,
    filtre: Optional[str] = None,
    segmtab: Optional[str] = None,
    sbati_min: Optional[float] = None,
    sbati_max: Optional[float] = None,
    sterr_min: Optional[float] = None,
    sterr_max: Optional[float] = None,
    valeurfonc_min: Optional[float] = None,
    valeurfonc_max: Optional[float] = None,
    fields: Optional[str] = None,
    page: Optional[int] = None,
    page_size: Optional[int] = 500,
    paginate: bool = True,
    format_output: str = "dataframe",
) -> gpd.GeoDataFrame:
    """
    Retourne, en GeoJSON, les mutations issues de DV3F pour la commune ou l'emprise rectangulaire demandée.

    Args:
        code_insee (str, optionnel): Code INSEE communal ou d'arrondissement municipal (max 10, séparés par virgule).
        codes_insee (List[str], optionnel): Liste de codes INSEE.
        in_bbox (List[float], optionnel): [xmin, ymin, xmax, ymax], max 0.02° x 0.02°.
        lon_lat (List[float], optionnel): Coordonnées [lon, lat].
        contains_lon_lat (List[float], optionnel): Coordonnées à contenir [lon, lat].
        anneemut (str, optionnel): Année de mutation (>=2010).
        anneemut_min (str, optionnel): Année minimale.
        anneemut_max (str, optionnel): Année maximale.
        codtypbien (str, optionnel): Typologie de bien (séparés par virgule).
        idnatmut (str, optionnel): Nature de mutation (séparés par virgule).
        vefa (str, optionnel): Vente en l'état futur d'achèvement.
        codtypproa (str, optionnel): Typologie acheteur (séparés par virgule).
        codtypprov (str, optionnel): Typologie vendeur (séparés par virgule).
        filtre (str, optionnel): Code pour exclure des transactions particulières.
        segmtab (str, optionnel): Note de segment terrain à bâtir.
        sbati_min (float, optionnel): Surface bâtie minimale.
        sbati_max (float, optionnel): Surface bâtie maximale.
        sterr_min (float, optionnel): Surface terrain minimale.
        sterr_max (float, optionnel): Surface terrain maximale.
        valeurfonc_min (float, optionnel): Valeur foncière minimale (€).
        valeurfonc_max (float, optionnel): Valeur foncière maximale (€).
        fields (str, optionnel): 'all' pour obtenir tous les champs, None sinon.
        page (int, optionnel): Page de résultats.
        page_size (int, optionnel): Nombre de résultats par page.
        paginate (bool, optionnel): Pagination automatique.
        format_output (str, optionnel): 'dataframe' ou 'dict'.

    Returns:
        GeoDataFrame des mutations géolocalisées.
    """
    checked_codes_insee, bbox_result, auto_contains_geom = (
        self._validate_location_params(
            code_insee=code_insee,
            codes_insee=codes_insee,
            coddep=None,
            in_bbox=in_bbox,
            lon_lat=lon_lat,
            contains_lon_lat=contains_lon_lat,
            max_bbox_size=0.02,
            max_codes=10,
        )
    )
    params = self._build_params(
        code_insee=checked_codes_insee,
        in_bbox=",".join(map(str, bbox_result)) if bbox_result else None,
        contains_geom=auto_contains_geom,
        anneemut=anneemut,
        anneemut_min=anneemut_min,
        anneemut_max=anneemut_max,
        codtypbien=codtypbien,
        idnatmut=idnatmut,
        vefa=vefa,
        codtypproa=codtypproa,
        codtypprov=codtypprov,
        filtre=filtre,
        segmtab=segmtab,
        sbati_min=sbati_min,
        sbati_max=sbati_max,
        sterr_min=sterr_min,
        sterr_max=sterr_max,
        valeurfonc_min=valeurfonc_min,
        valeurfonc_max=valeurfonc_max,
        fields=fields,
        page=page,
        page_size=page_size,
    )
    return self._fetch(
        endpoint="/dv3f/geomutations",
        params=params,
        format_output=format_output,
        geo=True,
        paginate=paginate,
    )

Exemples d'utilisation

Mutations DV3F géolocalisées pour une commune :
```
client.dv3f.geomutations(code_insee="59001")
```

Mutations DV3F géolocalisées dans une emprise :

client.dv3f.geomutations(in_bbox=[2.76, 49.73, 2.779, 49.749])

Mutations DV3F géolocalisées filtrées par type de bien :

client.dv3f.geomutations(code_insee="59001", codtypbien="1113")

📂 `dv3f.mutation_by_id`

Description

Retourne la mutation DV3F pour l'identifiant fiscal demandé.

Parameters:

Name	Type	Description	Default
`idmutation`	`(int, obligatoire)`	Identifiant fiscal de la mutation.	required
`format_output`	`(str, optionnel)`	'dict'.	`'dict'`

Returns:

Type	Description
`Union[dict, List[dict]]`	Dictionnaire de la mutation.

Source code in apifoncier\endpoints\dv3f.py

def mutation_by_id(
    self,
    idmutation: int,
    format_output: str = "dict",
) -> Union[dict, List[dict]]:
    """
    Retourne la mutation DV3F pour l'identifiant fiscal demandé.

    Args:
        idmutation (int, obligatoire): Identifiant fiscal de la mutation.
        format_output (str, optionnel): 'dict'.

    Returns:
        Dictionnaire de la mutation.
    """
    if idmutation is None:
        raise ValidationError("idmutation est obligatoire")
    return self._fetch(
        endpoint=f"/dv3f/mutations/{idmutation}",
        params={},
        format_output=format_output,
        geo=False,
        paginate=False,
    )

Exemples d'utilisation

Mutation DV3F par identifiant :

client.dv3f.mutation_by_id(idmutation=123456)

DV3F - principaux endpoints

Clef API

📂 dv3f.mutations

Description

Exemples d'utilisation

📂 dv3f.geomutations

Description

Exemples d'utilisation

📂 dv3f.mutation_by_id

Description

Exemples d'utilisation

📂 `dv3f.mutations`

📂 `dv3f.geomutations`

📂 `dv3f.mutation_by_id`