Package {geobr}

Type: Package
Title: Download Official Spatial Data Sets of Brazil
Version: 2.0.0
URL: https://ipeagit.github.io/geobr/, https://github.com/ipeaGIT/geobr
BugReports: https://github.com/ipeaGIT/geobr/issues
Description: Easy access to official spatial data sets of Brazil. The package offers a wide range of spatial data sets available at various geographic scales and for various years with harmonized attributes, projection and fixed topology. All functions allow for seamless integration sf, DuckDB and Arrow.
License: MIT + file LICENSE
Encoding: UTF-8
LazyData: TRUE
Depends: R (≥ 4.1.0)
Imports: checkmate, cli, curl (≥ 5.0.0), dplyr (≥ 0.8-3), DBI, duckdb, duckspatial(≥ 1.1.0), fs, glue, httr2, methods, nanoarrow, piggyback, rlang, sf (≥ 0.9-3), sfheaders, stringr, utils
Suggests: arrow (≥ 20.0.0), censobr (≥ 0.3.2), covr, data.table, geoarrow (≥ 0.4.2), ggplot2 (≥ 3.3.1), knitr, rmarkdown, scales, testthat
RoxygenNote: 7.3.3
VignetteBuilder: knitr
NeedsCompilation: no
Packaged: 2026-05-20 10:22:25 UTC; rafap
Author: Rafael H. M. Pereira ORCID iD [aut, cre], Rogério Jerônimo Barbosa [aut], Caio Nogueira Goncalves [ctb], Cecilia do Lago [ctb], Filipe Cavalcanti [ctb], Arthur Bazolli [ctb], Lucas Gelape [ctb], Rafael Lopes [ctb], Vinicius Oike [ctb], Paulo Henrique Fernandes de Araujo [ctb], Guilherme Duarte Carvalho [ctb], Rodrigo Almeida de Arruda [ctb], Igor Nascimento [ctb], Barbara Santiago Pedreira da Costa [ctb], Welligtton Silva Cavedo [ctb], Pedro R. Andrade [ctb], Alan da Silva [ctb], Carlos Kauê Vieira Braga [ctb], Carl Schmertmann [ctb], Alessandro Samuel-Rosa [ctb], Daniel Ferreira [ctb], Marcus Saraiva [ctb], Beatriz Milz ORCID iD [ctb], ITpS - Instituto Todos pela Saúde [fnd], Ipea - Institue for Applied Economic Research [cph, fnd]
Maintainer: Rafael H. M. Pereira <rafa.pereira.br@gmail.com>
Repository: CRAN
Date/Publication: 2026-05-20 12:30:09 UTC

geobr: Download Official Spatial Data Sets of Brazil

Description

Easy access to official spatial data sets of Brazil as 'sf' objects in R. The package includes a wide range of geospatial data available at various geographic scales and for various years with harmonized attributes, projection and fixed topology.

Usage

Please check the vignettes for more on the package usage:

Author(s)

Maintainer: Rafael H. M. Pereira rafa.pereira.br@gmail.com (ORCID)

Authors:

Other contributors:

See Also

Useful links:

Determine the state of a given CEP postal code

Description

Zips codes in Brazil are known as CEP, the abbreviation for postal code address. CEPs in Brazil are 8 digits long, with the format 'xxxxx-xxx'.

Usage

cep_to_state(cep)

Arguments

cep

A character string with 8 digits in the format "xxxxxxxx", or with the format 'xxxxx-xxx'.

Value

A character string with a state abbreviation.

Examples


uf <- cep_to_state(cep = '69900-000')

# Or:
uf <- cep_to_state(cep = '69900000')

Check internet connection with Ipea server

Description

Checks if there is an internet connection with Ipea server.

Usage

check_connection(
  url = "https://github.com/ipea/geobr_prep_data/releases",
  silent = FALSE
)

Arguments

url

A string with the url address of an aop dataset

silent

Logical. Throw a message when silent is FALSE (default)

Value

Logical. TRUE if url is working, FALSE if not.

Support function to download metadata internally used in geobr

Description

Support function to download metadata internally used in geobr

Usage

download_metadata2()

Examples

## Not run:  if (interactive()) {
df <- download_metadata2()
}

## End(Not run)

Download parquet to tempdir

Description

Download parquet to tempdir

Usage

download_parquet(
  filename_to_download,
  showProgress = parent.frame()$showProgress,
  cache = parent.frame()$cache
)

Arguments

filename_to_download

A string with the file name

showProgress

Logical. Defaults to TRUE display progress bar.

cache

Logical. Whether the function should read the data cached locally, which is faster. Defaults to cache = TRUE. By default, geobr stores data files in a temporary directory that exists only within each R session. If cache = FALSE, the function will download the data again and overwrite the local file.

Filter data set to return specific states

Description

Filter data set to return specific states

Usage

filter_arrw(temp_arrw = parent.frame()$temp_arrw, code)

Arguments

temp_arrw

An internal arrow table

code

The two-digit code of a state or a two-letter uppercase abbreviation (e.g. 33 or "RJ"). If code_state="all" (the default), the function downloads all states.

Value

A simple feature sf or data.frame.

Safely opens a Parquet file

Description

This function handles some failure modes, including if the Parquet file is corrupted.

Usage

geobr_open_dataset(filename)

Arguments

filename

A local Parquet file

Value

An duckspatial_df

A correspondence table indicating what quadrants of IBGE's statistical grid intersect with each Brazilian state

Description

Built-in dataset

Usage

data(grid_state_correspondence_table)

Format

A data frame sf with 139 rows and 3 columns

Details

correspondence table indicating what quadrants of IBGE's statistical grid intersect with each Brazilian state

Note

Last updated 2021-o3-21

List all data sets available in the geobr package

Description

Returns a data frame with all data sets available in the geobr package

Usage

list_geobr(wide = TRUE)

Arguments

wide

Whether the the output data frame should come in wide (TRUE) or long format (FALSE).

Value

A data.frame

Examples


df <- list_geobr()

Look up municipality codes and names

Description

Input a municipality name or code and get the names and codes of the municipality.

Usage

lookup_muni(year, name_muni = NULL, code_muni = NULL)

Arguments

year

Numeric. Year of the data in YYYY format. It defaults to NULL and reads the data from the latest year available.

name_muni

The municipality name to be looked up.

code_muni

The municipality code to be looked up.

Details

Only available from 2010 Census data so far

Value

A data.frame with 13 columns identifying the geographies information of that municipality.

A data.frame

Examples


# Look for municipality Rio de Janeiro
mun <- lookup_muni(
  name_muni = "Rio de Janeiro",
  year = 2022
  )

# Look for a given municipality code
mun <- lookup_muni(
  code_muni = 3304557,
  year = 2022
  )

# Get the lookup table for all municipalities
mun_all <- lookup_muni(
  name_muni = "all",
  year = 2022
  )

# Or:
mun_all <- lookup_muni(
  code_muni = "all",
  year = 2022
  )

Check if vector only has numeric characters

Description

Checks if vector only has numeric characters

Usage

numbers_only(x)

Arguments

x

A vector.

Value

Logical. TRUE if vector only has numeric characters.

Download spatial data of Brazil's Legal Amazon

Description

This data set covers the whole of Brazil's Legal Amazon as defined in the federal law n. 12.651/2012). The original data comes from the Brazilian Ministry of Environment (MMA) and can be found at "http://mapas.mma.gov.br/i3geo/datadownload.htm".

Usage

read_amazon(
  year,
  simplified = TRUE,
  output = "sf",
  showProgress = TRUE,
  cache = TRUE,
  verbose = TRUE
)

Arguments

year

Numeric. Year of the data in YYYY format. It defaults to NULL and reads the data from the latest year available.

simplified

Logic FALSE or TRUE, indicating whether the function should return the data set with 'original' spatial resolution or a data set with 'simplified' geometry. Defaults to TRUE. For spatial analysis and statistics users should set simplified = FALSE. Borders have been simplified by removing vertices of borders using ⁠st_simplify{sf}⁠ preserving topology with a dTolerance of 100.

output

String. Type of object returned by the function. Defaults to "sf", which loads the data into memory as an sf object. Alternatively, "duckdb" returns a lazy spatial table backed by DuckDB via the duckspatial package, and "arrow" returns an Arrow dataset. Both "duckdb" and "arrow" support out-of-memory processing of large data sets.

showProgress

Logical. Defaults to TRUE display progress bar.

cache

Logical. Whether the function should read the data cached locally, which is faster. Defaults to cache = TRUE. By default, geobr stores data files in a temporary directory that exists only within each R session. If cache = FALSE, the function will download the data again and overwrite the local file.

verbose

A logical. If TRUE (the default), the function prints informative messages and shows download progress bar. If FALSE, the function is silent.

Value

An ⁠"sf" "data.frame"⁠ OR an ArrowObject

Examples


# Read Brazilian Legal Amazon
a <- read_amazon(year = 2024)

Download spatial data of Brazilian biomes

Description

This data set includes polygons of all biomes present in the Brazilian territory and coastal area. Data comes from IBGE. More information at https://www.ibge.gov.br/geociencias/cartas-e-mapas/informacoes-ambientais/15842-biomas.html

Usage

read_biomes(
  year,
  simplified = TRUE,
  output = "sf",
  showProgress = TRUE,
  cache = TRUE,
  verbose = TRUE
)

