geobr

Easy access to official spatial data sets of Brazil in R and Python

Showing:

Popularity

Downloads/wk

0

GitHub Stars

481

Maintenance

Last Commit

1mo ago

Contributors

27

Package

Dependencies

0

License

MIT + file LICENSE.txt

Categories

Readme

geobr: Download Official Spatial Data Sets of Brazil

logo logo

geobr is a computational package to download official spatial data sets of Brazil. The package includes a wide range of geospatial data in geopackage format (like shapefiles but better), available at various geographic scales and for various years with harmonized attributes, projection and topology (see detailed list of available data sets below).

The package is currently available in R and Python.

RPythonRepo
CRAN/METACRAN Version
CRAN/METACRAN Total downloads
CRAN/METACRAN downloads per month
Codecov test coverage
Lifecycle: stable
PyPI version
Downloads
Downloads
Lifecycle: maturing
GitHub stars
R build status
Project Status: Active – The project has reached a stable, usable state and is being actively developed.

Installation R

# From CRAN
  install.packages("geobr")
  library(geobr)

# or use the development version with latest features
  utils::remove.packages('geobr')
  devtools::install_github("ipeaGIT/geobr", subdir = "r-package")
  library(geobr)

obs. If you use Linux, you need to install a couple dependencies before installing the libraries sf and geobr. More info here.

Installation Python

pip install geobr

Windows users:

conda create -n geo_env
conda activate geo_env  
conda config --env --add channels conda-forge  
conda config --env --set channel_priority strict  
conda install python=3 geopandas  
pip install geobr

Basic Usage

The syntax of all geobr functions operate on the same logic so it becomes intuitive to download any data set using a single line of code. Like this:

R, reading the data as an sf object

library(geobr)

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

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

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

More examples in the intro Vignette

Python, reading the data as a geopandas object

from geobr import read_municipality

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

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

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

More examples here

Available datasets:

👉 All datasets use geodetic reference system "SIRGAS2000", CRS(4674).

FunctionGeographies availableYears availableSource
read_countryCountry1872, 1900, 1911, 1920, 1933, 1940, 1950, 1960, 1970, 1980, 1991, 2000, 2001, 2010, 2013, 2014, 2015, 2016, 2017, 2018, 2019, 2020IBGE
read_regionRegion2000, 2001, 2010, 2013, 2014, 2015, 2016, 2017, 2018, 2019, 2020IBGE
read_stateStates1872, 1900, 1911, 1920, 1933, 1940, 1950, 1960, 1970, 1980, 1991, 2000, 2001, 2010, 2013, 2014, 2015, 2016, 2017, 2018, 2019, 2020IBGE
read_meso_regionMeso region2000, 2001, 2010, 2013, 2014, 2015, 2016, 2017, 2018, 2019, 2020IBGE
read_micro_regionMicro region2000, 2001, 2010, 2013, 2014, 2015, 2016, 2017, 2018, 2019, 2020IBGE
read_intermediate_regionIntermediate region2017, 2019, 2020IBGE
read_immediate_regionImmediate region2017, 2019, 2020IBGE
read_municipalityMunicipality1872, 1900, 1911, 1920, 1933, 1940, 1950, 1960, 1970, 1980, 1991, 2000, 2001, 2005, 2007, 2010, 2013, 2014, 2015, 2016, 2017, 2018, 2019, 2020IBGE
read_municipal_seatMunicipality seats (sedes municipais)1872, 1900, 1911, 1920, 1933, 1940, 1950, 1960, 1970, 1980, 1991, 2010IBGE
read_weighting_areaCensus weighting area (área de ponderação)2010IBGE
read_census_tractCensus tract (setor censitário)2000, 2010, 2017, 2019, 2020IBGE
read_statistical_gridStatistical Grid of 200 x 200 meters2010IBGE
read_metro_areaMetropolitan areas1970, 2001, 2002, 2003, 2005, 2010, 2013, 2014, 2015, 2016, 2017, 2018IBGE
read_urban_areaUrban footprints2005, 2015IBGE
read_amazonBrazil's Legal Amazon2012MMA
read_biomesBiomes2004, 2019IBGE
read_conservation_unitsEnvironmental Conservation Units201909MMA
read_disaster_risk_areaDisaster risk areas2010CEMADEN and IBGE
read_indigenous_landIndigenous lands201907, 202103FUNAI
read_semiaridSemi Arid region2005, 2017IBGE
read_health_facilitiesHealth facilities2015CNES, DataSUS
read_health_regionHealth regions and macro regions1991, 1994, 1997, 2001, 2005, 2013DataSUS
read_neighborhoodNeighborhood limits2010IBGE
read_schoolsSchools2020INEP
read_comparable_areasHistorically comparable municipalities, aka Areas minimas comparaveis (AMCs)1872,1900,1911,1920,1933,1940,1950,1960,1970,1980,1991,2000,2010IBGE
read_urban_concentrationsUrban concentration areas (concentrações urbanas)2015IBGE
read_pop_arrangementsPopulation arrangements (arranjos populacioanis)2015IBGE

Other functions:

FunctionAction
list_geobrList all datasets available in the geobr package
lookup_muniLook up municipality codes by their name, or the other way around
grid_state_correspondence_tableLoads a correspondence table indicating what quadrants of IBGE's statistical grid intersect with each state
cep_to_stateDetermine the state of a given CEP postal code
......

Note 1. Data sets and Functions marked with "dev" are only available in the development version of geobr.

Note 2. Most data sets are available at scale 1:250,000 (see documentation for details).

Coming soon:

GeographyYears availableSource
read_census_tract2007IBGE
Longitudinal Database* of micro regionsvarious yearsIBGE
Longitudinal Database* of Census tractsvarious yearsIBGE
.........

'*' Longitudinal Database refers to áreas mínimas comparáveis (AMCs)

Contributing to geobr

If you would like to contribute to geobr and add new functions or data sets, please check this guide to propose your contribution.


As of today, there is another R package with similar functionalities: simplefeaturesbr. The geobr package has a few advantages when compared to simplefeaturesbr, including for example:

  • A same syntax structure across all functions, making the package very easy and intuitive to use
  • Access to a wider range of official spatial data sets, such as states and municipalities, but also macro-, meso- and micro-regions, weighting areas, census tracts, urbanized areas, etc
  • Access to shapefiles with updated geometries for various years
  • Harmonized attributes and geographic projections across geographies and years
  • Option to download geometries with simplified borders for fast rendering
  • Stable version published on CRAN for R users, and on PyPI for Python users

Similar packages for other countries/continents


Credits ipea

Original shapefiles are created by official government institutions. The geobr package is developed by a team at the Institute for Applied Economic Research (Ipea), Brazil. If you want to cite this package, you can cite it as:

  • Pereira, R.H.M.; Gonçalves, C.N.; et. all (2019) geobr: Loads Shapefiles of Official Spatial Data Sets of Brazil. GitHub repository - https://github.com/ipeaGIT/geobr.

Rate & Review

Great Documentation0
Easy to Use0
Performant0
Highly Customizable0
Bleeding Edge0
Responsive Maintainers0
Poor Documentation0
Hard to Use0
Slow0
Buggy0
Abandoned0
Unwelcoming Community0
100