| Type: | Package |
| Title: | Identification and Visualisation of European NUTS Regions from Geolocations |
| Version: | 1.0.0 |
| Description: | Provides functions to identify European NUTS (Nomenclature of Territorial Units for Statistics) regions for geographic coordinates (latitude/longitude) using Eurostat geospatial boundaries. Includes map-based visualisation of the matched regions for validation and exploration. Designed for regional data analysis, reproducible workflows, and integration with common geospatial R packages. |
| License: | GPL (≥ 3) |
| URL: | https://github.com/aikatona/geonuts |
| BugReports: | https://github.com/aikatona/geonuts/issues |
| Depends: | R (≥ 4.1.0) |
| Imports: | eurostat, ggplot2, giscoR, units, grid, sf |
| Suggests: | knitr, rmarkdown, testthat (≥ 3.0.0) |
| Config/testthat/edition: | 3 |
| Encoding: | UTF-8 |
| RoxygenNote: | 7.3.2 |
| VignetteBuilder: | knitr |
| NeedsCompilation: | no |
| Packaged: | 2026-01-07 21:33:16 UTC; mtkurbucz |
| Author: | Attila I. Katona [aut, cre], Marcell T. Kurbucz [aut] |
| Maintainer: | Attila I. Katona <katona.attila@gtk.uni-pannon.hu> |
| Repository: | CRAN |
| Date/Publication: | 2026-01-09 15:10:13 UTC |
Assemble all-levels output (0..3) with status from level 3
Description
Assemble all-levels output (0..3) with status from level 3
Usage
.assemble_output_all(lat, lon, out0, out1, out2, out3, year, resolution)
Assemble single-level output
Description
Assemble single-level output
Usage
.assemble_output_single(lat, lon, joined, level, year, resolution)
Build map data (frequencies, splits, and an auto-zoom extent)
Description
Build map data (frequencies, splits, and an auto-zoom extent)
Usage
.build_map_data(shp, df, nuts_col)
Convert numeric lat/lon vectors to sf POINT (WGS84)
Description
Convert numeric lat/lon vectors to sf POINT (WGS84)
Usage
.coords_to_sf(latitude, longitude, crs_input = 4326)
Country filter by CNTR_CODE (if available)
Description
Country filter by CNTR_CODE (if available)
Usage
.filter_country(shp, country)
Cached Eurostat geospatial layer
Description
Cached Eurostat geospatial layer
Usage
.get_cached_shape(level, year, resolution, verbose = TRUE)
Spatial join + optional nearest fallback (robust; km units)
Description
Spatial join + optional nearest fallback (robust; km units)
Usage
.join_points_to_nuts(
pts,
shp,
match_strategy = "within",
nearest_max_km = Inf,
level = NA_integer_
)
Compact message printer
Description
Compact message printer
Usage
.message(x)
Pre-filter polygons by bounding box of points (safe with fallback)
Description
Pre-filter polygons by bounding box of points (safe with fallback)
Usage
.prefilter_by_bbox(shp, pts)
Render the map (ggplot2)
Description
Render the map (ggplot2)
Usage
.render_map(md, border_col, low_col, high_col, id_col, uid_col, show_points)
Normalise get_nuts() output for mapping
Description
Normalise get_nuts() output for mapping
Usage
.standardize_nuts_input(nuts, map_level)
Parameter validation for get_nuts()
Description
Parameter validation for get_nuts()
Usage
.validate_get_nuts_params(
latitude,
longitude,
level,
year,
resolution,
crs,
country,
match_strategy,
nearest_max_km
)
Identify NUTS Regions for Geolocations
Description
Vectorised identification of NUTS regions for input coordinates using
Eurostat geospatial layers. Supports a single level (0–3) or "all" to
return all levels. Optional country pre-filter and "nearest" fallback make
the function robust to points falling just outside polygon boundaries.
Usage
get_nuts(
latitude,
longitude,
level = "all",
year = 2021,
resolution = 20,
crs = 4326,
country = NULL,
match_strategy = c("within", "nearest"),
nearest_max_km = Inf,
verbose = TRUE
)
Arguments
latitude |
(numeric, mandatory) Latitudes in decimal degrees (WGS84).
Must be within |
longitude |
(numeric, mandatory) Longitudes in decimal degrees (WGS84).
Must be within |
level |
(integer or character, optional) One of |
year |
(integer, optional) NUTS reference year for the Eurostat layer.
Default: |
resolution |
(integer, optional) Eurostat map resolution. Typical
values: |
crs |
(integer, optional) EPSG code of input coordinates. If not 4326,
inputs are transformed to WGS84 (EPSG:4326). Default: |
country |
(character, optional) Two-letter |
match_strategy |
(character, optional) Matching strategy:
|
nearest_max_km |
(numeric, optional) Maximum distance (km) for
nearest fallback; use |
verbose |
(logical, optional) Print informative messages. Default: |
Details
Geometries are downloaded via
eurostat::get_eurostat_geospatial()and cached per(level, year, resolution)to avoid repeated I/O.Polygons are pre-filtered using the points' bounding box to accelerate joins on continental layers (with safe fallback).
Nearest distances are computed with units and converted to kilometers.
Value
If level is a single integer: a data.frame with columns
lat, lon, nuts, cntr_code, match_status, match_dist_km, level, year, resolution.
If level = "all": a data.frame with
lat, lon, nuts0, nuts1, nuts2, nuts3, cntr_code, match_status, match_dist_km, year, resolution.
Here match_status/match_dist_km are computed using level 3 (most granular).
See Also
Examples
res <- get_nuts(52.52, 13.405, level = 3, year = 2021, resolution = 20)
head(res)
Plot NUTS Matches on a Map
Description
Visualises the frequency of matched NUTS regions and (optionally) overlays
the input points (matched vs. unmatched) for validation. Works with both
single-level and multi-level (level = "all") outputs from get_nuts.
Usage
map_nuts(
nuts,
map_level = 3,
country = NULL,
show_points = TRUE,
border_col = "lightgrey",
low_col = "lightgreen",
high_col = "darkgreen",
id_col = "black",
uid_col = "red",
verbose = TRUE
)
Arguments
nuts |
(data.frame, mandatory) Output of |
map_level |
(integer, optional) NUTS level to display when multiple
levels are present. One of |
country |
(character, optional) Two-letter |
show_points |
(logical, optional) Overlay input points. Default: |
border_col |
(character, optional) Polygon border colour. Default: |
low_col |
(character, optional) Fill colour for lower frequencies. Default: |
high_col |
(character, optional) Fill colour for higher frequencies. Default: |
id_col |
(character, optional) Point colour for matched/nearest inputs. Default: |
uid_col |
(character, optional) Point colour for unmatched inputs. Default: |
verbose |
(logical, optional) Print informative messages. Default: |
Value
A ggplot2 object showing a choropleth of NUTS frequencies with
optional point overlays.
See Also
Examples
res <- get_nuts(52.52, 13.405, level = 3, year = 2021, resolution = 20)
p <- map_nuts(res, map_level = 3)
print(p)