gb_get: Download individual country boundaries from *geoBoundaries*

In geobounds: Download Administrative Boundary Data from 'geoBoundaries'

Download individual country boundaries from geoBoundaries

Description

Returns individual country boundaries that reflect how countries represent their own boundaries, without special identification of disputed areas.

Use gb_get_world() for global composite boundaries that standardize disputed areas and fill gaps between borders.

Boundaries downloaded through this function are not covered by the package's MIT license. Always acknowledge geoBoundaries when sharing the boundaries or derived products. See https://www.geoboundaries.org/index.html#usage. Consult the boundary metadata for any additional source attribution, license link, share-alike notice or modification statement required by the boundary's license.

The wrappers gb_get_adm0(), gb_get_adm1(), gb_get_adm2(), gb_get_adm3(), gb_get_adm4() and gb_get_adm5() are also available for requesting a single ADM level.

Usage

gb_get(
  country,
  adm_lvl = "adm0",
  simplified = FALSE,
  release_type = c("gbOpen", "gbHumanitarian", "gbAuthoritative"),
  quiet = TRUE,
  overwrite = FALSE,
  cache_dir = NULL
)

Arguments

country	A character vector of country names or ISO 3166-1 alpha-3 country codes. Use "all" to return boundaries for all countries. See also countrycode::countrycode() from countrycode.
adm_lvl	ADM level. Accepted values are "all" (all available boundaries) or the ADM level ("adm0" is the country boundary, "adm1" is the first level of subnational boundaries, "adm2" is the second level and so on). Uppercase versions ("ADM1") and level numbers (0, 1, 2, 3, 4, 5) are also accepted, including numbers supplied as text (for example, "1").
simplified	A logical value. If TRUE, return boundaries that are less accurate but faster to render. The default FALSE uses the primary geoBoundaries layer. See the simplified boundary downloads: https://www.geoboundaries.org/simplifiedDownloads.html.
release_type	A character string, one of "gbOpen", "gbHumanitarian" or "gbAuthoritative". For most users, use "gbOpen" (the default), which contains openly licensed boundaries suitable for most purposes when their individual license terms are followed. "gbHumanitarian" boundaries are mirrored from UN OCHA and may have additional conditions. "gbAuthoritative" boundaries are mirrored from UN SALB, verified through in-country processes and cannot be used for commercial purposes.
quiet	A logical value. If TRUE, suppress informational messages.
overwrite	A logical value. If TRUE, force a fresh download of the source .zip archive.
cache_dir	A path to a cache directory. If not set (the default NULL), boundary archives are stored in the default cache directory (see gb_set_cache_dir()). If no cache directory has been set, archives are stored in a temporary cache directory. See base::tempdir() and the cache strategies in gb_set_cache_dir().

Details

Each individual country boundary layer is governed by the original license identified in its boundary metadata. See gb_get_metadata(). The "gbOpen" release contains multiple open licenses, including ODbL and CC BY-SA. Do not assume every boundary is licensed only under CC BY 4.0. Users should cite the sources listed in the metadata and comply with any attribution, share-alike or non-commercial terms.

Value

An sf object from sf containing the requested boundaries. Returns NULL if no boundaries match the request or the downloads return no geometries.

Source

geoBoundaries API.

References

Runfola et al. (2020) "geoBoundaries: A global database of political administrative boundaries." PLOS ONE, 15(4), 1–9. \Sexpr[results=rd]{tools:::Rd_expr_doi("10.1371/journal.pone.0231866")}.

See Also

gb_get_metadata() inspects boundary metadata and licensing. gb_get_max_adm_lvl() checks the ADM levels available for individual country boundaries. gb_set_cache_dir() configures where downloaded archives are cached.

Boundary download functions: gb_get_adm, gb_get_world()

Examples

# Map ADM2 in Sri Lanka.
sri_lanka <- gb_get(
  "Sri Lanka",
  adm_lvl = 2,
  simplified = TRUE
)

sri_lanka

library(ggplot2)
ggplot(sri_lanka) +
  geom_sf() +
  labs(
    caption = paste(
      "Sources: geoBoundaries, OpenStreetMap and Wambacher,",
      "license: ODbL 1.0"
    )
  )


# Inspect boundary metadata.
library(dplyr)
gb_get_metadata(
  "Sri Lanka",
  adm_lvl = 2
) |>
  # Check the individual license.
  select(boundaryISO, boundaryType, licenseDetail, licenseSource) |>
  glimpse()

geobounds documentation built on Sept. 6, 2026, 1:06 a.m.