---
title: "Get started with giscoR"
description: A brief introduction
vignette: >
  %\VignetteIndexEntry{Get started with giscoR}
  %\VignetteEngine{quarto::html}
  %\VignetteEncoding{UTF-8}
---

<!-- giscoR.qmd is generated from giscoR.qmd.orig. Please edit that file -->



# Introduction

*The full site with more examples and vignettes is available at
<https://ropengov.github.io/giscoR/>*

[**giscoR**](https://ropengov.github.io/giscoR/) is a package designed to
provide a simple interface to the [GISCO
API](https://gisco-services.ec.europa.eu/distribution/v2/).

GISCO provides geographic data for the European Union, its member countries and
subnational regions. It supplies geospatial files in different formats, focusing
especially on the EU but also offering worldwide datasets such as country
polygons, labels, borders and coastlines.

GISCO supplies data at multiple resolutions: high-detail datasets for small
areas (01M, 03M) and lighter datasets for larger areas (10M, 20M, 60M).
Datasets are available in three projections: [EPSG:4326](https://epsg.io/4326),
[EPSG:3035](https://epsg.io/3035), and [EPSG:3857](https://epsg.io/3857).

**giscoR** returns [`sf`](https://r-spatial.github.io/sf/reference/sf.html)
objects. See <https://r-spatial.github.io/sf/> for details.

# Caching

**giscoR** supports caching of downloaded datasets. Set the cache directory
with:


``` r
gisco_set_cache_dir("./path/to/location")
```

If a file is not available locally, it will be downloaded to that directory so
subsequent requests for the same data can be served from the local cache.

If downloading fails, you can manually download the file from the [GISCO API
website](https://gisco-services.ec.europa.eu/distribution/v2/) and place it in
your local cache directory.

# Downloading data

Review the following attribution and licensing requirements when using GISCO
data:

## General copyright

<figure>

<blockquote class="blockquote">

[Eurostat's general copyright notice and license
policy](https://ec.europa.eu/eurostat/web/main/help/copyright-notice) applies.
Moreover, there are specific rules that apply to some of the following datasets
available for downloading. The download and use of these data are subject to
acceptance of these rules. See the [administrative
units](https://ec.europa.eu/eurostat/web/gisco/geodata/administrative-units) and
[statistical
units](https://ec.europa.eu/eurostat/web/gisco/geodata/statistical-units) for
more details.

</blockquote>

```{=html}
<figcaption class="blockquote-footer">Source: <cite title="GISCO">
<a href="https://ec.europa.eu/eurostat/web/gisco/geodata"
class="external-link uri">https://ec.europa.eu/eurostat/web/gisco/geodata</a>
</cite>
</figcaption>
```

</figure>

The `gisco_attributions()` function provides guidance on this topic and returns
attributions in several languages.


``` r
library(giscoR)
c(
  gisco_attributions(lang = "en"),
  gisco_attributions(lang = "fr"),
  gisco_attributions(lang = "de")
) |> cat(sep = "\n\n")
#> © EuroGeographics for the administrative boundaries
#> 
#> © EuroGeographics pour les limites administratives
#> 
#> © EuroGeographics bezüglich der Verwaltungsgrenzen
```

# Basic example

The following example downloads EU member states and candidate countries as of
2024.


``` r
library(dplyr)
library(ggplot2)
world <- gisco_get_countries(resolution = 3, epsg = 3035)

world <- world |>
  mutate(
    status = case_when(
      EU_STAT == "T" ~ "Current members",
      CC_STAT == "T" ~ "Candidate countries",
      TRUE ~ NA
    ),
    # Set levels.
    status = factor(status,
      levels = c("Current members", "Candidate countries")
    )
  )

ggplot(world) +
  geom_sf(fill = "#c1c1c1") +
  geom_sf(aes(fill = status), color = "white") +
  guides(fill = guide_legend(direction = "horizontal")) +
  # Center on Europe with EPSG 3035.
  coord_sf(
    xlim = c(2377294, 7453440),
    ylim = c(1313597, 5628510)
  ) +
  scale_fill_manual(
    values = c("#039", "#2782bb"), na.value = "#c1c1c1",
    na.translate = FALSE
  ) +
  theme_minimal() +
  theme(
    panel.background = element_rect(fill = "grey90", color = NA),
    axis.line = element_blank(),
    axis.text = element_blank(),
    panel.grid = element_blank(),
    legend.position = "bottom"
  ) +
  labs(
    title = "EU member states and candidate countries (2024)",
    caption = gisco_attributions(),
    fill = ""
  )
```

<div class="figure">
<img src="./fig-country-1.png" alt="EU member states and candidate countries (2024)" width="100%" />
<p class="caption">EU member states and candidate countries (2024)</p>
</div>

You can select specific countries by name (in any language), ISO3 codes, or
Eurostat codes. However, you cannot mix these identifier types in a single call.

You can also combine datasets by using the same `resolution`, `epsg`, and
(optionally) `year`:


``` r
cntr <- c("Morocco", "Algeria", "Tunisia", "Libya", "Egypt")

africa_north <- gisco_get_countries(
  country = cntr,
  resolution = "03",
  epsg = "4326", year = "2024"
)

# Order plot facets.
africa_north$NAME_ENGL <- factor(africa_north$NAME_ENGL, levels = cntr)

# Get coastlines.
coast <- gisco_get_coastal_lines(
  resolution = "03",
  epsg = "4326",
  year = "2016"
)

# Create plot.
ggplot(coast) +
  geom_sf(color = "#B9B9B9") +
  geom_sf(data = africa_north, fill = "#346733", color = "#335033") +
  coord_sf(xlim = c(-13, 37), ylim = c(18.5, 40)) +
  facet_wrap(vars(NAME_ENGL), ncol = 2) +
  labs(caption = gisco_attributions("fr"))
```

<div class="figure">
<img src="./fig-africa-1.png" alt="Political map of North Africa" width="100%" />
<p class="caption">Political map of North Africa</p>
</div>

# Thematic maps with **giscoR**

This example shows how **giscoR** can be used together with Eurostat data. For
plotting, we use **ggplot2**. Any package that supports `sf` objects
(e.g., **tmap**, **mapsf**, **leaflet**) can be used.


``` r
# Load EU member data.
library(giscoR)
library(dplyr)
library(eurostat)
library(ggplot2)

nuts2 <- gisco_get_nuts(
  year = "2021", epsg = "3035", resolution = "10",
  nuts_level = "2"
)
# Get country borders.
borders <- gisco_get_countries(epsg = "3035", year = "2020", resolution = "3")

eu_bord <- borders |>
  filter(CNTR_ID %in% nuts2$CNTR_CODE)

# Retrieve disposable income data from Eurostat.
pps <- get_eurostat("tgs00026") |>
  filter(TIME_PERIOD == "2022-01-01")
#> 
indexed 0B in  0s, 0B/s
indexed 2.15GB in  0s, 2.15GB/s
                                                                                            

nuts2_sf <- nuts2 |>
  left_join(pps, by = "geo") |>
  mutate(
    values_th = values / 1000,
    categ = cut(values_th, c(0, 15, 30, 60, 90, 120, Inf))
  )

# Adjust labels.
labs <- levels(nuts2_sf$categ)
labs[1] <- "< 15"
labs[6] <- "> 120"
levels(nuts2_sf$categ) <- labs

# Create the plot.
ggplot(nuts2_sf) +
  # Add background geometry.
  geom_sf(data = borders, fill = "#e1e1e1", color = NA) +
  geom_sf(aes(fill = categ), color = "grey20", linewidth = .1) +
  geom_sf(data = eu_bord, fill = NA, color = "black", linewidth = .15) +
  # Center on Europe with EPSG 3035.
  coord_sf(xlim = c(2377294, 6500000), ylim = c(1413597, 5228510)) +
  # Configure legends and color.
  scale_fill_manual(
    values = hcl.colors(length(labs), "Geyser", rev = TRUE),
    # Label missing values.
    labels = function(x) {
      ifelse(is.na(x), "No Data", x)
    },
    na.value = "#e1e1e1"
  ) +
  guides(fill = guide_legend(nrow = 1)) +
  theme_void() +
  theme(
    text = element_text(colour = "grey0"),
    panel.background = element_rect(fill = "#97dbf2"),
    panel.border = element_rect(fill = NA, color = "grey10"),
    plot.title = element_text(hjust = 0.5, vjust = -1, size = 12),
    plot.subtitle = element_text(
      hjust = 0.5, vjust = -2, face = "bold",
      margin = margin(b = 10, t = 5), size = 12
    ),
    plot.caption = element_text(
      size = 8, hjust = 0, margin =
        margin(b = 4, t = 8)
    ),
    legend.text = element_text(size = 7, ),
    legend.title = element_text(size = 7),
    legend.position = "bottom",
    legend.direction = "horizontal",
    legend.text.position = "bottom",
    legend.title.position = "top",
    legend.key.height = rel(0.5),
    legend.key.width = unit(0.1, "npc")
  ) +
  # Add labels.
  labs(
    title = "Disposable income of private households (2022)",
    subtitle = "NUTS-2 level",
    fill = "euros (thousands)",
    caption = paste0(
      "Source: Eurostat, ", gisco_attributions()
    )
  )
```

<div class="figure">
<img src="./fig-giscor-1.png" alt="Disposable income of private households by NUTS 2 regions (2022)" width="100%" />
<p class="caption">Disposable income of private households by NUTS 2 regions (2022)</p>
</div>

Happy mapping!