Universalizando o acesso a dados de qualidade no Brasil.
A Base dos Dados Mais (BD+) é um datalake público no Google BigQuery com os principais conjuntos de dados abertos do Brasil. Na BD+ você encontra tabelas tratadas e prontas para uso de forma gratuita. Disponibilizamos e mantemos neste projeto pacotes de acesso à BD+ em diferentes linguagens.
O projeto faz parte da Base dos Dados, uma organização sem fins lucrativos com a missão de universalizar o acesso a dados de qualidade para todes.
R | Python | Stata |
---|---|---|
install.packages("basedosdados") |
pip install basedosdados |
- |
- 📝 Como citar o projeto
- 🐍 Usando em Python
Usando em R
- Análises e tutoriais:
- ⚙️ Desenvolvimento
- 👥 Como contribuir ↗
- 💚 Apoie o projeto! ↗
O projeto (software) está sob licenca MIT - logo, pode ser utilizado e modificado sem restrições desde que sejam remetidos os direitos autorais originais - veja o texto de referência aqui.
Caso queira citar o projeto numa publicação, artigo ou na web, utilize o modelo no menu ao lado conforme a imagem.
💡 Quer divulgar seu projeto nas nossas redes? Envie para [email protected]
pip install basedosdados
import basedosdados as bd
df = bd.read_table('br_ibge_pib', 'municipio', billing_project_id="<YOUR-PROJECT>")
Caso esteja acessando da primeira vez, vão aparecer alguns passos na tela para autenticar seu projeto - basta segui-los!
É necessário criar um projeto para que você possa fazer as queries no nosso repositório. Ter um projeto é de graça e basta ter uma conta Google (seu gmail por exemplo). Veja aqui como criar um projeto no Google Cloud.
Se possível, armazene suas credenciais em um arquivo
dotenv
:"billing_project_id=<suas_credenciais_do_projeto>" >> .env
import basedosdados as bd
# Bens dos candidatos de Tocantins em 2020
query = """
SELECT *
FROM `basedosdados.br_tse_eleicoes.bens_candidato`
WHERE ano = 2020
AND sigla_uf = 'TO'
"""
df = bd.read_sql(query, billing_project_id="<YOUR-PROJECT>")
Caso esteja acessando da primeira vez, vão aparecer alguns passos na tela para autenticar seu projeto - basta segui-los!
import basedosdados as bd
bd.list_datasets()
import basedosdados as bd
# seta o billing_project_id global
bd.config.billing_project_id = '<billing-project-id>'
query = """
SELECT
*
FROM `basedosdados.br_bd_diretorios_brasil.municipio`
"""
df = bd.read_sql(query=query)
Para saber mais, veja os exemplos ou a documentação da API
Caso você precise ter uma configuração adicional, com uma service account
diferente, você pode criar uma configuração e utilizá-la em conjunto com a default, apenas alterando um atributo. Você deverá fazer o processo abaixo usando o terminal, mas esta forma só funcionará no Python.
Para isso, siga os seguintes passos:
- Renomeie a pasta com o comando abaixo (pode ser o nome que quiser)
mv ~/.basedosdados ~/.basedosdados_default
- Neste momento, o pacote não terá a configuração padrão. Assim, ao rodar o comando
ele irá criar uma nova configuração padrão, que será salva na pasta
basedosdados config init
~/.basedosdados
(que será recriada). Lembre-se de, no passo em que é oferecido um link do Google Cloud Platform (GCP) para criar a novaservice account
, observar que seu navegador esteja logado com a conta que você deseja utilizar. - Faça todo o processo como anteriormete, passando os parâmetros que deseja utilizar com esta nova conta, como o
path
dos metadados, o nome dobucket
do Google Cloud Storage, etc. - Ao salvar as novas
service accounts
(prod e staging), certifique-se de salvar na pasta.basedosdados
criada no passo 1. Na verdade, esta é apenas a repetição do processo de criação de uma nova configuração. - Renomeie a pasta criada no passo 1 para o nome que desejar, como
~/.bd_minha_nova_conta
. - Caso você queira que a primeira configuração seja a padrão, retorne o nome da pasta modificada anterioremnte (
.basedosdados_default
) para o valor utilizado como padrão pelo pacotebasedosdados
, usando o comandomv ~/.basedosdados_default ~/.basedosdados
. - A partir de agora, você poderá usar a nova conta (no Python), bastando utilizar o seguinte processo:
e, se quiser voltar para a configuração padrão, basta utilizar o comando
import basedosdados as bd bd.config.project_config_path = f"{home}/.bd_minha_nova_conta"
Importante observar que, ao alterar o path de configuração do Python ele valerá para a sessão. Então é recomendável que ele seja usado com cuidado, evitanto trocas numa mesma sessão - especialmente quando estiver usandobd.config.project_config_path = f"{home}/.basedosdados"
Jupyter Notebook
onde é comum a reutilização de células anteriores, sem redefinição de variáveis e atributos anteriormente setados.
install.packages("basedosdados")
# ou a versão de desenvolvimento
devtools::install_github("basedosdados/mais", subdir = "r-package")
read_sql
executa queries no banco e as devolve em dataframes (sempre na classe tibble
), download
escreve o resultado da query em um arquivo .csv
no disco.
library(basedosdados)
set_billing_id("id do seu projeto aqui") # autenticação para acesso aos dados
pib_per_capita <- "
SELECT
pib.id_municipio ,
pop.ano,
pib.PIB / pop.populacao as pib_per_capita
FROM `basedosdados.br_ibge_pib.municipio` as pib
INNER JOIN `basedosdados.br_ibge_populacao.municipio` as pop
ON pib.id_municipio = pop.id_municipio AND pib.ano = pop.ano"
(data <- read_sql(pib_per_capita)) # leia os dados em memória
download(pib_per_capita, "pib_per_capita.csv") # salve os dados em disco
Ou use o nosso backend para o dplyr
e faça queries com código, sem SQL.
query <- basedosdados::bdplyr("br_inep_ideb.municipio") %>%
dplyr::select(ano, id_municipio, sigla_uf, ideb) %>%
dplyr::filter(sigla_uf == "AC", ano < 2021) %>%
dplyr::group_by(ano) %>%
dplyr::summarise(ideb_medio = mean(ideb, na.rm = TRUE))
basedosdados::bd_collect(query) # retorne como um tibble
basedosdados::bd_write_csv(query, "ideb_medio.csv")
basedosdados::bd_write_rds(query, "ideb_medio.rds")
bd_write
é uma extensão para formatos customizados.
basedosdados::bd_write(query, .write_fn = writexl::write_xlsx, "ideb_medio.xlsx")
basedosdados::bd_write(query, .write_fn = jsonlite::write_json, "ideb_medio.json")
basedosdados::bd_write(query, .write_fn = haven::write_dta, "ideb_medio.dta")
O argumento .write_fn
espera uma função que receba como argumento um tibble e um endereço de escrita, compatível com a interface convencional da língua para escrever arquivos em disco. A princípio, toda função write_*
disponível no CRAN deve funcionar.
Caso encontre algum problema no pacote e queira ajudar, basta documentar o problema em um exemplo mínimo reprodutível e abrir uma issue.
Você pode fazer buscas por tabelas usando palavras-chave ou buscar descrições de conjuntos e tabelas:
dataset_search("educação")
get_dataset_description("br_sp_alesp")
get_table_description("br_sp_alesp", "deputado")
Caso esteja acessando da primeira vez, vão aparecer alguns passos na tela para autenticar seu projeto com sua conta google e possivelmente na Tidyverse API - basta segui-los! As credenciais ficam armazenadas no computador então usuários com mais de uma máquina talvez precisem autenticar mais de uma vez. É necessário criar um projeto para que você possa fazer as queries no nosso repositório. Ter um projeto é de graça e basta ter uma conta Google (seu gmail por exemplo). Veja aqui como criar um projeto no Google Cloud. Se possível, armazene suas credenciais em um arquivo
dotenv
, em bash o comando é"billing_project_id=<suas_credenciais_do_projeto>" >> .env
. Veja aqui como criar um arquivo dotenv.
Para rodar a documentação localmente:
python -m venv .mais # cria ambiente virtual (só rodar da primeira vez)
. .mais/bin/activate # ativa ambiente virtual
pip install --upgrade -r python-package/requirements-dev.txt # instala dependências
python python-package/setup.py develop # instala pacote local
mkdocs serve # cria documentacao em: https://localhost:8000/
Atualize os docs adicionando ou editando os arquivos .md
em docs/
.
Para adicionar seu arquivo no sumário da documentação, adicione-o em
mkdocs.yml
sob a chave nav
:
nav:
- Home:
- Aprenda sobre a BD: index.md
- BigQuery: access_data_bq.md
- Pacotes: access_data_packages.md
- Contribua: colab.md
- [Seu novo título]: <seu_arquivo>.md