Title: Download Map Data from 'geoBoundaries'
Version: 0.1.0
Description: 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>.
License: CC BY 4.0
URL: https://dieghernan.github.io/geobounds/, https://github.com/dieghernan/geobounds
BugReports: https://github.com/dieghernan/geobounds/issues
Depends: R (≥ 4.1.0)
Imports: cli, countrycode, dplyr, httr2 (≥ 1.0.0), sf, tools, utils
Suggests: ggplot2, jsonlite, knitr, rmarkdown, testthat (≥ 3.0.0), tibble
VignetteBuilder: knitr
Config/Needs/website: dieghernan/gitdevr, xfun, devtools, remotes, reactable, magick
Config/testthat/edition: 3
Config/testthat/parallel: false
Copyright: Attribution required. See file COPYRIGHTS for specific provisions.
Encoding: UTF-8
Language: en-US
RoxygenNote: 7.3.3
X-schema.org-keywords: administrative-boundaries, api, geoboundaries, r, r-package, spatial-data
NeedsCompilation: no
Packaged: 2026-02-09 05:37:13 UTC; diego
Author: Diego Hernangómez ORCID iD [aut, cre, cph], William and Mary geoLab [cph]
Maintainer: Diego Hernangómez <diego.hernangomezherrero@gmail.com>
Repository: CRAN
Date/Publication: 2026-02-11 20:00:02 UTC

geobounds: Download Map Data from 'geoBoundaries'

Description

logo

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.

Author(s)

Maintainer: Diego Hernangómez diego.hernangomezherrero@gmail.com (ORCID) [copyright holder]

Other contributors:

See Also

Useful links:


Clear your geobounds cache directory

Description

Use this function with caution. This function will clear your cached data and configuration, specifically:

Usage

gb_clear_cache(config = FALSE, cached_data = TRUE, quiet = TRUE)

Arguments

config

Logical. If TRUE, will delete the configuration folder of geobounds.

cached_data

Logical. If TRUE, it will delete your cache_dir and all its content.

quiet

logical. If TRUE suppresses informational messages.

Details

This is a comprehensive reset function that is intended to reset your status as if you had never installed or used geobounds.

Value

invisible() This function is called for its side effects.

See Also

Other cache utilities: gb_detect_cache_dir(), gb_set_cache_dir()

Examples


# Caution! This may modify your current state

## Not run: 
my_cache <- gb_detect_cache_dir()
# Set an example cache
ex <- file.path(tempdir(), "example", "cache")
gb_set_cache_dir(ex, quiet = TRUE)

gb_clear_cache(quiet = FALSE)

# Restore initial cache
gb_set_cache_dir(my_cache)
identical(my_cache, gb_detect_cache_dir())

## End(Not run)


Detect cache directory for geobounds

Description

Helper function to detect the current cache folder. See gb_set_cache_dir().

Usage

gb_detect_cache_dir(x = NULL)

Arguments

x

Ignored.

Value

A character with the path to your cache_dir. The same path will appear also as a clickable message, see cli::inline-markup.

See Also

Other cache utilities: gb_clear_cache(), gb_set_cache_dir()

Examples

gb_detect_cache_dir()


Get individual country files from geoBoundaries

Description

Attribution is required for all uses of this dataset.

This function returns data of individual countries "as they would represent themselves", with no special identification of disputed areas.

If you would prefer data that explicitly includes disputed areas, please use gb_get_world().

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 codes. It can be either "all" (that would return the data for all countries), a vector of country names or ISO3 country codes. See also countrycode::countrycode().

adm_lvl

Type of boundary. Accepted values are "all" (all available boundaries) or the ADM level ("adm0" is the country boundary, "adm1" is the first level of sub-national boundaries, "adm2" is the second level, and so on). Upper-case versions ("ADM1") and the number of the level (⁠1, 2, 3, 4, 5⁠) are also accepted.

simplified

logical. Return the simplified boundary or not. The default FALSE uses the premier geoBoundaries release.

release_type

One of "gbOpen", "gbHumanitarian", "gbAuthoritative". For most users, we suggest using "gbOpen" (the default), as it is CC-BY 4.0 compliant and can be used for most purposes so long as attribution is provided:

  • "gbHumanitarian" files are mirrored from UN OCHA, but may have more restrictive licensing.

  • "gbAuthoritative" files are mirrored from UN SALB, and cannot be used for commercial purposes, but are verified through in-country processes.

quiet

logical. If TRUE suppresses informational messages.

overwrite

logical. When set to TRUE it will force a fresh download of the source .zip file.

cache_dir

