Skip to contents

geobounds

Why this package?

The geobounds package provides an R-friendly interface for downloading administrative boundary data from geoBoundaries, the Global Database of Political Administrative Boundaries. With geobounds, you can:

  • Download individual country files and global composite files from geoBoundaries.
  • Use tidyverse and sf workflows in R to map, analyze and join administrative boundary data with your own data.
  • Work in an open-data context where attribution to geoBoundaries is required.

In short, if you work with administrative boundaries in R, this package simplifies downloading, cache management and integration with spatial data workflows.

Important

Attribution is required when using geoBoundaries.

Installation

Install geobounds from CRAN:

install.packages("geobounds")

Example usage 

library(geobounds)

sri_lanka_adm1 <- gb_get_adm1("Sri Lanka")
sri_lanka_adm2 <- gb_get_adm2("Sri Lanka")
sri_lanka_adm3 <- gb_get_adm3("Sri Lanka")

library(sf)
library(dplyr)

library(ggplot2)

ggplot(sri_lanka_adm3) +
  geom_sf(fill = "#DFDFDF", color = "white") +
  geom_sf(data = sri_lanka_adm2, fill = NA, color = "#F0B323") +
  geom_sf(data = sri_lanka_adm1, fill = NA, color = "black") +
  labs(caption = "Source: www.geoboundaries.org") +
  theme_void()

ADM1, ADM2 and ADM3 boundaries for Sri Lanka.

Release types

geoBoundaries provides three release types with different sources, validation processes and licensing:

  • gbOpen: Freely available boundaries under CC BY 4.0, suitable for most uses when attribution is provided.
  • gbHumanitarian: Boundaries mirrored from UN OCHA for humanitarian use, which may have less open licensing.
  • gbAuthoritative: Boundaries mirrored from UN SALB and verified through in-country processes. These boundaries cannot be used for commercial purposes.

Use the release_type argument to request a specific release type, for example, gb_get_adm1("Sri Lanka", release_type = "gbHumanitarian").

For coverage and boundary metadata by release type, see the package articles.

Advanced usage

Map the highest available ADM level in geoBoundaries by country:

library(geobounds)
library(ggplot2)
library(dplyr)

world <- gb_get_world()
max_lvl <- gb_get_max_adm_lvl(release_type = "gbOpen")

world_max <- world |>
  mutate(boundaryISO = shapeGroup) |>
  left_join(max_lvl) |>
  mutate(max_lvl = factor(maxBoundaryType, levels = 0:5))

pal <- c("#0e221b", "#0f4a38", "#0b6e4f", "#719384", "#b9975a", "#936e28")
names(pal) <- levels(world_max$max_lvl)

ggplot(world_max) +
  geom_sf(fill = "#e5e5e5", color = "#e5e5e5") +
  geom_sf(aes(fill = max_lvl), color = "transparent") +
  scale_fill_manual(values = pal, na.translate = FALSE, drop = FALSE) +
  guides(fill = guide_legend(direction = "horizontal", nrow = 1)) +
  coord_sf(expand = TRUE, crs = "+proj=robin") +
  theme_void() +
  theme(
    plot.background = element_rect(fill = "white", color = NA),
    text = element_text(family = "sans", face = "bold"),
    legend.position = "bottom",
    legend.title.position = "top",
    legend.title = element_text(size = rel(0.75), face = "plain"),
    legend.text = element_text(size = rel(1)),
    legend.text.position = "right",
    legend.key.height = unit(1, "line"),
    legend.key.width = unit(1, "line"),
    plot.caption = element_text(
      size = rel(0.7),
      margin = margin(r = 4)
    )
  ) +
  labs(
    fill = "gbOpen: Highest available ADM level",
    caption = "Source: www.geoboundaries.org"
  )

Highest available gbOpen ADM level by country.

Documentation and resources

License

This package is released under the CC BY 4.0 license. The default geoBoundaries release type, gbOpen, is CC BY 4.0 compliant when attribution is provided. Other release types may have additional licensing restrictions, so check the boundary metadata returned by gb_get_metadata() before reuse.

Acknowledgments

  • Thanks to the geoBoundaries team and the William & Mary geoLab for creating and maintaining the dataset.
  • Thanks to the R package community and all contributors to this package’s development.
  • If you use geobounds and the underlying geoBoundaries data, please cite both.

Citation

Hernangómez D (2026). geobounds: Download Administrative Boundary Data from geoBoundaries. doi:10.32614/CRAN.package.geobounds. https://dieghernan.github.io/geobounds/.

A BibTeX entry for LaTeX users:

@Manual{R-geobounds,
  title = {{geobounds}: Download Administrative Boundary Data from geoBoundaries},
  author = {Diego Hernangómez},
  year = {2026},
  version = {0.1.2},
  url = {https://dieghernan.github.io/geobounds/},
  abstract = {Provides tools for downloading individual country files and global composite files from geoBoundaries <https://www.geoboundaries.org/> across multiple administrative (ADM) levels. Returns boundary data as sf objects for mapping and spatial analysis. Runfola et al. (2020) <doi:10.1371/journal.pone.0231866> describe the underlying database.},
  doi = {10.32614/CRAN.package.geobounds},
}

References

Runfola, Daniel, Austin Anderson, Heather Baier, et al. 2020. “geoBoundaries: A Global Database of Political Administrative Boundaries.” PLOS ONE 15 (4): 1–9. https://doi.org/10.1371/journal.pone.0231866.