Arguments

year

Numeric. Year of the data in YYYY format. It defaults to NULL and reads the data from the latest year available.

simplified

Logic FALSE or TRUE, indicating whether the function should return the data set with 'original' spatial resolution or a data set with 'simplified' geometry. Defaults to TRUE. For spatial analysis and statistics users should set simplified = FALSE. Borders have been simplified by removing vertices of borders using ⁠st_simplify{sf}⁠ preserving topology with a dTolerance of 100.

output

String. Type of object returned by the function. Defaults to "sf", which loads the data into memory as an sf object. Alternatively, "duckdb" returns a lazy spatial table backed by DuckDB via the duckspatial package, and "arrow" returns an Arrow dataset. Both "duckdb" and "arrow" support out-of-memory processing of large data sets.

showProgress

Logical. Defaults to TRUE display progress bar.

cache

Logical. Whether the function should read the data cached locally, which is faster. Defaults to cache = TRUE. By default, geobr stores data files in a temporary directory that exists only within each R session. If cache = FALSE, the function will download the data again and overwrite the local file.

verbose

A logical. If TRUE (the default), the function prints informative messages and shows download progress bar. If FALSE, the function is silent.

Value

An ⁠"sf" "data.frame"⁠ OR an ArrowObject

Examples


# Read biomes
b <- read_biomes(year = 2025)

Download data of state capitals

Description

This function downloads either a spatial sf object with the location of the municipal seats (sede dos municipios) of state capitals, or a data.frame with the names and codes of state capitals. Data downloaded for the latest available year.

Usage

read_capitals(output = "sf", showProgress = TRUE, cache = TRUE, verbose = TRUE)

Arguments

output

String. Type of object returned by the function. Defaults to "sf", which loads the data into memory as an sf object. Alternatively, "duckdb" returns a lazy spatial table backed by DuckDB via the duckspatial package, and "arrow" returns an Arrow dataset. Both "duckdb" and "arrow" support out-of-memory processing of large data sets.

showProgress

Logical. Defaults to TRUE display progress bar.

cache

Logical. Whether the function should read the data cached locally, which is faster. Defaults to cache = TRUE. By default, geobr stores data files in a temporary directory that exists only within each R session. If cache = FALSE, the function will download the data again and overwrite the local file.

verbose

A logical. If TRUE (the default), the function prints informative messages and shows download progress bar. If FALSE, the function is silent.

Value

An ⁠"sf" "data.frame"⁠ OR an ArrowObject

Examples


# Read spatial data with the  municipal seats of state capitals
capitals_sf <- read_capitals(output = "sf")

Download spatial data of census tracts

Description

Data of census tracts (setores censitários) of the Brazilian Population Census

Usage

read_census_tract(
  year,
  code_tract,
  zone = "urban",
  simplified = TRUE,
  output = "sf",
  showProgress = TRUE,
  cache = TRUE,
  verbose = TRUE
)

Arguments

year

Numeric. Year of the data in YYYY format. It defaults to NULL and reads the data from the latest year available.

code_tract

The 7-digit code of a Municipality. If the two-digit code or a two-letter uppercase abbreviation of a state is passed, (e.g. 33 or "RJ") the function will load all census tracts of that state. If code_tract="all", the function downloads all census tracts of the country.

zone

For census tracts before 2010, 'urban' and 'rural' census tracts are separate data sets.

simplified

Logic FALSE or TRUE, indicating whether the function should return the data set with 'original' spatial resolution or a data set with 'simplified' geometry. Defaults to TRUE. For spatial analysis and statistics users should set simplified = FALSE. Borders have been simplified by removing vertices of borders using ⁠st_simplify{sf}⁠ preserving topology with a dTolerance of 100.

output

String. Type of object returned by the function. Defaults to "sf", which loads the data into memory as an sf object. Alternatively, "duckdb" returns a lazy spatial table backed by DuckDB via the duckspatial package, and "arrow" returns an Arrow dataset. Both "duckdb" and "arrow" support out-of-memory processing of large data sets.

showProgress

Logical. Defaults to TRUE display progress bar.

cache

Logical. Whether the function should read the data cached locally, which is faster. Defaults to cache = TRUE. By default, geobr stores data files in a temporary directory that exists only within each R session. If cache = FALSE, the function will download the data again and overwrite the local file.

verbose

A logical. If TRUE (the default), the function prints informative messages and shows download progress bar. If FALSE, the function is silent.

Value

An ⁠"sf" "data.frame"⁠ OR an ArrowObject

Examples



# Read all census tracts of a state at a given year
c <- read_census_tract(year = 2022, code_tract = "DF")

# Read all census tracts of a municipality at a given year
c <- read_census_tract(year = 2022, code_tract = 5201108)

# Read all census tracts of the country at a given year
c <- read_census_tract(year = 2022, code_tract = "all")

# Read rural census tracts for years before 2007
c <- read_census_tract(
  year = 2000,
  code_tract = 5201108,
  zone = "rural"
  )

Download spatial data of historically comparable municipalities

Description

This function downloads the shape file of minimum comparable area of municipalities, known in Portuguese as 'Areas minimas comparaveis (AMCs)'. The data is available for any combination of census years between 1872-2010. These data sets are generated based on the Stata code originally developed by Ehrl (2017) doi:10.1590/0101-416147182phe, and translated into R by the geobr team.

Usage

read_comparable_areas(
  start_year = 1970,
  end_year = 2010,
  simplified = TRUE,
  showProgress = TRUE,
  cache = TRUE,
  verbose = TRUE
)

Arguments

start_year

Numeric. Start year to the period in the YYYY format. Defaults TO 1970.

end_year

Numeric. End year to the period in the YYYY format. Defaults to 2010.

simplified

Logic FALSE or TRUE, indicating whether the function should return the data set with 'original' spatial resolution or a data set with 'simplified' geometry. Defaults to TRUE. For spatial analysis and statistics users should set simplified = FALSE. Borders have been simplified by removing vertices of borders using ⁠st_simplify{sf}⁠ preserving topology with a dTolerance of 100.

showProgress

Logical. Defaults to TRUE display progress bar.

cache

Logical. Whether the function should read the data cached locally, which is faster. Defaults to cache = TRUE. By default, geobr stores data files in a temporary directory that exists only within each R session. If cache = FALSE, the function will download the data again and overwrite the local file.

verbose

A logical. If TRUE (the default), the function prints informative messages and shows download progress bar. If FALSE, the function is silent.

Details

These data sets are generated based on the original Stata code developed by Philipp Ehrl. If you use these data, please cite:

Value

An ⁠"sf" "data.frame"⁠ OR an ArrowObject

Examples


  amc <- read_comparable_areas(start_year=1970, end_year=2010)

Download spatial data of Brazilian environmental conservation units

Description

This data set covers the whole of Brazil and it includes the polygons of all conservation units present in Brazilian territory. The original data and data dictionary can be found comes from MMA and can be found at "https://dados.mma.gov.br/dataset/unidadesdeconservacao".

Usage

read_conservation_units(
  date,
  simplified = TRUE,
  output = "sf",
  showProgress = TRUE,
  cache = TRUE,
  verbose = TRUE
)

Arguments

date

Numeric. Date of the data in YYYYMM format. It defaults to NULL and reads the data from the latest date available.

simplified

Logic FALSE or TRUE, indicating whether the function should return the data set with 'original' spatial resolution or a data set with 'simplified' geometry. Defaults to TRUE. For spatial analysis and statistics users should set simplified = FALSE. Borders have been simplified by removing vertices of borders using ⁠st_simplify{sf}⁠ preserving topology with a dTolerance of 100.

output

String. Type of object returned by the function. Defaults to "sf", which loads the data into memory as an sf object. Alternatively, "duckdb" returns a lazy spatial table backed by DuckDB via the duckspatial package, and "arrow" returns an Arrow dataset. Both "duckdb" and "arrow" support out-of-memory processing of large data sets.

showProgress

Logical. Defaults to TRUE display progress bar.

cache

Logical. Whether the function should read the data cached locally, which is faster. Defaults to cache = TRUE. By default, geobr stores data files in a temporary directory that exists only within each R session. If cache = FALSE, the function will download the data again and overwrite the local file.

verbose

A logical. If TRUE (the default), the function prints informative messages and shows download progress bar. If FALSE, the function is silent.

Value

An ⁠"sf" "data.frame"⁠ OR an ArrowObject

Examples


# Read conservation_units
uc <- read_conservation_units(date = 202503)

Download spatial data of Brazil's national borders

Description

National borders

Usage

read_country(
  year,
  simplified = TRUE,
  output = "sf",
  showProgress = TRUE,
  cache = TRUE,
  verbose = TRUE
)

Arguments

year

Numeric. Year of the data in YYYY format. It defaults to NULL and reads the data from the latest year available.

simplified

Logic FALSE or TRUE, indicating whether the function should return the data set with 'original' spatial resolution or a data set with 'simplified' geometry. Defaults to TRUE. For spatial analysis and statistics users should set simplified = FALSE. Borders have been simplified by removing vertices of borders using ⁠st_simplify{sf}⁠ preserving topology with a dTolerance of 100.

output

String. Type of object returned by the function. Defaults to "sf", which loads the data into memory as an sf object. Alternatively, "duckdb" returns a lazy spatial table backed by DuckDB via the duckspatial package, and "arrow" returns an Arrow dataset. Both "duckdb" and "arrow" support out-of-memory processing of large data sets.