A path to a cache directory. If not set (the default NULL), the data will be stored in the default cache directory (see gb_set_cache_dir()). If no cache directory has been set, files will be stored in the temporary directory (see base::tempdir()). See caching strategies in gb_set_cache_dir().

Details

Individual data files in the geoBoundaries database are governed by the license or licenses identified within the metadata for each respective boundary (see gb_get_metadata(). Users using individual boundary files from geoBoundaries should additionally ensure that they cite the sources provided in the metadata for each file. See Examples.

The following wrappers are also available:

Value

A sf object.

Source

geoBoundaries API Service https://www.geoboundaries.org/api.html.

References

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.

See Also

Other API functions: gb_get_adm, gb_get_world()

Examples



# Map level 2 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 = "Source: www.geoboundaries.org")


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


Get country files from geoBoundaries for a given administrative level

Description

Attribution is required for all uses of this dataset.

These functions are wrappers of gb_get() for extracting any given administrative level:

Note that not all countries have the same number of levels. Check gb_get_max_adm_lvl.

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
)

Arguments

country

A character vector of country codes. It can be either "all" (that would return the data for all countries), a vector of country names or ISO3 country codes. See also countrycode::countrycode().

simplified

logical. Return the simplified boundary or not. The default FALSE uses the premier geoBoundaries release.

release_type

One of "gbOpen", "gbHumanitarian", "gbAuthoritative". For most users, we suggest using "gbOpen" (the default), as it is CC-BY 4.0 compliant and can be used for most purposes so long as attribution is provided:

  • "gbHumanitarian" files are mirrored from UN OCHA, but may have more restrictive licensing.

  • "gbAuthoritative" files are mirrored from UN SALB, and cannot be used for commercial purposes, but are verified through in-country processes.

quiet

logical. If TRUE suppresses informational messages.

overwrite

logical. When set to TRUE it will force a fresh download of the source .zip file.

cache_dir

A path to a cache directory. If not set (the default NULL), the data will be stored in the default cache directory (see gb_set_cache_dir()). If no cache directory has been set, files will be stored in the temporary directory (see base::tempdir()). See caching strategies in gb_set_cache_dir().

Details

