Package {geobounds}

Title:	Download Administrative Boundary Data from 'geoBoundaries'
Version:	1.0.0
Description:	Provides tools to download individual country boundaries and global composite boundaries from 'geoBoundaries' https://www.geoboundaries.org/ across multiple administrative ('ADM') levels. Returns boundaries as 'sf' objects for mapping and spatial analysis. Runfola et al. (2020) <doi:10.1371/journal.pone.0231866> describe the underlying database.
License:	MIT + file LICENSE
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, quarto, testthat (≥ 3.0.0), tibble, withr
VignetteBuilder:	quarto
Config/Needs/website:	dieghernan/gitdevr, xfun, devtools, remotes, reactable
Config/roxygen2/markdown:	TRUE
Config/roxygen2/version:	8.0.0
Config/testthat/edition:	3
Config/testthat/parallel:	true
Copyright:	Package code is MIT licensed. See file COPYRIGHTS for data and figure attribution.
Encoding:	UTF-8
Language:	en-US
X-schema.org-keywords:	administrative-boundaries, api, geoboundaries, r, r-package, spatial-data, cran, cran-r
NeedsCompilation:	no
Packaged:	2026-07-08 15:36:49 UTC; diego
Author:	Diego Hernangómez [aut, cre, cph], William and Mary geoLab [cph] (for the geoBoundaries project)
Maintainer:	Diego Hernangómez <diego.hernangomezherrero@gmail.com>
Repository:	CRAN
Date/Publication:	2026-07-08 16:00:08 UTC

geobounds: Download Administrative Boundary Data from 'geoBoundaries'

Description

Provides tools to download individual country boundaries and global composite boundaries from 'geoBoundaries' https://www.geoboundaries.org/ across multiple administrative ('ADM') levels. Returns boundaries as 'sf' objects for mapping and spatial analysis. Runfola et al. (2020) doi:10.1371/journal.pone.0231866 describe the underlying database.

Author(s)

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

Authors:

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

Other contributors:

• William and Mary geoLab (ROR) (for the geoBoundaries project) [copyright holder]

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.

See Also

Useful links:

• https://dieghernan.github.io/geobounds/

• https://github.com/dieghernan/geobounds

• Report bugs at https://github.com/dieghernan/geobounds/issues

Clear the geobounds cache directory

Description

Use this function with caution. It clears cached archives and configuration by deleting the geobounds configuration directory (tools::R_user_dir("geobounds", "config")), deleting the active cache directory and clearing Sys.getenv("GEOBOUNDS_CACHE_DIR").

Usage

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

Arguments

Details

This reset restores the cache state of a fresh geobounds installation.

Value

Invisibly returns NULL. This function is called for its side effects.

See Also

Cache management functions: 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 directory.
ex <- file.path(tempdir(), "example", "cache")
gb_set_cache_dir(ex, quiet = TRUE)

gb_clear_cache(quiet = FALSE)

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

## End(Not run)

Detect the geobounds cache directory

Description

Detects the active cache directory. See gb_set_cache_dir().

Usage

gb_detect_cache_dir(x = NULL)

Arguments

Value

A character scalar containing the path to the active cache directory. The path is also printed as a clickable message. See cli::inline-markup from cli.

See Also

Cache management functions: gb_clear_cache(), gb_set_cache_dir()

Examples

gb_detect_cache_dir()

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. Attribution to geoBoundaries and the original sources is required when sharing the boundaries or derived products.

Usage

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

Arguments

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.

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.

Value

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

Source

geoBoundaries API.

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.

See Also

• gb_get_metadata() inspects boundary metadata and licensing.

• gb_get_max_adm_lvl() checks available ADM levels.

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

Download country boundaries for one ADM level

Description

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
)

Arguments

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.

Value

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

Source

geoBoundaries API.

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.

See Also

• gb_get_metadata() inspects boundary metadata and licensing.

• gb_get_max_adm_lvl() checks available ADM levels.

Boundary download 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 administrative boundaries",
    subtitle = "Selected countries",
    caption = paste(
      "Sources: geoBoundaries and the original boundary providers,",
      "check gb_get_metadata() for licenses"
    )
  )

Find the highest available ADM level

Description

Returns a summary of selected country codes and their highest available ADM level in geoBoundaries.

Usage

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

Arguments

Value

A tibble from tibble containing ISO 3166-1 alpha-3 country codes and their highest available ADM levels.

Source

geoBoundaries API.

See Also

gb_get() downloads boundaries for the available ADM levels.

Metadata and licensing functions: gb_get_metadata()

Examples

all <- gb_get_max_adm_lvl()
library(dplyr)

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

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

Retrieve boundary metadata from geoBoundaries

Description

Returns boundary metadata from the geoBoundaries API.

Usage

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

Arguments

Details

The result is a tibble from tibble with the following columns:

• boundaryID: The ID for this layer. It combines the ISO code, boundary type and a unique identifier generated from the input metadata and geometry. This only changes if the underlying boundary changes.

• boundaryName: The name of the country represented by the layer.