showProgress

Logical. Defaults to TRUE display progress bar.

cache

Logical. Whether the function should read the data cached locally, which is faster. Defaults to cache = TRUE. By default, geobr stores data files in a temporary directory that exists only within each R session. If cache = FALSE, the function will download the data again and overwrite the local file.

verbose

A logical. If TRUE (the default), the function prints informative messages and shows download progress bar. If FALSE, the function is silent.

Value

An ⁠"sf" "data.frame"⁠ OR an ArrowObject

Examples


# Read specific year
br_1872 <- read_country(year = 1872)

br_2025 <- read_country(year = 2025)

Download spatial data of disaster risk areas

Description

This function reads the the official data of disaster risk areas in Brazil (currently only available for 2010). It specifically focuses on geodynamic and hydro-meteorological disasters capable of triggering landslides and floods. The data set covers the whole country. Each risk area polygon (known as 'BATER') has unique code id (column 'geo_bater'). The data set brings information on the extent to which the risk area polygons overlap with census tracts and block faces (column "acuracia") and number of ris areas within each risk area (column 'num'). Original data were generated by IBGE and CEMADEN. For more information about the methodology, see deails at https://www.ibge.gov.br/geociencias/organizacao-do-territorio/tipologias-do-territorio/21538-populacao-em-areas-de-risco-no-brasil.html

Usage

read_disaster_risk_area(
  year,
  code_muni = "all",
  simplified = TRUE,
  output = "sf",
  showProgress = TRUE,
  cache = TRUE,
  verbose = TRUE
)

Arguments

year

Numeric. Year of the data in YYYY format. It defaults to NULL and reads the data from the latest year available.

code_muni

The 7-digit code of a municipality. If code_muni = "all" (Default), the function downloads all the data available in the country. Alternatively, if a two-digit state code or a two-letter uppercase abbreviation of a state is passed (e.g. 33 or "RJ"), all data of that state are downloaded. Municipality codes can be consulted with the geobr::lookup_muni() function.

simplified

Logic FALSE or TRUE, indicating whether the function should return the data set with 'original' spatial resolution or a data set with 'simplified' geometry. Defaults to TRUE. For spatial analysis and statistics users should set simplified = FALSE. Borders have been simplified by removing vertices of borders using ⁠st_simplify{sf}⁠ preserving topology with a dTolerance of 100.

output

String. Type of object returned by the function. Defaults to "sf", which loads the data into memory as an sf object. Alternatively, "duckdb" returns a lazy spatial table backed by DuckDB via the duckspatial package, and "arrow" returns an Arrow dataset. Both "duckdb" and "arrow" support out-of-memory processing of large data sets.

showProgress

Logical. Defaults to TRUE display progress bar.

cache

Logical. Whether the function should read the data cached locally, which is faster. Defaults to cache = TRUE. By default, geobr stores data files in a temporary directory that exists only within each R session. If cache = FALSE, the function will download the data again and overwrite the local file.

verbose

A logical. If TRUE (the default), the function prints informative messages and shows download progress bar. If FALSE, the function is silent.

Value

An ⁠"sf" "data.frame"⁠ OR an ArrowObject

Examples


# Read all disaster risk areas in an specific year
d <- read_disaster_risk_area(year = 2010)

# Read disaster risk areas in a given municipality
d <- read_disaster_risk_area(year = 2010, code_muni = 2927408)

# Read disaster risk areas in a given state
d <- read_disaster_risk_area(year = 2010, code_muni = "AC")

Download spatial data of favelas and urban communities

Description

This function reads the official data on favelas and urban communities (favelas e comunidades urbanas) of Brazil. Original data from the Institute of Geography and Statistics (IBGE) For more information about the methodology, see details at https://biblioteca.ibge.gov.br/visualizacao/livros/liv102134.pdf

Usage

read_favela(
  year,
  code_muni = "all",
  simplified = TRUE,
  output = "sf",
  showProgress = TRUE,
  cache = TRUE,
  verbose = TRUE
)

Arguments

year

Numeric. Year of the data in YYYY format. It defaults to NULL and reads the data from the latest year available.

code_muni

The 7-digit code of a municipality. If code_muni = "all" (Default), the function downloads all the data available in the country. Alternatively, if a two-digit state code or a two-letter uppercase abbreviation of a state is passed (e.g. 33 or "RJ"), all data of that state are downloaded. Municipality codes can be consulted with the geobr::lookup_muni() function.

simplified

Logic FALSE or TRUE, indicating whether the function should return the data set with 'original' spatial resolution or a data set with 'simplified' geometry. Defaults to TRUE. For spatial analysis and statistics users should set simplified = FALSE. Borders have been simplified by removing vertices of borders using ⁠st_simplify{sf}⁠ preserving topology with a dTolerance of 100.

output

String. Type of object returned by the function. Defaults to "sf", which loads the data into memory as an sf object. Alternatively, "duckdb" returns a lazy spatial table backed by DuckDB via the duckspatial package, and "arrow" returns an Arrow dataset. Both "duckdb" and "arrow" support out-of-memory processing of large data sets.

showProgress

Logical. Defaults to TRUE display progress bar.

cache

Logical. Whether the function should read the data cached locally, which is faster. Defaults to cache = TRUE. By default, geobr stores data files in a temporary directory that exists only within each R session. If cache = FALSE, the function will download the data again and overwrite the local file.

verbose

A logical. If TRUE (the default), the function prints informative messages and shows download progress bar. If FALSE, the function is silent.

Value

An ⁠"sf" "data.frame"⁠ OR an ArrowObject

Examples


# Read all favelas of Brazil
n <- read_favela(year = 2022)

# Read all favelas of a given municipality
n <- read_favela(year = 2022, code_muni = 2927408)

# Read all favelas of a given state
n <- read_favela(year = 2022, code_muni = "RJ")

Download geolocated data of health facilities

Description

Data comes from the National Registry of Health Facilities (Cadastro Nacional de Estabelecimentos de Saude - CNES), originally collected by the Brazilian Ministry of Health. The spatial coordinates used in geobr are a combination of the coordinates produced by the original data producer and the coordinates found via geocoding with the geocodebr package https://CRAN.R-project.org/package=geocodebr. Whenever the distance between the coordinates from both sources is smaller than 800 meters, geobr uses coordinates from the data producer. When the distance between the two sources is greater than 800 meters and the results from geocodebr have a precision level finer than 800 meters, geobr uses the coordinates from geocodebr. When the coordinates from the original source are missing, geobr also uses geocodebr coordinates, regardless of precision level. The source of the spatial coordinates used in each observation is registered in the data in a specific column coords_source. Additional columns indicating the precision level of geocodebr geocoding are also included in the data.

Usage

read_health_facilities(
  date,
  code_muni = "all",
  output = "sf",
  showProgress = TRUE,
  cache = TRUE,
  verbose = TRUE
)

Arguments

date

Numeric. Date of the data in YYYYMM format. It defaults to NULL and reads the data from the latest date available.

code_muni

The 7-digit code of a municipality. If code_muni = "all" (Default), the function downloads all the data available in the country. Alternatively, if a two-digit state code or a two-letter uppercase abbreviation of a state is passed (e.g. 33 or "RJ"), all data of that state are downloaded. Municipality codes can be consulted with the geobr::lookup_muni() function.

output

String. Type of object returned by the function. Defaults to "sf", which loads the data into memory as an sf object. Alternatively, "duckdb" returns a lazy spatial table backed by DuckDB via the duckspatial package, and "arrow" returns an Arrow dataset. Both "duckdb" and "arrow" support out-of-memory processing of large data sets.

showProgress

Logical. Defaults to TRUE display progress bar.

cache

Logical. Whether the function should read the data cached locally, which is faster. Defaults to cache = TRUE. By default, geobr stores data files in a temporary directory that exists only within each R session. If cache = FALSE, the function will download the data again and overwrite the local file.

verbose

A logical. If TRUE (the default), the function prints informative messages and shows download progress bar. If FALSE, the function is silent.

Value

An ⁠"sf" "data.frame"⁠ OR an ArrowObject

Examples


# Read health facilities of a given state
h <- read_health_facilities(
  date = 202601,
  code_muni = "PA"
  )

# Read all health facilities of the whole country
h <- read_health_facilities(date = 202601)

Download spatial data of Brazilian health regions and health macro regions

Description

Health regions are used to guide the the regional and state planning of health services. Macro health regions, in particular, are used to guide the planning of high complexity #' health services. These services involve larger economics of scale and are concentrated in few municipalities because they are generally more technology intensive, costly and face shortages of specialized professionals. A macro region comprises one or more health regions.

Usage

read_health_region(
  year,
  code_state = "all",
  geometry_level = "municipality",
  macro = NULL,
  simplified = TRUE,
  output = "sf",
  showProgress = TRUE,
  cache = TRUE,
  verbose = TRUE
)

Arguments

year

Numeric. Year of the data in YYYY format. It defaults to NULL and reads the data from the latest year available.

code_state

The two-digit code of a state or a two-letter uppercase abbreviation (e.g. 33 or "RJ"). If code_state="all" (the default), the function downloads all states.

geometry_level

String. Spatial level of the output geometries. Use "municipality" to return municipal geometries (default), "micro" to aggregate geometries by health region, or "macro" to aggregate geometries by health macroregion.