Individual data files in the geoBoundaries database are governed by the license or licenses identified within the metadata for each respective boundary (see gb_get_metadata(). Users using individual boundary files from geoBoundaries should additionally ensure that they are citing the sources provided in the metadata for each file.

Value

A sf object.

Source

geoBoundaries API Service https://www.geoboundaries.org/api.html.

References

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.

See Also

gb_get_max_adm_lvl().

Other API functions: gb_get(), gb_get_world()

Examples



lev2 <- gb_get_adm2(
  c("Italia", "Suiza", "Austria"),
  simplified = TRUE
)

library(ggplot2)

ggplot(lev2) +
  geom_sf(aes(fill = shapeGroup)) +
  labs(
    title = "Second-level administration",
    subtitle = "Selected countries",
    caption = "Source: www.geoboundaries.org"
  )



Get the highest administrative level available for a given country

Description

Get a summary of selected or all countries and their highest administrative level available in geoBoundaries.

Usage

gb_get_max_adm_lvl(
  country = "all",
  release_type = c("gbOpen", "gbHumanitarian", "gbAuthoritative")
)

Arguments

country

A character vector of country codes. It can be either "all" (that would return the data for all countries), a vector of country names or ISO3 country codes. See also countrycode::countrycode().

release_type

One of "gbOpen", "gbHumanitarian", "gbAuthoritative". For most users, we suggest using "gbOpen" (the default), as it is CC-BY 4.0 compliant and can be used for most purposes so long as attribution is provided:

  • "gbHumanitarian" files are mirrored from UN OCHA, but may have more restrictive licensing.

  • "gbAuthoritative" files are mirrored from UN SALB, and cannot be used for commercial purposes, but are verified through in-country processes.

Value

A tibble with the country names and corresponding highest administrative level.

Source

geoBoundaries API Service https://www.geoboundaries.org/api.html.

See Also

Other metadata functions: gb_get_metadata()

Examples


all <- gb_get_max_adm_lvl()
library(dplyr)

# Countries with only 1 level available
all |>
  filter(maxBoundaryType == 1)

# Countries with level 4 available
all |>
  filter(maxBoundaryType == 4)


Get metadata of individual country files from geoBoundaries

Description

This function returns metadata of the geoBoundaries API.

Usage

gb_get_metadata(
  country = "all",
  adm_lvl = "all",
  release_type = c("gbOpen", "gbHumanitarian", "gbAuthoritative")
)

Arguments

country

A character vector of country codes. It can be either "all" (that would return the data for all countries), a vector of country names or ISO3 country codes. See also countrycode::countrycode().

adm_lvl

Type of boundary. Accepted values are "all" (all available boundaries) or the ADM level ("adm0" is the country boundary, "adm1" is the first level of sub-national boundaries, "adm2" is the second level, and so on). Upper-case versions ("ADM1") and the number of the level (⁠1, 2, 3, 4, 5⁠) are also accepted.

release_type

One of "gbOpen", "gbHumanitarian", "gbAuthoritative". For most users, we suggest using "gbOpen" (the default), as it is CC-BY 4.0 compliant and can be used for most purposes so long as attribution is provided:

  • "gbHumanitarian" files are mirrored from UN OCHA, but may have more restrictive licensing.

  • "gbAuthoritative" files are mirrored from UN SALB, and cannot be used for commercial purposes, but are verified through in-country processes.

Details

The result is a tibble with the following columns:

Value

A tibble.

Source

geoBoundaries API Service https://www.geoboundaries.org/api.html.

See Also

gb_get()

Other metadata functions: gb_get_max_adm_lvl()

Examples


# Get metadata of ADM4 levels

library(dplyr)

gb_get_metadata(adm_lvl = "ADM4") |>
  glimpse()


Get global composites data (CGAZ) from geoBoundaries

Description

Attribution is required for all uses of this dataset.

This function returns a global composite of the required administrative level, clipped to international boundaries, with gaps filled between borders.

Usage

gb_get_world(
  country = "all",
  adm_lvl = "adm0",
  quiet = TRUE,
  overwrite = FALSE,
  cache_dir = NULL
)

Arguments

country

A character vector of country codes. It can be either "all" (that would return the data for all countries), a vector of country names or ISO3 country codes. See also countrycode::countrycode().

adm_lvl

Type of boundary. Accepted values are administrative levels 0, 1, and 2 ("adm0" is the country boundary, "adm1" is the first level of sub-national boundaries, "adm2" is the second level, and so on). Upper-case versions ("ADM1") and the number of the level (⁠0, 1, 2⁠) are also accepted.

quiet

logical. If TRUE suppresses informational messages.

overwrite

logical. When set to TRUE it will force a fresh download of the source .zip file.

cache_dir

A path to a cache directory. If not set (the default NULL), the data will be stored in the default cache directory (see gb_set_cache_dir()). If no cache directory has been set, files will be stored in the temporary directory (see base::tempdir()). See caching strategies in gb_set_cache_dir().

Details

Comprehensive Global Administrative Zones (CGAZ) are a set of global composites for administrative boundaries. There are two important distinctions between our global product and individual country downloads.

Value

A sf object.

Source

geoBoundaries API Service https://www.geoboundaries.org/api.html.

References

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.

See Also

Other API functions: gb_get(), gb_get_adm

Examples


# This download may take some time
## Not run: 
world <- gb_get_world()

library(ggplot2)

ggplot(world) +
  geom_sf() +
  coord_sf(expand = FALSE) +
  labs(caption = "Source: www.geoboundaries.org")

## End(Not run)


Set your geobounds cache directory

Description

This function stores your cache_dir path on your local machine and loads it for future sessions. Type gb_detect_cache_dir() to find your cache directory path.

Usage

gb_set_cache_dir(cache_dir, overwrite = FALSE, install = FALSE, quiet = FALSE)

Arguments

cache_dir

A path to a cache directory. If missing, the function will store the cache files in a temporary directory (see base::tempdir()).

overwrite

Logical. If this is set to TRUE, it will overwrite an existing cache_dir.

install

Logical. If TRUE, will install the key in your local machine for use in future sessions. Defaults to FALSE. If cache_dir is FALSE this parameter is set to FALSE automatically.

quiet

logical. If TRUE suppresses informational messages.

Details

By default, when no cache_dir is set the package uses a folder inside base::tempdir() (so files are temporary and are removed when the R session ends). To persist a cache across R sessions, use gb_set_cache_dir(path, install = TRUE), which writes the chosen path to a small configuration file under tools::R_user_dir("geobounds", "config").

Value

An (invisible()) character with the path to your cache_dir.

Caching strategies

See Also

tools::R_user_dir()

Other cache utilities: gb_clear_cache(), gb_detect_cache_dir()

Examples


# Caution! This may modify your current state

## Not run: 
my_cache <- gb_detect_cache_dir()

# Set an example cache
ex <- file.path(tempdir(), "example", "cachenew")
gb_set_cache_dir(ex)

gb_detect_cache_dir()

# Restore initial cache
gb_set_cache_dir(my_cache)
identical(my_cache, gb_detect_cache_dir())

## End(Not run)

gb_detect_cache_dir()