Get Brazilian municipalities data

brazil_municipality() returns a tibble with data about Brazilian municipalities.

Note: This function requires an internet connection to work and the geobr or geocodebr package to be installed, depending on the chosen method for retrieving coordinates.

Usage

brazil_municipality(
  municipality = NULL,
  state = NULL,
  year = as.numeric(substr(Sys.Date(), 1, 4)),
  coords_method = "geobr",
  force = FALSE
)

Arguments

municipality

(optional) A character vector with the name of the municipalities. If NULL the function returns all municipalities (default: NULL).

state

(optional) A character vector with the name of the states (default: NULL).

year

(optional) An integerish number indicating the year of the data regarding the municipalities (default: Sys.Date() |> substr(1, 4) |> as.numeric()).

coords_method

(optional) A string indicating the method to retrieve the latitude and longitude coordinates of the municipalities (default: "geobr"). Options are:

• "geobr": Uses read_municipal_seat() from the geobr package to retrieve the coordinates.

• "geocodebr": Uses the geocode() from the geocodebr package to retrieve the coordinates.

force

(optional) A logical flag indicating whether to force the download of the data again (default: FALSE).

Value

A tibble with the following columns:

• region_code: The region code.

• region: The region name.

• state_code: The state code.

• state: The state name.

• federal_unit: The state abbreviation.

• municipality_code: The municipality code.

• municipality: The municipality name.

• latitude: The municipality latitude.

• longitude: The municipality longitude.

Details

The data from this function is based on data from the Brazilian Institute of Geography and Statistics (IBGE) via the geobr and geocodebr R packages.

Both packages are produced by Brazil's Institute for Applied Economic Research (IPEA) and access the Brazilian Institute of Geography and Statistics (IBGE) data.

See also

Other Brazil functions: brazil_fu(), brazil_municipality_code(), brazil_municipality_coords(), brazil_municipality_latitude(), brazil_municipality_longitude(), brazil_region(), brazil_region_code(), brazil_render_address(), brazil_state(), brazil_state_by_utc(), brazil_state_capital(), brazil_state_code(), brazil_state_latitude(), brazil_state_longitude()

Examples

library(curl)
#> Using libcurl 8.5.0 with OpenSSL/3.0.13
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

# \dontrun{
  if (has_internet()) {
    brazil_municipality() |> glimpse()
  }
#> ! The closest map year to 2025 is 2022. Using year 2022 instead.
#> Using year/date 2022
#> Rows: 5,570
#> Columns: 9
#> $ region_code       <int> 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1…
#> $ region            <chr> "North", "North", "North", "North", "North", "Nor…
#> $ state_code        <int> 11, 11, 11, 11, 11, 11, 11, 11, 11, 11, 11, 11, 1…
#> $ state             <chr> "Rondônia", "Rondônia", "Rondônia", "Rondônia", "…
#> $ federal_unit      <chr> "RO", "RO", "RO", "RO", "RO", "RO", "RO", "RO", "…
#> $ municipality_code <dbl> 1100015, 1100023, 1100031, 1100049, 1100056, 1100…
#> $ municipality      <chr> "Alta Floresta D'Oeste", "Ariquemes", "Cabixi", "…
#> $ latitude          <dbl> -11.935540305, -9.908462867, -13.499763460, -11.4…
#> $ longitude         <dbl> -61.99982390, -63.03326928, -60.54431358, -61.442…
# }

# \dontrun{
  if (has_internet()) {
    brazil_municipality(municipality = "Belém") |> glimpse()
  }
#> Rows: 3
#> Columns: 9
#> $ region_code       <int> 1, 2, 2
#> $ region            <chr> "North", "Northeast", "Northeast"
#> $ state_code        <int> 15, 25, 27
#> $ state             <chr> "Pará", "Paraíba", "Alagoas"
#> $ federal_unit      <chr> "PA", "PB", "AL"
#> $ municipality_code <dbl> 1501402, 2501906, 2700805
#> $ municipality      <chr> "Belém", "Belém", "Belém"
#> $ latitude          <dbl> -1.459845000, -6.694042610, -9.568648231
#> $ longitude         <dbl> -48.48782569, -35.53627408, -36.49449799
# }

# \dontrun{
  if (has_internet()) {
    brazil_municipality(municipality = "Belém", state = "Pará") |> glimpse()
  }
#> Rows: 1
#> Columns: 9
#> $ region_code       <int> 1
#> $ region            <chr> "North"
#> $ state_code        <int> 15
#> $ state             <chr> "Pará"
#> $ federal_unit      <chr> "PA"
#> $ municipality_code <dbl> 1501402
#> $ municipality      <chr> "Belém"
#> $ latitude          <dbl> -1.459845
#> $ longitude         <dbl> -48.48782569
# }

# \dontrun{
  if (has_internet()) {
    brazil_municipality(municipality = c("Belém", "São Paulo")) |> glimpse()
  }
#> Rows: 4
#> Columns: 9
#> $ region_code       <int> 1, 2, 2, 3
#> $ region            <chr> "North", "Northeast", "Northeast", "Southeast"
#> $ state_code        <int> 15, 25, 27, 35
#> $ state             <chr> "Pará", "Paraíba", "Alagoas", "São Paulo"
#> $ federal_unit      <chr> "PA", "PB", "AL", "SP"
#> $ municipality_code <dbl> 1501402, 2501906, 2700805, 3550308
#> $ municipality      <chr> "Belém", "Belém", "Belém", "São Paulo"
#> $ latitude          <dbl> -1.459845000, -6.694042610, -9.568648231, -23.567…
#> $ longitude         <dbl> -48.48782569, -35.53627408, -36.49449799, -46.570…
# }