Download country boundaries for one ADM level

These functions call gb_get() for a single ADM level. gb_get_adm0() returns country boundaries, gb_get_adm1() returns first-level subnational boundaries (for example, states in the United States) and gb_get_adm2() returns second-level subnational boundaries (for example, counties in the United States). gb_get_adm3(), gb_get_adm4() and gb_get_adm5() return third-, fourth- and fifth-level administrative boundaries, respectively.

Not all countries have the same number of ADM levels. Use gb_get_max_adm_lvl() to check availability.

Boundaries downloaded through these functions are not covered by the package's MIT license. Attribution to geoBoundaries and the original sources is required when sharing the boundaries or derived products.

Usage

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

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

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

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

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

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

Source

geoBoundaries API.

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.
simplified: A logical value. If TRUE, return simplified boundaries. The default FALSE uses the primary geoBoundaries layer. See simplified boundaries at https://www.geoboundaries.org/.
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().

Value

An sf object from sf containing the requested boundaries. If no boundaries match the request, the function returns NULL.

Details

Each individual country boundary layer is governed by the original license identified in its boundary metadata. See gb_get_metadata(). Users should cite the sources listed in the metadata and comply with any attribution, share-alike or non-commercial terms.

References

Runfola et al. (2020) "geoBoundaries: A global database of political administrative boundaries." PLOS ONE, 15(4), 1–9. doi:10.1371/journal.pone.0231866 .

Examples

# \donttest{
lev2 <- gb_get_adm2(
  c("Italia", "Suiza", "Austria"),
  simplified = TRUE
)

library(ggplot2)

ggplot(lev2) +
  geom_sf(aes(fill = shapeGroup)) +
  labs(
    title = "Second-level administrative boundaries",
    subtitle = "Selected countries",
    caption = paste(
      "Sources: geoBoundaries and the original boundary providers,",
      "check gb_get_metadata() for licenses"
    )
  )

# }