The hardware and bandwidth for this mirror is donated by dogado GmbH, the Webhosting and Full Service-Cloud Provider. Check out our Wordpress Tutorial.
If you wish to report a bug, or if you are interested in having us mirror your free-software or open-source project, please feel free to contact us at mirror[@]dogado.de.

geobounds

Attribution is required when using geoBoundaries.

Why this package?

The geobounds package provides an R-friendly interface to access and work with the geoBoundaries dataset (an open-license global database of administrative boundary polygons). Using this package, you can:

• Programmatically retrieve administrative boundary geometries (e.g., country → region → district) from geoBoundaries
• Use tidyverse / sf workflows in R to map, analyse and join these boundaries with your own data
• Work in an open-data context (geoBoundaries uses CC BY-4.0) / open licenses)

In short: if you work with geospatial boundaries in R (shape files, polygons, join with other data), this package simplifies the process.

Installation

Install geobounds from CRAN (when accepted):

install.packages("geobounds")

You can install the developing version of geobounds with:

# install.packages("pak")
pak::pak("dieghernan/geobounds")

Alternatively, you can install geobounds using the r-universe:

# Install geobounds in R:
install.packages(
  "geobounds",
  repos = c(
    "https://dieghernan.r-universe.dev",
    "https://cloud.r-project.org"
  )
)

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()

Data Types

geoBoundaries offers different release types with varying levels of validation and licensing:

• gbOpen: Freely available boundaries under CC BY 4.0, suitable for most applications
• gbHumanitarian: Boundaries validated for humanitarian work, ensuring accuracy for aid distribution
• gbAuthoritative: Official government boundaries, highest accuracy but may have restrictions

Use the release_type parameter in functions to specify, e.g., gb_get_adm1("Sri Lanka", release_type = "gbHumanitarian").

For detailed comparisons, see the vignettes.

Advanced usage

Get a map with the level of coverage of 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: Administrative Divisions (ADMs)",
    caption = "Source: www.geoboundaries.org"
  )

Documentation & Resources

• Visit the pkgdown site for full documentation: https://dieghernan.github.io/geobounds/
• Vignettes on data releases:
  • gbOpen
  • gbHumanitarian
  • gbAuthoritative
• Explore the geoBoundaries homepage: https://www.geoboundaries.org/
• Read the original paper describing the geoBoundaries dataset (Runfola et al. 2020).
• Report issues or contribute on GitHub

License

This package is released under the CC BY-4.0 license. Note that the boundary data being accessed (via geoBoundaries) also uses open licenses; please check the specific dataset metadata for licensing details.

Acknowledgements

• Many 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 underlying geoBoundaries data) in your research or project, a citation and acknowledgment is greatly appreciated.

Citation

Hernangómez D (2026). geobounds: Download Map Data from geoBoundaries. doi:10.5281/zenodo.17554275, https://dieghernan.github.io/geobounds/.

A BibTeX entry for LaTeX users:

@Manual{R-geobounds,
  title = {{geobounds}: Download Map Data from geoBoundaries},
  author = {Diego Hernangómez},
  year = {2026},
  version = {0.1.0},
  url = {https://dieghernan.github.io/geobounds/},
  abstract = {Tools to download data from geoBoundaries <https://www.geoboundaries.org/>. Several administration levels available. See Runfola, D. et al. (2020) geoBoundaries: A global database of political administrative boundaries. PLOS ONE 15(4): 1-9. <doi:10.1371/journal.pone.0231866>.},
  doi = {10.5281/zenodo.17554275},
}

References

These binaries (installable software) and packages are in development.
They may not be fully stable and should be used with caution. We make no claims about them.
Health stats visible at Monitor.