gisco_id_api: GISCO ID service API

In giscoR: Download 'Eurostat' 'GISCO' Spatial Data

GISCO ID service API

Description

Functions to interact with the GISCO ID service API, which returns attributes and, optionally, geometry for different datasets at specified coordinates in the selected coordinate reference system.

Each endpoint has a corresponding function in giscoR. See Details for the lookup modes supported by these functions.

Usage

gisco_id_api_geonames(
  x = NULL,
  y = NULL,
  xmin = NULL,
  ymin = NULL,
  xmax = NULL,
  ymax = NULL,
  verbose = FALSE
)

gisco_id_api_nuts(
  x = NULL,
  y = NULL,
  year = 2024,
  epsg = c(4326, 4258, 3035),
  verbose = FALSE,
  nuts_id = NULL,
  nuts_level = NULL,
  geometry = TRUE
)

gisco_id_api_lau(
  x,
  y,
  year = 2024,
  epsg = c(4326, 4258, 3035),
  verbose = FALSE,
  geometry = TRUE
)

gisco_id_api_country(
  x,
  y,
  year = 2024,
  epsg = c(4326, 4258, 3035),
  verbose = FALSE,
  geometry = TRUE
)

gisco_id_api_river_basin(
  x,
  y,
  year = 2019,
  epsg = c(4326, 4258, 3035),
  verbose = FALSE,
  geometry = TRUE
)

gisco_id_api_biogeo_region(
  x,
  y,
  year = 2016,
  epsg = c(4326, 4258, 3035),
  verbose = FALSE,
  geometry = TRUE
)

gisco_id_api_census_grid(
  x,
  y,
  year = 2021,
  epsg = c(4326, 4258, 3035),
  verbose = FALSE,
  geometry = TRUE
)

Arguments

x, y	A character string or numeric value with the coordinates to identify, expressed in the CRS selected by epsg. For Geonames, use longitude and latitude in EPSG:4326.
xmin, ymin, xmax, ymax	A character string or numeric value with bounding box coordinates in EPSG:4326 to identify geonames within the box. The extent must not exceed five degrees in either dimension.
verbose	A logical value indicating whether to display informational messages.
year	A character string or numeric value with the dataset year, see Details.
epsg	A character string or numeric value with the EPSG code for the coordinate reference system of the input coordinates and returned geometry. One of 4326, 4258 or 3035. This argument is sent as the API's proj parameter.
nuts_id	A character string with the NUTS ID code.
nuts_level	A character string or numeric value with the NUTS level. One of 0, 1, 2 or 3. This argument is sent as the API's level parameter. If NULL, the service uses level 3 for coordinate lookups.
geometry	A logical value indicating whether to return geometry. If TRUE, an sf object is returned. If FALSE, a tibble is returned.

Details

The service also supports identifier lookups for other datasets and Geonames name searches. These lookup modes are not exposed by the corresponding functions in giscoR. Only the NUTS function supports lookup by ID through nuts_id.

The available endpoints are:

• gisco_id_api_geonames(): Get geographic placenames from longitude and latitude coordinates or a bounding box.

• gisco_id_api_nuts(): Return NUTS regions from coordinates or an ID. Accepted values for year: \Sexpr[stage=render,results=rd]{sub("^(is|are) ", "", giscoR:::docs_id_years("nuts"))}.

• gisco_id_api_lau(): Return the ID and, optionally, geometry for Local Administrative Units (LAU) at specified coordinates. Accepted values for year: \Sexpr[stage=render,results=rd]{sub("^(is|are) ", "", giscoR:::docs_id_years("lau"))}.

• gisco_id_api_country(): Return the ID and, optionally, geometry for countries at specified coordinates. Accepted values for year: \Sexpr[stage=render,results=rd]{sub("^(is|are) ", "", giscoR:::docs_id_years("country"))}.

• gisco_id_api_river_basin(): Return the ID and, optionally, geometry for river basins at specified coordinates, based on the Water Framework Directive (WFD) reference spatial datasets. Accepted values for year: \Sexpr[stage=render,results=rd]{sub("^(is|are) ", "", giscoR:::docs_id_years("riverbasin"))}.

• gisco_id_api_biogeo_region(): Return the ID and, optionally, geometry for biogeographical regions at specified coordinates. The biogeographical regions dataset contains the official delineations used in the Habitats Directive (92/43/EEC) and for the EMERALD Network. Accepted values for year: \Sexpr[stage=render,results=rd]{sub("^(is|are) ", "", giscoR:::docs_id_years("biogeoregion"))}.

• gisco_id_api_census_grid(): Return the ID and, optionally, geometry for census grid cells at specified coordinates. Accepted values for year: \Sexpr[stage=render,results=rd]{sub("^(is|are) ", "", giscoR:::docs_id_years("censusgrid"))}.

Value

A tibble when geometry = FALSE, or an sf object when geometry = TRUE. Geonames always returns an sf object. Failed requests return NULL.

Source

https://gisco-services.ec.europa.eu/id/api-docs/.

See Also

gisco_get_nuts(), gisco_get_lau(), gisco_get_countries(), gisco_get_census() and gisco_address_api.

GISCO API tools: gisco_address_api

Examples

gisco_id_api_geonames(x = -2.5, y = 43.06)

lau <- gisco_id_api_lau(x = -2.5, y = 43.06)
nuts3 <- gisco_id_api_nuts(x = -2.5, y = 43.06, nuts_level = 3)

if (
  all(!is.null(lau), !is.null(nuts3)) &&
    requireNamespace("ggplot2", quietly = TRUE)
) {
  library(ggplot2)

  ggplot(nuts3) +
    geom_sf(fill = "lightblue", color = "black") +
    geom_sf(data = lau, fill = "orange", color = "red") +
    labs(
      title = "NUTS 3 and LAU boundaries",
      subtitle = "Arrasate, Basque Country, Spain",
      caption = "Source: GISCO ID service API"
    )
}

giscoR documentation built on Oct. 1, 2026, 5:13 p.m.