macro

The argument macro has been deprecated.

simplified

Logic FALSE or TRUE, indicating whether the function should return the data set with 'original' spatial resolution or a data set with 'simplified' geometry. Defaults to TRUE. For spatial analysis and statistics users should set simplified = FALSE. Borders have been simplified by removing vertices of borders using ⁠st_simplify{sf}⁠ preserving topology with a dTolerance of 100.

output

String. Type of object returned by the function. Defaults to "sf", which loads the data into memory as an sf object. Alternatively, "duckdb" returns a lazy spatial table backed by DuckDB via the duckspatial package, and "arrow" returns an Arrow dataset. Both "duckdb" and "arrow" support out-of-memory processing of large data sets.

showProgress

Logical. Defaults to TRUE display progress bar.

cache

Logical. Whether the function should read the data cached locally, which is faster. Defaults to cache = TRUE. By default, geobr stores data files in a temporary directory that exists only within each R session. If cache = FALSE, the function will download the data again and overwrite the local file.

verbose

A logical. If TRUE (the default), the function prints informative messages and shows download progress bar. If FALSE, the function is silent.

Value

An ⁠"sf" "data.frame"⁠ OR an ArrowObject

Examples


# Read municipalities with info on health regions
health_muni <- read_health_region(year = 2024)

# Read the geometries of micro regions
health_micro <- read_health_region(
  year = 2024,
  geometry_level = "micro"
  )

# Read the geometries of macro regions
health_macro <- read_health_region(
  year = 2024,
  geometry_level = "macro"
)

Download spatial data of Brazil's Immediate Geographic Areas

Description

The Immediate Geographic Areas are part of the geographic division of Brazil created after 2017 by IBGE. These regions were created to replace the "Micro Regions" division. Data at scale 1:250,000.

Usage

read_immediate_region(
  year,
  code_immediate = "all",
  simplified = TRUE,
  output = "sf",
  showProgress = TRUE,
  cache = TRUE,
  verbose = TRUE
)

Arguments

year

Numeric. Year of the data in YYYY format. It defaults to NULL and reads the data from the latest year available.

code_immediate

6-digit code of an immediate region. If the two-digit code or a two-letter uppercase abbreviation of a state is passed, (e.g. 33 or "RJ") the function will load all immediate regions of that state. If code_immediate="all" (Default), the function downloads all immediate regions of the country.

simplified

Logic FALSE or TRUE, indicating whether the function should return the data set with 'original' spatial resolution or a data set with 'simplified' geometry. Defaults to TRUE. For spatial analysis and statistics users should set simplified = FALSE. Borders have been simplified by removing vertices of borders using ⁠st_simplify{sf}⁠ preserving topology with a dTolerance of 100.

output

String. Type of object returned by the function. Defaults to "sf", which loads the data into memory as an sf object. Alternatively, "duckdb" returns a lazy spatial table backed by DuckDB via the duckspatial package, and "arrow" returns an Arrow dataset. Both "duckdb" and "arrow" support out-of-memory processing of large data sets.

showProgress

Logical. Defaults to TRUE display progress bar.

cache

Logical. Whether the function should read the data cached locally, which is faster. Defaults to cache = TRUE. By default, geobr stores data files in a temporary directory that exists only within each R session. If cache = FALSE, the function will download the data again and overwrite the local file.

verbose

A logical. If TRUE (the default), the function prints informative messages and shows download progress bar. If FALSE, the function is silent.

Value

An ⁠"sf" "data.frame"⁠ OR an ArrowObject

Examples


# Read an specific immediate region
im <- read_immediate_region(code_immediate=110006, year = 2024)

# Read immediate regions of a state
im <- read_immediate_region(code_immediate="AM", year = 2024)
im <- read_immediate_region(code_immediate=12, year = 2024)

# Read all immediate regions of the country
im <- read_immediate_region(code_immediate="all", year = 2024)

Download spatial data of indigenous lands in Brazil

Description

The data set covers the whole of Brazil and it includes indigenous lands from all ethnic groups and at different stages of demarcation. The original data comes from the National Indian Foundation (FUNAI) and can be found at https://www.gov.br/funai/pt-br/atuacao/terras-indigenas/geoprocessamento-e-mapas. Although original data is updated monthly, the geobr package will only keep the data for a few months per year.

Usage

read_indigenous_land(
  year,
  code_state = "all",
  simplified = TRUE,
  output = "sf",
  showProgress = TRUE,
  cache = TRUE,
  verbose = TRUE
)

Arguments

year

Numeric. Year of the data in YYYY format. It defaults to NULL and reads the data from the latest year available.

code_state

The two-digit code of a state or a two-letter uppercase abbreviation (e.g. 33 or "RJ"). If code_state="all" (the default), the function downloads all states.

simplified

Logic FALSE or TRUE, indicating whether the function should return the data set with 'original' spatial resolution or a data set with 'simplified' geometry. Defaults to TRUE. For spatial analysis and statistics users should set simplified = FALSE. Borders have been simplified by removing vertices of borders using ⁠st_simplify{sf}⁠ preserving topology with a dTolerance of 100.

output

String. Type of object returned by the function. Defaults to "sf", which loads the data into memory as an sf object. Alternatively, "duckdb" returns a lazy spatial table backed by DuckDB via the duckspatial package, and "arrow" returns an Arrow dataset. Both "duckdb" and "arrow" support out-of-memory processing of large data sets.

showProgress

Logical. Defaults to TRUE display progress bar.

cache

Logical. Whether the function should read the data cached locally, which is faster. Defaults to cache = TRUE. By default, geobr stores data files in a temporary directory that exists only within each R session. If cache = FALSE, the function will download the data again and overwrite the local file.

verbose

A logical. If TRUE (the default), the function prints informative messages and shows download progress bar. If FALSE, the function is silent.

Value

An ⁠"sf" "data.frame"⁠ OR an ArrowObject

Examples


# Read all indigenous land in an specific year
i <- read_indigenous_land(year = 2025)

Download spatial data of Brazil's Intermediate Geographic Areas

Description

The intermediate Geographic Areas are part of the geographic division of Brazil created after 2017 by IBGE. These regions were created to replace the "Meso Regions" division. Data at scale 1:250,000.

Usage

read_intermediate_region(
  year,
  code_intermediate = "all",
  simplified = TRUE,
  output = "sf",
  showProgress = TRUE,
  cache = TRUE,
  verbose = TRUE
)

Arguments

year

Numeric. Year of the data in YYYY format. It defaults to NULL and reads the data from the latest year available.

code_intermediate

4-digit code of an intermediate region. If the two-digit code or a two-letter uppercase abbreviation of a state is passed, (e.g. 33 or "RJ") the function will load all intermediate regions of that state. If code_intermediate="all" (Default), the function downloads all intermediate regions of the country.

simplified

Logic FALSE or TRUE, indicating whether the function should return the data set with 'original' spatial resolution or a data set with 'simplified' geometry. Defaults to TRUE. For spatial analysis and statistics users should set simplified = FALSE. Borders have been simplified by removing vertices of borders using ⁠st_simplify{sf}⁠ preserving topology with a dTolerance of 100.

output

String. Type of object returned by the function. Defaults to "sf", which loads the data into memory as an sf object. Alternatively, "duckdb" returns a lazy spatial table backed by DuckDB via the duckspatial package, and "arrow" returns an Arrow dataset. Both "duckdb" and "arrow" support out-of-memory processing of large data sets.

showProgress

Logical. Defaults to TRUE display progress bar.

cache

Logical. Whether the function should read the data cached locally, which is faster. Defaults to cache = TRUE. By default, geobr stores data files in a temporary directory that exists only within each R session. If cache = FALSE, the function will download the data again and overwrite the local file.

verbose

A logical. If TRUE (the default), the function prints informative messages and shows download progress bar. If FALSE, the function is silent.

Value

An ⁠"sf" "data.frame"⁠ OR an ArrowObject

Examples



# Read an specific intermediate region
inter <- read_intermediate_region(code_intermediate = 1202, year = 2024)

# Read intermediate regions of a state
inter <- read_intermediate_region(code_intermediate = "AM", year = 2024)
inter <- read_intermediate_region(code_intermediate = 12, year = 2024)

# Read all intermediate regions of the country
inter <- read_intermediate_region(code_intermediate = "all", year = 2024)

Download spatial data of meso regions

Description

Data at scale 1:250,000, using Geodetic reference system "SIRGAS2000" and CRS(4674)

Usage

read_meso_region(
  year,
  code_meso = "all",
  simplified = TRUE,
  output = "sf",
  showProgress = TRUE,
  cache = TRUE,
  verbose = TRUE
)

Arguments

year

Numeric. Year of the data in YYYY format. It defaults to NULL and reads the data from the latest year available.

code_meso

The 4-digit code of a meso region. If the two-digit code or a two-letter uppercase abbreviation of a state is passed, (e.g. 33 or "RJ") the function will load all meso regions of that state. If code_meso="all" (Default), the function downloads all meso regions of the country.

simplified

Logic FALSE or TRUE, indicating whether the function should return the data set with 'original' spatial resolution or a data set with 'simplified' geometry. Defaults to TRUE. For spatial analysis and statistics users should set simplified = FALSE. Borders have been simplified by removing vertices of borders using ⁠st_simplify{sf}⁠ preserving topology with a dTolerance of 100.

