% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/get_heritage.R
\name{get_heritage}
\alias{get_heritage}
\title{Retrieve and download heritage spatial data for a given sf object}
\usage{
get_heritage(x, data_code, buffer = 2500, crs = 2154, verbose = TRUE)
}
\arguments{
\item{x}{An \code{sf} object defining the area of interest.}

\item{data_code}{A single \code{character} heritage dataset codes to retrieve.
Valid codes can be obtained with \code{\link[=get_heritage_layernames]{get_heritage_layernames()}}.}

\item{buffer}{A \code{numeric} value (default = 2500). Buffer distance in meters
used to slightly expand geometries before querying.}

\item{crs}{An \code{integer} or \code{sf::st_crs} object (default = 2154). Coordinate
reference system used for spatial processing.}

\item{verbose}{Logical. If \code{TRUE} (default), prints progress and diagnostic messages.}
}
\value{
A single \code{sf} object containing all retrieved heritage features.
Returns an empty \code{sf} object if no data is found or all requests fail.
}
\description{
This function retrieves and downloads spatial heritage datasets from the
French Ministry of Culture’s "Atlas du Patrimoine" service.
}
\details{
It uses the spatial extent and inferred department(s) of the input \code{sf}
object to query an internal registry of heritage datasets, then downloads
and merges the corresponding spatial layers.

This function currently supports metropolitan France departments (96 units).

Internally, the function:
\enumerate{
\item Validates the input \code{data_code} against an internal registry.
\item Prepares and optionally buffers the input geometry.
\item Computes spatial extents (bounding boxes) for each feature.
\item Assigns each feature to one or more administrative departments.
\item Filters available heritage records using an internal dataset registry.
\item Builds query URLs for the Atlas du Patrimoine service.
\item Downloads ZIP archives containing shapefiles.
\item Reads, validates, and merges the resulting \code{sf} objects.
}

Partial failures are tolerated: invalid or empty responses for individual
requests are skipped.
}
\examples{
\donttest{
if (interactive()) {

  # Define a minimal spatial object (WGS84 point)
  my_sf_layer <- sf::st_sf(
    geometry = sf::st_sfc(
      sf::st_point(c(2.21, 48.82)),
      crs = 4326
    )
  )

  # Retrieve heritage spatial data
  res <- get_heritage(
    x = my_sf_layer,
    data_code = "IMMH",
    buffer = 2000,
    crs = 2154,
    verbose = TRUE
  )

}
}

}
