Skip to contents

Get individual country files from geoBoundaries

Source: R/gb-get.R
gb_get.Rd

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

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 Service https://www.geoboundaries.org/api.html.

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

Value

A sf object.

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:

  • gb_get_adm0() returns the country boundary.

  • gb_get_adm1() returns first-level administrative boundaries (e.g. States in the United States).

  • gb_get_adm2() returns second-level administrative boundaries (e.g. Counties in the United States).

  • gb_get_adm3() returns third-level administrative boundaries (e.g. towns or cities in some countries).

  • gb_get_adm4() returns fourth-level administrative boundaries.

  • gb_get_adm5() returns fifth-level administrative boundaries.

References

Runfola, D. et al. (2020) geoBoundaries: A global database of political administrative boundaries. PLoS ONE 15(4): e0231866. doi:10.1371/journal.pone.0231866 .

See also

Other API functions: gb_get_adm, gb_get_cgaz()

Examples

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

# }

# Metadata
library(dplyr)
#> 
#> Attaching package: 'dplyr'
#> The following objects are masked from 'package:stats':
#> 
#>     filter, lag
#> The following objects are masked from 'package:base':
#> 
#>     intersect, setdiff, setequal, union
gb_get_metadata(
  "Sri Lanka",
  adm_lvl = 2
) |>
  # Check individual license
  select(boundaryISO, boundaryType, licenseDetail, licenseSource) |>
  glimpse()
#> Rows: 1
#> Columns: 4
#> $ boundaryISO   <chr> "LKA"
#> $ boundaryType  <chr> "ADM2"
#> $ licenseDetail <chr> "Open Data Commons Open Database License 1.0"
#> $ licenseSource <chr> "www.openstreetmap.org/copyright"