output

String. Type of object returned by the function. Defaults to "sf", which loads the data into memory as an sf object. Alternatively, "duckdb" returns a lazy spatial table backed by DuckDB via the duckspatial package, and "arrow" returns an Arrow dataset. Both "duckdb" and "arrow" support out-of-memory processing of large data sets.

showProgress

Logical. Defaults to TRUE display progress bar.

cache

Logical. Whether the function should read the data cached locally, which is faster. Defaults to cache = TRUE. By default, geobr stores data files in a temporary directory that exists only within each R session. If cache = FALSE, the function will download the data again and overwrite the local file.

verbose

A logical. If TRUE (the default), the function prints informative messages and shows download progress bar. If FALSE, the function is silent.

Value

An ⁠"sf" "data.frame"⁠ OR an ArrowObject

Examples


# Read specific meso region at a given year
meso <- read_meso_region(code_meso=3301, year = 2018)

# Read all meso regions of a state at a given year
meso <- read_meso_region(code_meso="AM", year = 2018)
meso <- read_meso_region(code_meso=12, year = 2018)

# Read all meso regions of the country at a given year
meso <- read_meso_region(code_meso="all", year = 2018)

Download spatial data of official metropolitan areas in Brazil

Description

The function returns the shapes of municipalities grouped by their respective metro areas. Metropolitan areas are created by each state in Brazil. The data set includes the municipalities that belong to all metropolitan areas in the country according to state legislation in each year. Original data were generated by the Brazilian Institute of Geography and Statistics (IBGE). Data at scale 1:250,000, using Geodetic reference system "SIRGAS2000" and CRS(4674).

Usage

read_metro_area(
  year,
  code_state = "all",
  simplified = TRUE,
  output = "sf",
  showProgress = TRUE,
  cache = TRUE,
  verbose = TRUE
)

Arguments

year

Numeric. Year of the data in YYYY format. It defaults to NULL and reads the data from the latest year available.

code_state

The two-digit code of a state or a two-letter uppercase abbreviation (e.g. 33 or "RJ"). If code_state="all" (the default), the function downloads all states.

simplified

Logic FALSE or TRUE, indicating whether the function should return the data set with 'original' spatial resolution or a data set with 'simplified' geometry. Defaults to TRUE. For spatial analysis and statistics users should set simplified = FALSE. Borders have been simplified by removing vertices of borders using ⁠st_simplify{sf}⁠ preserving topology with a dTolerance of 100.

output

String. Type of object returned by the function. Defaults to "sf", which loads the data into memory as an sf object. Alternatively, "duckdb" returns a lazy spatial table backed by DuckDB via the duckspatial package, and "arrow" returns an Arrow dataset. Both "duckdb" and "arrow" support out-of-memory processing of large data sets.

showProgress

Logical. Defaults to TRUE display progress bar.

cache

Logical. Whether the function should read the data cached locally, which is faster. Defaults to cache = TRUE. By default, geobr stores data files in a temporary directory that exists only within each R session. If cache = FALSE, the function will download the data again and overwrite the local file.

verbose

A logical. If TRUE (the default), the function prints informative messages and shows download progress bar. If FALSE, the function is silent.

Value

An ⁠"sf" "data.frame"⁠ OR an ArrowObject

Examples


# Read all official metropolitan areas for a given year
m <- read_metro_area(year = 1970)

m <- read_metro_area(
  year = 2024,
  code_state = "RJ"
  )

Download spatial data of micro regions

Description

Data at scale 1:250,000, using Geodetic reference system "SIRGAS2000" and CRS(4674)

Usage

read_micro_region(
  year,
  code_micro = "all",
  simplified = TRUE,
  output = "sf",
  showProgress = TRUE,
  cache = TRUE,
  verbose = TRUE
)

Arguments

year

Numeric. Year of the data in YYYY format. It defaults to NULL and reads the data from the latest year available.

code_micro

5-digit code of a micro region. If the two-digit code or a two-letter uppercase abbreviation of a state is passed, (e.g. 33 or "RJ") the function will load all micro regions of that state. If code_micro="all" (Default), the function downloads all micro regions of the country.

simplified

Logic FALSE or TRUE, indicating whether the function should return the data set with 'original' spatial resolution or a data set with 'simplified' geometry. Defaults to TRUE. For spatial analysis and statistics users should set simplified = FALSE. Borders have been simplified by removing vertices of borders using ⁠st_simplify{sf}⁠ preserving topology with a dTolerance of 100.

output

String. Type of object returned by the function. Defaults to "sf", which loads the data into memory as an sf object. Alternatively, "duckdb" returns a lazy spatial table backed by DuckDB via the duckspatial package, and "arrow" returns an Arrow dataset. Both "duckdb" and "arrow" support out-of-memory processing of large data sets.

showProgress

Logical. Defaults to TRUE display progress bar.

cache

Logical. Whether the function should read the data cached locally, which is faster. Defaults to cache = TRUE. By default, geobr stores data files in a temporary directory that exists only within each R session. If cache = FALSE, the function will download the data again and overwrite the local file.

verbose

A logical. If TRUE (the default), the function prints informative messages and shows download progress bar. If FALSE, the function is silent.

Value

An ⁠"sf" "data.frame"⁠ OR an ArrowObject

Examples


# Read an specific micro region a given year
micro <- read_micro_region(code_micro=11008, year=2018)

# Read micro regions of a state at a given year
micro <- read_micro_region(code_micro="AM", year=2018)
micro <- read_micro_region(code_micro=12, year=2018)

# Read all micro regions at a given year
 micro <- read_micro_region(code_micro="all", year=2018)

Download spatial data of municipal seats (sede dos municipios) of Brazil

Description

This function reads the official data on the municipal seats (sede dos municipios) of Brazil. The data brings the geographical coordinates (lat lon) of municipal seats for various years since 1872. Original data by the Brazilian Institute of Geography and Statistics (IBGE).

Usage

read_municipal_seat(
  year,
  code_muni = "all",
  output = "sf",
  showProgress = TRUE,
  cache = TRUE,
  verbose = TRUE
)

Arguments

year

Numeric. Year of the data in YYYY format. It defaults to NULL and reads the data from the latest year available.

code_muni

The 7-digit code of a municipality. If code_muni = "all" (Default), the function downloads all the data available in the country. Alternatively, if a two-digit state code or a two-letter uppercase abbreviation of a state is passed (e.g. 33 or "RJ"), all data of that state are downloaded. Municipality codes can be consulted with the geobr::lookup_muni() function.

output

String. Type of object returned by the function. Defaults to "sf", which loads the data into memory as an sf object. Alternatively, "duckdb" returns a lazy spatial table backed by DuckDB via the duckspatial package, and "arrow" returns an Arrow dataset. Both "duckdb" and "arrow" support out-of-memory processing of large data sets.

showProgress

Logical. Defaults to TRUE display progress bar.

cache

Logical. Whether the function should read the data cached locally, which is faster. Defaults to cache = TRUE. By default, geobr stores data files in a temporary directory that exists only within each R session. If cache = FALSE, the function will download the data again and overwrite the local file.

verbose

A logical. If TRUE (the default), the function prints informative messages and shows download progress bar. If FALSE, the function is silent.

Value

An ⁠"sf" "data.frame"⁠ OR an ArrowObject

Examples


# Read municipal seats in an specific year
m <- read_municipal_seat(year = 2022)

Download spatial data of Brazilian municipalities

Description

Brazilian municipalities

Usage

read_municipality(
  year,
  code_muni = "all",
  simplified = TRUE,
  output = "sf",
  showProgress = TRUE,
  cache = TRUE,
  verbose = TRUE,
  keep_areas_operacionais = FALSE
)

Arguments

year

Numeric. Year of the data in YYYY format. It defaults to NULL and reads the data from the latest year available.

code_muni

The 7-digit code of a municipality. If code_muni = "all" (Default), the function downloads all the data available in the country. Alternatively, if a two-digit state code or a two-letter uppercase abbreviation of a state is passed (e.g. 33 or "RJ"), all data of that state are downloaded. Municipality codes can be consulted with the geobr::lookup_muni() function.

simplified

Logic FALSE or TRUE, indicating whether the function should return the data set with 'original' spatial resolution or a data set with 'simplified' geometry. Defaults to TRUE. For spatial analysis and statistics users should set simplified = FALSE. Borders have been simplified by removing vertices of borders using ⁠st_simplify{sf}⁠ preserving topology with a dTolerance of 100.

output

String. Type of object returned by the function. Defaults to "sf", which loads the data into memory as an sf object. Alternatively, "duckdb" returns a lazy spatial table backed by DuckDB via the duckspatial package, and "arrow" returns an Arrow dataset. Both "duckdb" and "arrow" support out-of-memory processing of large data sets.

showProgress

Logical. Defaults to TRUE display progress bar.

cache

Logical. Whether the function should read the data cached locally, which is faster. Defaults to cache = TRUE. By default, geobr stores data files in a temporary directory that exists only within each R session. If cache = FALSE, the function will download the data again and overwrite the local file.

verbose

A logical. If TRUE (the default), the function prints informative messages and shows download progress bar. If FALSE, the function is silent.

keep_areas_operacionais

