GISCO ID service API

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
)

Source

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

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.

Value

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

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: "2024", "2021", "2016", "2013", "2010", "2006" .
gisco_id_api_lau(): Return the ID and, optionally, geometry for Local Administrative Units (LAU) at specified coordinates. Accepted values for year: "2024", "2023", "2022", "2021", "2020", "2019", "2018", "2017", "2016", "2015", "2014", "2013", "2012", "2011" .
gisco_id_api_country(): Return the ID and, optionally, geometry for countries at specified coordinates. Accepted values for year: "2024", "2020", "2016", "2013", "2010", "2006" .
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: "2024", "2023", "2022", "2021", "2020", "2019" .
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: "2016" .
gisco_id_api_census_grid(): Return the ID and, optionally, geometry for census grid cells at specified coordinates. Accepted values for year: "2021" .

Examples

# \donttest{
gisco_id_api_geonames(x = -2.5, y = 43.06)
#> Simple feature collection with 10 features and 8 fields
#> Geometry type: POINT
#> Dimension:     XY
#> Bounding box:  xmin: -2.520847 ymin: 43.06455 xmax: -2.491494 ymax: 43.07037
#> Geodetic CRS:  WGS 84
#> # A tibble: 10 × 9
#>    name       type  country language localtype distanceMeters endlifespanversion
#>  * <chr>      <chr> <chr>   <chr>    <chr>              <dbl> <chr>             
#>  1 Arrasate   admi… Spain   baq      Administ…           809. NA                
#>  2 Mondragón  admi… Spain   spa      Administ…           809. NA                
#>  3 Arrasate   admi… Spain   baq      Administ…           809. NA                
#>  4 Arrasate   admi… Spain   baq      Administ…           809. NA                
#>  5 Mondragón  admi… Spain   spa      Administ…           809. NA                
#>  6 Mondragón  admi… Spain   spa      Administ…           809. NA                
#>  7 Arrasate/… popu… Spain   spa      BUILTUPP            858. NA                
#>  8 Arrasate/… popu… Spain   spa      BUILTUPP            858. NA                
#>  9 Arrasate/… popu… Spain   spa      BUILTUPP            858. NA                
#> 10 Garagartza popu… Spain   baq      BUILTUPP           2052. NA                
#> # ℹ 2 more variables: beginlifespanversion <date>, geometry <POINT [°]>

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"
    )
}

# }