Comparison between full vs. simplified map.
Attribution is required when using geoBoundaries.
The geobounds package provides a straightforward interface for downloading and working with global administrative boundary data from the geoBoundaries project (Runfola et al. 2020).
The default gbOpen release is CC BY 4.0 compliant when attribution is provided and covers countries worldwide across multiple administrative levels. The package also supports gbHumanitarian and gbAuthoritative release types, which vary in source, validation process and licensing. With geobounds, you can fetch boundary geometries as sf objects, explore metadata, cache datasets locally and integrate the boundaries into your spatial workflows.
The geoBoundaries database undergoes a rigorous quality assurance process, including manual review and hand-digitization of physical maps where necessary. Its primary goal is to provide the highest possible level of spatial accuracy for scientific and academic applications.
This precision comes at a cost: some files can be quite large and may take longer to download. For visualization or general mapping purposes, we recommend using the simplified datasets by setting simplified = TRUE.
library(geobounds)
library(ggplot2)
library(dplyr)
# Compare resolutions.
norway <- gb_get_adm0("NOR") |>
mutate(res = "Full resolution")
print(object.size(norway), units = "Mb")
#> 26.5 Mb
norway_simp <- gb_get_adm0(country = "NOR", simplified = TRUE) |>
mutate(res = "Simplified")
print(object.size(norway_simp), units = "Mb")
#> 1.5 Mb
norway_all <- bind_rows(norway, norway_simp)
# Plot with ggplot2.
ggplot(norway_all) +
geom_sf(fill = "#BA0C2F", color = "#00205B") +
facet_wrap(vars(res)) +
theme_minimal() +
labs(caption = "Source: www.geoboundaries.org")Comparison between full vs. simplified map.
The geoBoundaries API provides individual country files, whose aim is to represent every nation “as they would represent themselves”, without special identification of disputed areas.
Download individual country files with gb_get() or the ?gb_get_adm wrappers. Borders are not guaranteed to align perfectly, gaps may exist between countries and disputed territories may not be represented consistently.
india_pak <- gb_get_adm0(c("India", "Pakistan"))
# Highlight the disputed Kashmir area.
ggplot(india_pak) +
geom_sf(aes(fill = shapeName), alpha = 0.5) +
scale_fill_manual(values = c("#FF671F", "#00401A")) +
labs(
fill = "Country",
title = "Map of India and Pakistan",
subtitle = "Note the overlap in the Kashmir region",
caption = "Source: www.geoboundaries.org"
)
Map showing overlap in the disputed Kashmir area.
Note that individual country files are governed by the license or licenses identified within the metadata for each respective boundary.
gb_get_metadata(c("India", "Pakistan"), adm_lvl = "ADM0") |>
select(boundaryName, boundaryLicense, boundarySource)
#> # A tibble: 2 × 3
#> boundaryName boundaryLicense boundarySource
#> <chr> <chr> <chr>
#> 1 India CC0 1.0 Universal (CC0 1.0) Public … geoBoundaries…
#> 2 Pakistan Open Data Commons Open Database Lic… OpenStreetMap…Use gb_get_world() for data where disputed areas are explicitly handled by removing overlaps and filling gaps. This function downloads global composite files for administrative boundaries, also known as Comprehensive Global Administrative Zones (CGAZ). There are three important distinctions between CGAZ and individual country files:
cgaz_india_pak <- gb_get_world(c("India", "Pakistan"))
ggplot(cgaz_india_pak) +
geom_sf(aes(fill = shapeName), alpha = 0.5) +
scale_fill_manual(values = c("#FF671F", "#00401A")) +
labs(
fill = "Country",
title = "Map of India and Pakistan",
subtitle = "CGAZ does not overlap",
caption = "Source: www.geoboundaries.org"
)
Map showing no overlap in Kashmir, provided by CGAZ.
The package provides a built-in mechanism to cache files locally so that repeated downloads for the same country and administrative level use the cached version. For example:
# Show the current folder.
current <- gb_detect_cache_dir()
#> ℹ 'C:\Users\diego\AppData\Local\Temp\RtmpoLuvEM'
current
#> [1] "C:\\Users\\diego\\AppData\\Local\\Temp\\RtmpoLuvEM"
# Change to a new folder.
newdir <- file.path(tempdir(), "/geoboundvignette")
gb_set_cache_dir(newdir)
#> ✔ geobounds cache directory is 'C:\Users\diego\AppData\Local\Temp\RtmpoLuvEM//geoboundvignette'.
#> ℹ To install your `cache_dir` path for use in future sessions run this function with `install = TRUE`.
# Download the example data.
example <- gb_get_adm0("Vatican City", quiet = FALSE)
#> ℹ Downloading file from <https://github.com/wmgeolab/geoBoundaries/raw/9469f09/releaseData/gbOpen/VAT/ADM0/geoBoundaries-VAT-ADM0-all.zip>.
#> → Cache directory is 'C:\Users\diego\AppData\Local\Temp\RtmpoLuvEM//geoboundvignette/gbOpen'.
# Restore the cache directory.
gb_set_cache_dir(current)
#> ✔ geobounds cache directory is 'C:\Users\diego\AppData\Local\Temp\RtmpoLuvEM'.
#> ℹ To install your `cache_dir` path for use in future sessions run this function with `install = TRUE`.
current == gb_detect_cache_dir()
#> ℹ 'C:\Users\diego\AppData\Local\Temp\RtmpoLuvEM'
#> [1] TRUETo clear the cache, use gb_clear_cache().
Set a specific cache directory for each function call with the cache_dir argument.
Because the boundaries are returned as sf objects, you can use them with other spatial data:
This example creates a choropleth map using metadata from individual country files and boundary data from CGAZ:
# Retrieve metadata.
latam_meta <- gb_get_metadata(adm_lvl = "ADM0") |>
select(boundaryISO, boundaryName, Continent, worldBankIncomeGroup) |>
filter(Continent == "Latin America and the Caribbean") |>
glimpse()
#> Rows: 47
#> Columns: 4
#> $ boundaryISO <chr> "ABW", "AIA", "ARG", "ATG", "BES", …
#> $ boundaryName <chr> "Aruba", "Anguilla", "Argentina", "…
#> $ Continent <chr> "Latin America and the Caribbean", …
#> $ worldBankIncomeGroup <chr> "High-income Countries", "No income…
# Adjust factors.
latam_meta$income_factor <- factor(
latam_meta$worldBankIncomeGroup,
levels = c(
"High-income Countries",
"Upper-middle-income Countries",
"Lower-middle-income Countries",
"Low-income Countries"
)
)
# Get the shapes from CGAZ.
latam_sf <- gb_get_world(adm_lvl = "ADM0") |>
inner_join(latam_meta, by = c("shapeGroup" = "boundaryISO"))
ggplot(latam_sf) +
geom_sf(aes(fill = income_factor)) +
scale_fill_brewer(palette = "Greens", direction = -1) +
guides(fill = guide_legend(position = "bottom", nrow = 2)) +
coord_sf(
crs = "+proj=laea +lon_0=-75 +lat_0=-15"
) +
labs(
title = "World Bank Income Group",
subtitle = "Latin America and the Caribbean",
fill = "",
caption = "Source: www.geoboundaries.org"
)
World Bank Income Group: Latin America and the Caribbean.
The geobounds package makes it easy to fetch, manage and visualize administrative boundary data worldwide in a reproducible way. Whether you are mapping, doing spatial analysis, integrating survey data or modeling geospatial patterns, it gives you access to high-quality boundary data with minimal overhead.