Logic. Whether the function should keep the polygons of Lagoas dos Patos and Lagoa Mirim in the State of Rio Grande do Sul (considered as areas estaduais operacionais). Defaults to FALSE.

Value

An ⁠"sf" "data.frame"⁠ OR an ArrowObject

Examples


# Read specific municipality at a given year
mun <- read_municipality(code_muni = 1200179, year = 2017)

# Read all municipalities of a state at a given year
mun <- read_municipality(code_muni = 33, year = 2010)
mun <- read_municipality(code_muni = "RJ", year = 2010)

# Read all municipalities of the country at a given year
mun <- read_municipality(code_muni = "all", year = 2018)

Download spatial data of neighborhood limits of Brazilian municipalities

Description

This data set includes the neighborhood limits of Brazilian municipalities. The data is only available for those municipalities where neighborhood information was collected in the population census. The data set is based on aggregations of the census tracts from the Brazilian census.

Usage

read_neighborhood(
  year,
  code_muni = "all",
  simplified = TRUE,
  output = "sf",
  showProgress = TRUE,
  cache = TRUE,
  verbose = TRUE
)

Arguments

year

Numeric. Year of the data in YYYY format. It defaults to NULL and reads the data from the latest year available.

code_muni

The 7-digit code of a municipality. If code_muni = "all" (Default), the function downloads all the data available in the country. Alternatively, if a two-digit state code or a two-letter uppercase abbreviation of a state is passed (e.g. 33 or "RJ"), all data of that state are downloaded. Municipality codes can be consulted with the geobr::lookup_muni() function.

simplified

Logic FALSE or TRUE, indicating whether the function should return the data set with 'original' spatial resolution or a data set with 'simplified' geometry. Defaults to TRUE. For spatial analysis and statistics users should set simplified = FALSE. Borders have been simplified by removing vertices of borders using ⁠st_simplify{sf}⁠ preserving topology with a dTolerance of 100.

output

String. Type of object returned by the function. Defaults to "sf", which loads the data into memory as an sf object. Alternatively, "duckdb" returns a lazy spatial table backed by DuckDB via the duckspatial package, and "arrow" returns an Arrow dataset. Both "duckdb" and "arrow" support out-of-memory processing of large data sets.

showProgress

Logical. Defaults to TRUE display progress bar.

cache

Logical. Whether the function should read the data cached locally, which is faster. Defaults to cache = TRUE. By default, geobr stores data files in a temporary directory that exists only within each R session. If cache = FALSE, the function will download the data again and overwrite the local file.

verbose

A logical. If TRUE (the default), the function prints informative messages and shows download progress bar. If FALSE, the function is silent.

Value

An ⁠"sf" "data.frame"⁠ OR an ArrowObject

Examples


# Read neighborhoods of Brazilian municipalities
n <- read_neighborhood(year = 2022)

# Read neighborhoods of two municipalities, Recife and Porto Alegre in this example
r <- read_neighborhood(
  year = 2022,
  code_muni = c(2611606, 4314902)
  )

Download geolocated data of polling places

Description

Data comes from the Superior Electoral Court (TSE). The spatial coordinates used in geobr are a combination of the coordinates produced by the original data producer and the coordinates found via geocoding with the geocodebr package https://CRAN.R-project.org/package=geocodebr. Whenever the distance between the coordinates from both sources is smaller than 800 meters, geobr uses coordinates from the data producer. When the distance between the two sources is greater than 800 meters and the results from geocodebr have a precision level finer than 800 meters, geobr uses the coordinates from geocodebr. When the coordinates from the original source are missing, geobr also uses geocodebr coordinates, regardless of precision level. The source of the spatial coordinates used in each observation is registered in the data in a specific column coords_source. Additional columns indicating the precision level of geocodebr geocoding are also included in the data.

Usage

read_polling_places(
  year,
  code_muni = "all",
  output = "sf",
  showProgress = TRUE,
  cache = TRUE,
  verbose = TRUE
)

Arguments

year

Numeric. Year of the data in YYYY format. It defaults to NULL and reads the data from the latest year available.

code_muni

The 7-digit code of a municipality. If code_muni = "all" (Default), the function downloads all the data available in the country. Alternatively, if a two-digit state code or a two-letter uppercase abbreviation of a state is passed (e.g. 33 or "RJ"), all data of that state are downloaded. Municipality codes can be consulted with the geobr::lookup_muni() function.

output

String. Type of object returned by the function. Defaults to "sf", which loads the data into memory as an sf object. Alternatively, "duckdb" returns a lazy spatial table backed by DuckDB via the duckspatial package, and "arrow" returns an Arrow dataset. Both "duckdb" and "arrow" support out-of-memory processing of large data sets.

showProgress

Logical. Defaults to TRUE display progress bar.

cache

Logical. Whether the function should read the data cached locally, which is faster. Defaults to cache = TRUE. By default, geobr stores data files in a temporary directory that exists only within each R session. If cache = FALSE, the function will download the data again and overwrite the local file.

verbose

A logical. If TRUE (the default), the function prints informative messages and shows download progress bar. If FALSE, the function is silent.

Value

An ⁠"sf" "data.frame"⁠ OR an ArrowObject

Examples


# Read health facilities of a given municipality
h <- read_polling_places(
  year = 2022,
  code_muni = 2800308
  )

# Read health facilities of a given state
h <- read_polling_places(
  year = 2022,
  code_muni = "SE"
  )

# Read all health facilities of the whole country
h <- read_polling_places(year = 2022)

Download population arrangements in Brazil

Description

This function reads the official data on the population arrangements (Arranjos Populacionais) in Brazil. Original data by the Brazilian Institute of Geography and Statistics (IBGE). More information about the methodology at https://www.ibge.gov.br/geociencias/organizacao-do-territorio/divisao-regional/15782-arranjos-populacionais-e-concentracoes-urbanas-do-brasil.html

Usage

read_pop_arrangements(
  year,
  code_state = "all",
  simplified = TRUE,
  output = "sf",
  showProgress = TRUE,
  cache = TRUE,
  verbose = TRUE
)

Arguments

year

Numeric. Year of the data in YYYY format. It defaults to NULL and reads the data from the latest year available.

code_state

The two-digit code of a state or a two-letter uppercase abbreviation (e.g. 33 or "RJ"). If code_state="all" (the default), the function downloads all states.

simplified

Logic FALSE or TRUE, indicating whether the function should return the data set with 'original' spatial resolution or a data set with 'simplified' geometry. Defaults to TRUE. For spatial analysis and statistics users should set simplified = FALSE. Borders have been simplified by removing vertices of borders using ⁠st_simplify{sf}⁠ preserving topology with a dTolerance of 100.

output

String. Type of object returned by the function. Defaults to "sf", which loads the data into memory as an sf object. Alternatively, "duckdb" returns a lazy spatial table backed by DuckDB via the duckspatial package, and "arrow" returns an Arrow dataset. Both "duckdb" and "arrow" support out-of-memory processing of large data sets.

showProgress

Logical. Defaults to TRUE display progress bar.

cache

Logical. Whether the function should read the data cached locally, which is faster. Defaults to cache = TRUE. By default, geobr stores data files in a temporary directory that exists only within each R session. If cache = FALSE, the function will download the data again and overwrite the local file.

verbose

A logical. If TRUE (the default), the function prints informative messages and shows download progress bar. If FALSE, the function is silent.

Value

An ⁠"sf" "data.frame"⁠ OR an ArrowObject

Examples


# Read population arrangements in an specific year
pa <- read_pop_arrangements(year = 2010)

Download spatial data of quilombola lands in Brazil

Description

Read data of quilombola areas officialy recognized by the Instituto Nacional de Colonização e Reforma Agrária - INCRA. The date refers to the date when the data was downloaded, and captures the quilombola lands recognized on that date. More info at https://dados.gov.br/dados/conjuntos-dados/comunidades-quilombolas-certificadas.

Usage

read_quilombola_land(
  date,
  code_state = "all",
  simplified = TRUE,
  output = "sf",
  showProgress = TRUE,
  cache = TRUE,
  verbose = TRUE
)

Arguments

date

Numeric. Date of the data in YYYYMM format. It defaults to NULL and reads the data from the latest date available.

code_state

The two-digit code of a state or a two-letter uppercase abbreviation (e.g. 33 or "RJ"). If code_state="all" (the default), the function downloads all states.

simplified

Logic FALSE or TRUE, indicating whether the function should return the data set with 'original' spatial resolution or a data set with 'simplified' geometry. Defaults to TRUE. For spatial analysis and statistics users should set simplified = FALSE. Borders have been simplified by removing vertices of borders using ⁠st_simplify{sf}⁠ preserving topology with a dTolerance of 100.

output

String. Type of object returned by the function. Defaults to "sf", which loads the data into memory as an sf object. Alternatively, "duckdb" returns a lazy spatial table backed by DuckDB via the duckspatial package, and "arrow" returns an Arrow dataset. Both "duckdb" and "arrow" support out-of-memory processing of large data sets.

showProgress

Logical. Defaults to TRUE display progress bar.

cache

Logical. Whether the function should read the data cached locally, which is faster. Defaults to cache = TRUE. By default, geobr stores data files in a temporary directory that exists only within each R session. If cache = FALSE, the function will download the data again and overwrite the local file.

verbose

A logical. If TRUE (the default), the function prints informative messages and shows download progress bar. If FALSE, the function is silent.

Value

