Download individual country boundaries from geoBoundaries

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.

Always acknowledge geoBoundaries and follow the boundary's license. See vignette("metadata", package = "geobounds") for sources and licensing.

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
)

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.

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, read simplified boundaries that are faster to render. Both options download the complete ZIP archive.

release_type

A character string, one of "gbOpen" (the default), "gbHumanitarian" or "gbAuthoritative". Selects a product, not a dataset version. "gbAuthoritative" is restricted to non-commercial use. See vignette("metadata", package = "geobounds") for product sources and licenses.

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 NULL, use the configured directory, or a temporary directory when none is configured. See gb_set_cache_dir().

Value

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

Details

These are terrestrial boundaries, not maritime boundaries. For product selection and mapping workflows, see vignette("geobounds", package = "geobounds").

This function uses current API metadata and reuses cached archives without checking for upstream changes. Historical versions cannot be selected. See vignette("metadata", package = "geobounds") for cache limitations and provenance.

References

Runfola et al. (2020) "geoBoundaries: A global database of political administrative boundaries." PLOS ONE, 15(4), e0231866. 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

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

sri_lanka
#> Simple feature collection with 25 features and 5 fields
#> Geometry type: MULTIPOLYGON
#> Dimension:     XY
#> Bounding box:  xmin: 79.65102 ymin: 5.919017 xmax: 81.87896 ymax: 9.835791
#> Geodetic CRS:  WGS 84
#> # A tibble: 25 × 6
#>    shapeName     shapeISO shapeID shapeGroup shapeType                  geometry
#>  * <chr>         <chr>    <chr>   <chr>      <chr>            <MULTIPOLYGON [°]>
#>  1 Jaffna Distr… LK-41    463711… LKA        ADM2      (((79.7152 9.529465, 79.…
#>  2 Kilinochchi … LK-42    463711… LKA        ADM2      (((80.01015 9.472403, 80…
#>  3 Mannar Distr… LK-43    463711… LKA        ADM2      (((80.11535 9.209068, 80…
#>  4 Mullaitivu D… LK-45    463711… LKA        ADM2      (((80.61353 9.456581, 80…
#>  5 Vavuniya Dis… LK-44    463711… LKA        ADM2      (((80.23541 8.680412, 80…
#>  6 Galle Distri… LK-31    463711… LKA        ADM2      (((79.98757 6.440352, 79…
#>  7 Hambantota D… LK-33    463711… LKA        ADM2      (((80.67006 6.306029, 80…
#>  8 Matara Distr… LK-32    463711… LKA        ADM2      (((80.3818 5.965264, 80.…
#>  9 Ampara Distr… LK-52    463711… LKA        ADM2      (((81.70788 6.51073, 81.…
#> 10 Anuradhapura… LK-71    463711… LKA        ADM2      (((80.03237 8.527211, 80…
#> # ℹ 15 more rows

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

# }