• boundaryISO: The ISO 3166-1 alpha-3 code for the country.

• boundaryYearRepresented: The year or range of years in "START to END" format that the boundary layers represent.

• boundaryType: The type of boundary.

• boundaryCanonical: The canonical name of the boundary.

• boundarySource: A comma-separated list of the primary sources for the boundary.

• boundaryLicense: The original license under which the primary source released the boundary.

• licenseDetail: Notes about the license.

• licenseSource: The URL of the primary source.

• sourceDataUpdateDate: The date the source information was integrated into the geoBoundaries repository.

• buildDate: The date the source boundary was most recently standardized and built into a geoBoundaries release.

• Continent: The continent the country is associated with.

• UNSDG-region: The United Nations Sustainable Development Goals (SDG) region the country is associated with.

• UNSDG-subregion: The United Nations Sustainable Development Goals (SDG) subregion the country is associated with.

• worldBankIncomeGroup: The World Bank income group the country is associated with.

• admUnitCount: The number of administrative units in the boundary.

• meanVertices: The mean number of vertices defining the boundaries of each administrative unit in the layer.

• minVertices: The minimum number of vertices defining a boundary.

• maxVertices: The maximum number of vertices defining a boundary.

• minPerimeterLengthKM: The minimum perimeter length of an administrative unit in the layer, measured in kilometers and based on a World Equidistant Cylindrical projection.

• meanPerimeterLengthKM: The mean perimeter length of an administrative unit in the layer, measured in kilometers and based on a World Equidistant Cylindrical projection.

• maxPerimeterLengthKM: The maximum perimeter length of an administrative unit in the layer, measured in kilometers and based on a World Equidistant Cylindrical projection.

• meanAreaSqKM: The mean area of all administrative units in the layer, measured in square kilometers and based on an EASE-GRID 2 projection.

• minAreaSqKM: The minimum area of an administrative unit in the layer, measured in square kilometers and based on an EASE-GRID 2 projection.

• maxAreaSqKM: The maximum area of an administrative unit in the layer, measured in square kilometers and based on an EASE-GRID 2 projection.

• staticDownloadLink: The static download link for the aggregate ZIP file containing all boundary information.

• gjDownloadURL: The static download link for the GeoJSON.

• tjDownloadURL: The static download link for the TopoJSON.

• imagePreview: The static download link for an automatically rendered PNG image of the layer.

• simplifiedGeometryGeoJSON: The static download link for the simplified GeoJSON.

Value

A tibble from tibble with one row per matching boundary and the columns described in Details.

Source

geoBoundaries API.

See Also

gb_get() downloads the boundaries described by the metadata.

Metadata and licensing functions: gb_get_max_adm_lvl()

Examples

# Get boundary metadata for ADM4.

library(dplyr)

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

Download global composite boundaries from geoBoundaries

Description

Returns global composite boundaries for the requested ADM level. Boundaries are clipped to international borders, with gaps between borders filled.

CGAZ boundaries are not covered by the package's MIT license. Attribution is required when sharing the boundaries or derived products.

Usage

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

Arguments

Details

Comprehensive Global Administrative Zones (CGAZ) are global composites for administrative boundaries. Compared with individual country boundaries, global composite boundaries use extensive simplification so file sizes are small enough for most desktop software. They remove disputed areas, replace them with polygons following United States Department of State definitions and fill gaps between borders.

Follow the citation and use information included in the downloaded CGAZ archive. CGAZ and figures derived from it are not relicensed under the package's MIT license.

Value

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

Source

geoBoundaries API.

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.

See Also

• gb_get_metadata() inspects boundary metadata and licensing.

• gb_get_max_adm_lvl() checks the ADM levels available for individual country boundaries.

Boundary download 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: geoBoundaries (CGAZ)")

## End(Not run)

Set the geobounds cache directory

Description

Sets the active cache directory and optionally saves it for future sessions. Use gb_detect_cache_dir() to find the active cache directory.

Usage

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

Arguments

Details

By default, when no cache_dir is set, geobounds uses a directory inside base::tempdir(). Cached archives in this directory are removed when the R session ends. To reuse a cache directory across R sessions, use gb_set_cache_dir(cache_dir = "a/path/here", install = TRUE). This saves the directory in a configuration file under tools::R_user_dir("geobounds", "config").

Value

An invisible character scalar containing the path to the cache directory.

Cache strategies

• For occasional use, use the default temporary cache directory.

• Set the cache directory for the current session with gb_set_cache_dir(cache_dir = "a/path/here").

• Save a persistent cache directory for future R sessions with gb_set_cache_dir(cache_dir = "a/path/here", install = TRUE).

• Set the cache directory for an individual download with the cache_dir argument. See gb_get().

See Also

tools::R_user_dir() identifies standard locations for user-specific files.

Cache management functions: 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 directory.
ex <- file.path(tempdir(), "example", "cachenew")
gb_set_cache_dir(ex)

gb_detect_cache_dir()

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

## End(Not run)

gb_detect_cache_dir()