An ⁠"sf" "data.frame"⁠ OR an ArrowObject

Data dictionary

Examples


# Read all quilombola areas in an specific date
q <- read_quilombola_land(date = 202605)

# Read the quilombola areas in an given state
ba <- read_quilombola_land(date = 202605, code_state = "BA")

Download spatial data of Brazil Regions

Description

Brazil macro regions

Usage

read_region(
  year,
  simplified = TRUE,
  output = "sf",
  showProgress = TRUE,
  cache = TRUE,
  verbose = TRUE
)

Arguments

year

Numeric. Year of the data in YYYY format. It defaults to NULL and reads the data from the latest year available.

simplified

Logic FALSE or TRUE, indicating whether the function should return the data set with 'original' spatial resolution or a data set with 'simplified' geometry. Defaults to TRUE. For spatial analysis and statistics users should set simplified = FALSE. Borders have been simplified by removing vertices of borders using ⁠st_simplify{sf}⁠ preserving topology with a dTolerance of 100.

output

String. Type of object returned by the function. Defaults to "sf", which loads the data into memory as an sf object. Alternatively, "duckdb" returns a lazy spatial table backed by DuckDB via the duckspatial package, and "arrow" returns an Arrow dataset. Both "duckdb" and "arrow" support out-of-memory processing of large data sets.

showProgress

Logical. Defaults to TRUE display progress bar.

cache

Logical. Whether the function should read the data cached locally, which is faster. Defaults to cache = TRUE. By default, geobr stores data files in a temporary directory that exists only within each R session. If cache = FALSE, the function will download the data again and overwrite the local file.

verbose

A logical. If TRUE (the default), the function prints informative messages and shows download progress bar. If FALSE, the function is silent.

Value

An ⁠"sf" "data.frame"⁠ OR an ArrowObject

Examples


# Read specific year
reg <- read_region(year = 2023)

Download geolocated data of schools

Description

Data comes from the School Census and Catalogue of Schools, organized by the National Institute for Educational Studies and Research Anisio Teixeira (INEP). More information available at https://www.gov.br/inep/pt-br/acesso-a-informacao/dados-abertos/inep-data/catalogo-de-escolas/. The spatial coordinates used in geobr are a combination of the coordinates produced by the original data producer and the coordinates found via geocoding with the geocodebr package https://CRAN.R-project.org/package=geocodebr. Whenever the distance between the coordinates from both sources is smaller than 800 meters, geobr uses coordinates from the data producer. When the distance between the two sources is greater than 800 meters and the results from geocodebr have a precision level finer than 800 meters, geobr uses the coordinates from geocodebr. When the coordinates from the original source are missing, geobr also uses geocodebr coordinates, regardless of precision level. The source of the spatial coordinates used in each observation is registered in the data in a specific column coords_source. Additional columns indicating the precision level of geocodebr geocoding are also included in the data.

Usage

read_schools(
  year,
  code_muni = "all",
  output = "sf",
  showProgress = TRUE,
  cache = TRUE,
  verbose = TRUE
)

Arguments

year

Numeric. Year of the data in YYYY format. It defaults to NULL and reads the data from the latest year available.

code_muni

The 7-digit code of a municipality. If code_muni = "all" (Default), the function downloads all the data available in the country. Alternatively, if a two-digit state code or a two-letter uppercase abbreviation of a state is passed (e.g. 33 or "RJ"), all data of that state are downloaded. Municipality codes can be consulted with the geobr::lookup_muni() function.

output

String. Type of object returned by the function. Defaults to "sf", which loads the data into memory as an sf object. Alternatively, "duckdb" returns a lazy spatial table backed by DuckDB via the duckspatial package, and "arrow" returns an Arrow dataset. Both "duckdb" and "arrow" support out-of-memory processing of large data sets.

showProgress

Logical. Defaults to TRUE display progress bar.

cache

Logical. Whether the function should read the data cached locally, which is faster. Defaults to cache = TRUE. By default, geobr stores data files in a temporary directory that exists only within each R session. If cache = FALSE, the function will download the data again and overwrite the local file.

verbose

A logical. If TRUE (the default), the function prints informative messages and shows download progress bar. If FALSE, the function is silent.

Value

An ⁠"sf" "data.frame"⁠ OR an ArrowObject

Examples


# Read all schools in the country
s <- read_schools(year = 2020)

# Read all schools in a given state
s <- read_schools(
  year = 2020,
  code_muni = "AC"
  )

# Read all schools in a given municipality
s <- read_schools(
  year = 2020,
  code_muni = 1200401
  )

Download spatial data of the Brazilian Semiarid region

Description

This data set returns all the municipalities which are legally included in the Brazilian Semiarid, following changes in the national legislation. The original data comes from the Brazilian Institute of Geography and Statistics (IBGE) and can be found at https://www.ibge.gov.br/geociencias/cartas-e-mapas/mapas-regionais/15974-semiarido-brasileiro.html

Usage

read_semiarid(
  year,
  simplified = TRUE,
  output = "sf",
  showProgress = TRUE,
  cache = TRUE,
  verbose = TRUE
)

Arguments

year

Numeric. Year of the data in YYYY format. It defaults to NULL and reads the data from the latest year available.

simplified

Logic FALSE or TRUE, indicating whether the function should return the data set with 'original' spatial resolution or a data set with 'simplified' geometry. Defaults to TRUE. For spatial analysis and statistics users should set simplified = FALSE. Borders have been simplified by removing vertices of borders using ⁠st_simplify{sf}⁠ preserving topology with a dTolerance of 100.

output

String. Type of object returned by the function. Defaults to "sf", which loads the data into memory as an sf object. Alternatively, "duckdb" returns a lazy spatial table backed by DuckDB via the duckspatial package, and "arrow" returns an Arrow dataset. Both "duckdb" and "arrow" support out-of-memory processing of large data sets.

showProgress

Logical. Defaults to TRUE display progress bar.

cache

Logical. Whether the function should read the data cached locally, which is faster. Defaults to cache = TRUE. By default, geobr stores data files in a temporary directory that exists only within each R session. If cache = FALSE, the function will download the data again and overwrite the local file.

verbose

A logical. If TRUE (the default), the function prints informative messages and shows download progress bar. If FALSE, the function is silent.

Value

An ⁠"sf" "data.frame"⁠ OR an ArrowObject

Examples


# read Brazilian semiarid
sa <- read_semiarid(year = 2022)

Download spatial data of Brazilian states

Description

Brazilian states

Usage

read_state(
  year = NULL,
  code_state = "all",
  simplified = TRUE,
  output = "sf",
  showProgress = TRUE,
  cache = TRUE,
  verbose = TRUE
)

Arguments

year

Numeric. Year of the data in YYYY format. It defaults to NULL and reads the data from the latest year available.

code_state

The two-digit code of a state or a two-letter uppercase abbreviation (e.g. 33 or "RJ"). If code_state="all" (the default), the function downloads all states.

simplified

Logic FALSE or TRUE, indicating whether the function should return the data set with 'original' spatial resolution or a data set with 'simplified' geometry. Defaults to TRUE. For spatial analysis and statistics users should set simplified = FALSE. Borders have been simplified by removing vertices of borders using ⁠st_simplify{sf}⁠ preserving topology with a dTolerance of 100.

output

String. Type of object returned by the function. Defaults to "sf", which loads the data into memory as an sf object. Alternatively, "duckdb" returns a lazy spatial table backed by DuckDB via the duckspatial package, and "arrow" returns an Arrow dataset. Both "duckdb" and "arrow" support out-of-memory processing of large data sets.

showProgress

Logical. Defaults to TRUE display progress bar.

cache

Logical. Whether the function should read the data cached locally, which is faster. Defaults to cache = TRUE. By default, geobr stores data files in a temporary directory that exists only within each R session. If cache = FALSE, the function will download the data again and overwrite the local file.

verbose

A logical. If TRUE (the default), the function prints informative messages and shows download progress bar. If FALSE, the function is silent.

Value

An ⁠"sf" "data.frame"⁠ OR an ArrowObject

Examples


# Read all states at a given year
ufs <- read_state(code_state="all", year = 2025)

# Read specific state at a given year
uf <- read_state(code_state="SC", year = 2025)

# Read specific state at a given year
uf <- read_state(code_state=12, year = 2025)

Download spatial data of IBGE's statistical grid

Description

Official gridded population estimate of Brazil.

Usage

read_statistical_grid(
  year,
  code_muni,
  output = "sf",
  showProgress = TRUE,
  cache = TRUE,
  verbose = TRUE
)

Arguments

year

Numeric. Year of the data in YYYY format. It defaults to NULL and reads the data from the latest year available.

code_muni

The 7-digit code of a municipality. If code_muni = "all" (Default), the function downloads all the data available in the country. Alternatively, if a two-digit state code or a two-letter uppercase abbreviation of a state is passed (e.g. 33 or "RJ"), all data of that state are downloaded. Municipality codes can be consulted with the geobr::lookup_muni() function.

output

String. Type of object returned by the function. Defaults to "sf", which loads the data into memory as an sf object. Alternatively, "duckdb" returns a lazy spatial table backed by DuckDB via the duckspatial package, and "arrow" returns an Arrow dataset. Both "duckdb" and "arrow" support out-of-memory processing of large data sets.

showProgress

Logical. Defaults to TRUE display progress bar.

cache

