% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/h3_compat.R
\name{import_h3}
\alias{import_h3}
\title{Import External H3 Cell IDs into hexify}
\usage{
import_h3(cell_ids, data = NULL, validate = TRUE, radius_km = EARTH_RADIUS_KM)
}
\arguments{
\item{cell_ids}{Character vector of H3 cell ID strings}

\item{data}{Optional data frame to attach. Must have the same number of rows
as \code{cell_ids}. If \code{NULL}, returns a HexGridInfo object.}

\item{validate}{If \code{TRUE} (default), checks that all cell IDs are valid
H3 cells at the same resolution before proceeding. Set to \code{FALSE} to
skip validation when cell IDs are known to be correct.}

\item{radius_km}{Radius of the body the cells cover, in kilometers, or a body
name (default Earth). See \code{\link{hex_grid}}.}
}
\value{
If \code{data = NULL}, a HexGridInfo object for the inferred H3
resolution. If \code{data} is provided, a HexData object with data
attached at the specified cells.
}
\description{
Ingests H3 cell IDs from an external source (another H3 library, a database,
or a CSV file) into hexify. Validates cell IDs, infers the H3 resolution,
and optionally attaches data to build a HexData object.
}
\details{
For converting between grid specs, use
\code{\link{hex_grid}(type = "h3")} directly. For cell-level ISEA/H3
mapping, use \code{\link{h3_crosswalk}}.

H3 cell IDs encode their resolution in the index itself, so no resolution
argument is needed. The resolution is inferred automatically. All cell IDs
must share the same resolution; mixed resolutions produce an error.
}
\examples{
\donttest{
# Import external H3 cell IDs (grid spec only)
h3_ids <- c("8528342bfffffff", "85283473fffffff", "85283447fffffff")
grid <- import_h3(h3_ids)
grid

# Import with data attached
df <- data.frame(species = c("oak", "pine", "birch"), count = c(10, 5, 3))
hd <- import_h3(h3_ids, data = df)
hd
}
}
\seealso{
\code{\link{hex_grid}} for creating grids directly,
\code{\link{h3_crosswalk}} for cell-level ISEA/H3 mapping
}
