carti_download

carti_download(
    values,
    borders='COMMUNE',
    filter_by='REGION',
    territory='metropole',
    vectorfile_format='auto',
    year=None,
    crs=4326,
    simplification=None,
    bucket=BUCKET,
    path_within_bucket=PATH_WITHIN_BUCKET,
    provider='IGN',
    dataset_family='ADMINEXPRESS',
    source='EXPRESS-COG-CARTO-TERRITOIRE',
    filename='raw',
    return_as_json=False,
    engine='geopandas',
    con=None,
    force=False,
    where=None,
)

Download official French borders produced by cartiflette.

Everything is done with DuckDB; with the default engine, the result is converted into a GeoDataFrame at the end.

GeoJSON: one file per value of filter_by; the list of links is built and DuckDB reads the files together.
GeoParquet (from 2025 onwards, and some earlier years): one file per level; DuckDB filters it and only downloads the needed parts.

Parameters

Name	Type	Description	Default
values	list or str or int	Values of `filter_by` to retrieve (e.g. [“11”, “84”] for REGION, “France” for FRANCE_ENTIERE). Region codes below 10 can be given as 1, “1” or “01”.	required
borders	str	Level of the polygons: COMMUNE, COMMUNE_ARRONDISSEMENT, IRIS (2025 onwards), DEPARTEMENT, REGION, BASSIN_VIE, ZONE_EMPLOI, UNITE_URBAINE, AIRE_ATTRACTION_VILLES; or the cells of the Insee gridded data (Filosofi, metropolitan France, Martinique and La Réunion), CARREAU_200M and CARREAU_1KM, with the Insee fields (ind, men, ind_snv…) and the commune holding their centre.	`'COMMUNE'`
filter_by	str	Level used to select the polygons: DEPARTEMENT, REGION, TERRITOIRE, FRANCE_ENTIERE, FRANCE_ENTIERE_DROM_RAPPROCHES or a zoning; also COMMUNE and COMMUNE_ARRONDISSEMENT for IRIS and the grids (no FRANCE_ENTIERE_DROM_RAPPROCHES for the grids).	`'REGION'`
territory	str	Kept for compatibility with the storage layout of the GeoJSON files, “metropole”.	`'metropole'`
vectorfile_format	str	“auto” (default), “geojson” or “parquet”. GeoParquet is read whenever it exists, even if “geojson” is requested, unless `force` is True; see `choose_format`, `parquet_available` and `geojson_available`.	`'auto'`
year	str or int	Vintage of the borders. Defaults to the current year.	`None`
crs	str or int	EPSG code of the projection. Default 4326.	`4326`
simplification	int	Simplification level, as the percentage of points removed: 0 (complete contours), 50, or 80 (lightest). Default 80, or 50 for the years only published as GeoJSON (2022), which have no 80 version. Always 0 for the grids: squares are not simplified.	`None`
bucket	str	Bucket of the files, “projet-cartiflette”.	`BUCKET`
path_within_bucket	str	Prefix within the bucket: “production” for the published files, or a test location such as “test/v0.3.0”.	`PATH_WITHIN_BUCKET`
provider	str	Provider of the data, “IGN”.	`'IGN'`
dataset_family	str	Dataset family, “ADMINEXPRESS”.	`'ADMINEXPRESS'`
source	str	Source label in the paths, “EXPRESS-COG-CARTO-TERRITOIRE”.	`'EXPRESS-COG-CARTO-TERRITOIRE'`
filename	str	Name of the file without extension, “raw”.	`'raw'`
return_as_json	bool	If True, return a GeoJSON string.	`False`
engine	str	“geopandas” (default): return a GeoDataFrame. “duckdb”: return the DuckDB relation, not evaluated yet, to go on with SQL.	`'geopandas'`
con	duckdb.DuckDBPyConnection	DuckDB connection to use (e.g. to join the result with other data). By default, an in-memory connection shared by all the calls.	`None`
force	bool	Read GeoJSON when `vectorfile_format="geojson"` even if GeoParquet exists for the year. A warning recalls that GeoParquet is faster. Only for years with GeoJSON files (2022): none is published from 2025 onwards, so GeoParquet is read anyway, with a warning.	`False`
where	str	DuckDB SQL expression to keep only some of the polygons of `values`, on their attributes (`"POPULATION > 2000"`) or their geometry (`"ST_Intersects(geometry, ST_MakeEnvelope(4.2, 43.3, 4.9, 43.8))"`, coordinates in `crs`); see `filter_relation`. Applied before the conversion, whatever the format and the engine.	`None`

Returns

Name	Type	Description
	geopandas.GeoDataFrame or duckdb.DuckDBPyRelation or str

Raises

Name	Type	Description
	ValueError	If `vectorfile_format` or `engine` is not supported, or if `where` is not a valid expression; GeoParquet only: if `borders` cannot be filtered by `filter_by`, or if some values are not found.
	OSError	If a file cannot be found.

Examples

Departements with the DROM brought closer to metropolitan France:

>>> from cartiflette import carti_download
>>> gdf = carti_download(
...     values=["France"],
...     borders="DEPARTEMENT",
...     filter_by="FRANCE_ENTIERE_DROM_RAPPROCHES",
...     simplification=50,
...     year=2022,
... )

Communes of two regions, kept in DuckDB:

>>> rel = carti_download(
...     values=["11", "84"],
...     borders="COMMUNE",
...     filter_by="REGION",
...     year=2025,
...     engine="duckdb",
... )
>>> rel.aggregate("INSEE_REG, sum(POPULATION)")

Communes of more than 2,000 inhabitants in Occitanie:

>>> gdf = carti_download(
...     values="76",
...     borders="COMMUNE",
...     filter_by="REGION",
...     year=2025,
...     where="POPULATION > 2000",
... )

Retour au sommet