Logical. Whether the function should read the data cached locally, which is faster. Defaults to cache = TRUE. By default, geobr stores data files in a temporary directory that exists only within each R session. If cache = FALSE, the function will download the data again and overwrite the local file.

verbose

A logical. If TRUE (the default), the function prints informative messages and shows download progress bar. If FALSE, the function is silent.

Value

An ⁠"sf" "data.frame"⁠ OR an ArrowObject

Examples



# Read the grid covering a given state at a given year
grid_rio <- read_statistical_grid(
  year = 2022,
  code_muni = "RJ"
  )

# Read the grid covering a given municipality at a given year
grid_ssalvador <- read_statistical_grid(
  year = 2022,
  code_muni = 2927408
  )

Download spatial data of urbanized areas in Brazil

Description

This function reads the official data on the urban footprint of Brazilian cities. Original data by the Brazilian Institute of Geography and Statistics (IBGE) For more information about the methodology, see details at https://biblioteca.ibge.gov.br/visualizacao/livros/liv100639.pdf

Usage

read_urban_area(
  year,
  code_muni = "all",
  simplified = TRUE,
  output = "sf",
  showProgress = TRUE,
  cache = TRUE,
  verbose = TRUE
)

Arguments

year

Numeric. Year of the data in YYYY format. It defaults to NULL and reads the data from the latest year available.

code_muni

The 7-digit code of a municipality. If code_muni = "all" (Default), the function downloads all the data available in the country. Alternatively, if a two-digit state code or a two-letter uppercase abbreviation of a state is passed (e.g. 33 or "RJ"), all data of that state are downloaded. Municipality codes can be consulted with the geobr::lookup_muni() function.

simplified

Logic FALSE or TRUE, indicating whether the function should return the data set with 'original' spatial resolution or a data set with 'simplified' geometry. Defaults to TRUE. For spatial analysis and statistics users should set simplified = FALSE. Borders have been simplified by removing vertices of borders using ⁠st_simplify{sf}⁠ preserving topology with a dTolerance of 100.

output

String. Type of object returned by the function. Defaults to "sf", which loads the data into memory as an sf object. Alternatively, "duckdb" returns a lazy spatial table backed by DuckDB via the duckspatial package, and "arrow" returns an Arrow dataset. Both "duckdb" and "arrow" support out-of-memory processing of large data sets.

showProgress

Logical. Defaults to TRUE display progress bar.

cache

Logical. Whether the function should read the data cached locally, which is faster. Defaults to cache = TRUE. By default, geobr stores data files in a temporary directory that exists only within each R session. If cache = FALSE, the function will download the data again and overwrite the local file.

verbose

A logical. If TRUE (the default), the function prints informative messages and shows download progress bar. If FALSE, the function is silent.

Value

An ⁠"sf" "data.frame"⁠ OR an ArrowObject

Examples


# Read urban footprint of Brazilian cities in an specific year
d <- read_urban_area(year = 2015)

Download urban concentration areas in Brazil

Description

This function reads the official data on the urban concentration areas (Áreas de Concentração de População) in Brazil. Original data by the Brazilian Institute of Geography and Statistics (IBGE). More information about the methodology at https://www.ibge.gov.br/geociencias/organizacao-do-territorio/divisao-regional/15782-arranjos-populacionais-e-concentracoes-urbanas-do-brasil.html

Usage

read_urban_concentrations(
  year,
  code_state = "all",
  simplified = TRUE,
  output = "sf",
  showProgress = TRUE,
  cache = TRUE,
  verbose = TRUE
)

Arguments

year

Numeric. Year of the data in YYYY format. It defaults to NULL and reads the data from the latest year available.

code_state

The two-digit code of a state or a two-letter uppercase abbreviation (e.g. 33 or "RJ"). If code_state="all" (the default), the function downloads all states.

simplified

Logic FALSE or TRUE, indicating whether the function should return the data set with 'original' spatial resolution or a data set with 'simplified' geometry. Defaults to TRUE. For spatial analysis and statistics users should set simplified = FALSE. Borders have been simplified by removing vertices of borders using ⁠st_simplify{sf}⁠ preserving topology with a dTolerance of 100.

output

String. Type of object returned by the function. Defaults to "sf", which loads the data into memory as an sf object. Alternatively, "duckdb" returns a lazy spatial table backed by DuckDB via the duckspatial package, and "arrow" returns an Arrow dataset. Both "duckdb" and "arrow" support out-of-memory processing of large data sets.

showProgress

Logical. Defaults to TRUE display progress bar.

cache

Logical. Whether the function should read the data cached locally, which is faster. Defaults to cache = TRUE. By default, geobr stores data files in a temporary directory that exists only within each R session. If cache = FALSE, the function will download the data again and overwrite the local file.

verbose

A logical. If TRUE (the default), the function prints informative messages and shows download progress bar. If FALSE, the function is silent.

Value

An ⁠"sf" "data.frame"⁠ OR an ArrowObject

Examples


# Read urban concentration areas in an specific year
uc <- read_urban_concentrations(year = 2010)

Download spatial data of census weighting areas

Description

Data of Census Weighting Areas (area de ponderação) of the Brazilian Population Census

Usage

read_weighting_area(
  year,
  code_weighting = "all",
  simplified = TRUE,
  output = "sf",
  showProgress = TRUE,
  cache = TRUE,
  verbose = TRUE
)

Arguments

year

Numeric. Year of the data in YYYY format. It defaults to NULL and reads the data from the latest year available.

code_weighting

The 7-digit code of a Municipality. If the two-digit code or a two-letter uppercase abbreviation of a state is passed, (e.g. 33 or "RJ") the function will load all weighting areas of that state. If code_weighting="all" (the default), all weighting areas of the country are loaded.

simplified

Logic FALSE or TRUE, indicating whether the function should return the data set with 'original' spatial resolution or a data set with 'simplified' geometry. Defaults to TRUE. For spatial analysis and statistics users should set simplified = FALSE. Borders have been simplified by removing vertices of borders using ⁠st_simplify{sf}⁠ preserving topology with a dTolerance of 100.

output

String. Type of object returned by the function. Defaults to "sf", which loads the data into memory as an sf object. Alternatively, "duckdb" returns a lazy spatial table backed by DuckDB via the duckspatial package, and "arrow" returns an Arrow dataset. Both "duckdb" and "arrow" support out-of-memory processing of large data sets.

showProgress

Logical. Defaults to TRUE display progress bar.

cache

Logical. Whether the function should read the data cached locally, which is faster. Defaults to cache = TRUE. By default, geobr stores data files in a temporary directory that exists only within each R session. If cache = FALSE, the function will download the data again and overwrite the local file.

verbose

A logical. If TRUE (the default), the function prints informative messages and shows download progress bar. If FALSE, the function is silent.

Value

An ⁠"sf" "data.frame"⁠ OR an ArrowObject

Examples


# Read specific weighting area at a given year
w <- read_weighting_area(
  code_weighting = 5201108005004,
  year = 2010
  )

# Read all weighting areas of a state at a given year
w <- read_weighting_area(
  code_weighting = "DF",
  year = 2010
  )

# Read all weighting areas of a municipality at a given year
w <- read_weighting_area(
  code_weighting = 5201108,
  year = 2010
  )

# Read all weighting areas of the country at a given year
w <- read_weighting_area(
  code_weighting = "all",
  year = 2010
  )

Remove islands from Brazil

Description

Removes Brazilian islands that are approximately more than 20 km from the mainland coast. This is useful when analyses or data visualization should focus on the continental territory of Brazil and exclude distant oceanic islands.

Usage

remove_islands(x)

Arguments

x

An 'sf' object with CRS EPSG:4674. Usually an object returned from other geobr functions, such as read_country(), read_states(), read_municipality(), or similar functions.

Value

An sf data frame with the same attributes as x, but with distant islands removed from the geometry.

Examples


library(geobr)
library(sf)

br <- read_country(year = 1991)

br_no_islands <- remove_islands(br)

plot(br)

Select data type: 'original' or 'simplified' (default)

Description

Select data type: 'original' or 'simplified' (default)

Usage

select_geometry_type(temp_meta, simplified_geometry)

Arguments

temp_meta

A data.frame with the metadata of geobr datasets

simplified_geometry

Logical TRUE or FALSE indicating whether the function should return a dataset with the 'original' geometry or a dataset with 'simplified' geometry (Defaults to TRUE)

Select metadata

Description

Select metadata

Usage

select_metadata(
  geography,
  year = parent.frame()$year,
  simplified = parent.frame()$simplified,
  verbose = parent.frame()$verbose
)

Arguments

geography

Which geography will be downloaded.

year

Year of the dataset (passed by read_ function).

simplified

Logical TRUE or FALSE indicating whether the function returns the 'original' dataset with high resolution or a dataset with 'simplified' borders (Defaults to TRUE).

Examples

## Not run:  if (interactive()) {

library(geobr)

df <- download_metadata()

}
## End(Not run)

Select year input

Description

Select year input

Usage

select_year_input(
  temp_meta,
  y = parent.frame()$year,
  verbose = parent.frame()$verbose
)

Arguments

temp_meta

A dataframe with the file_url addresses of geobr datasets

y

Year of the dataset (passed by red_ function)

verbose

A logical. If TRUE (the default), the function prints informative messages and shows download progress bar. If FALSE, the function is silent.