Metadata-Version: 2.4
Name: geocensobr
Version: 0.1.0
Summary: Biblioteca Python para consulta de dados do Censo Brasileiro
Author: Diego Abreu
License: MIT
Project-URL: Homepage, https://pypi.org/project/geocensobr/
Project-URL: Repository, https://github.com/diegoabreu/GeoCensoBR
Project-URL: Issues, https://github.com/diegoabreu/GeoCensoBR/issues
Keywords: censo,ibge,geospatial,geodata,brasil
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: GIS
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: geopandas
Requires-Dist: shapely
Requires-Dist: pandas
Requires-Dist: openpyxl
Provides-Extra: dev
Requires-Dist: pytest>=7; extra == "dev"
Requires-Dist: pytest-cov>=4; extra == "dev"
Dynamic: license-file

# GeoCensoBR

Biblioteca Python para consulta de dados do Censo Demográfico Brasileiro (IBGE) através de latitude e longitude.

## O que a biblioteca faz?

- Baixa automaticamente os arquivos oficiais do IBGE na primeira execucao:
  - `BR_setores_CD2022.gpkg`
  - `Dicionario_de_dados_malha_agregados.xlsx`
- Busca nos dados de geometria do arquivo .gpkg do IBGE qual é o setor censitario correspondente ao ponto (`lat`, `lon`) consultado.
- Através da função `dicionario()` exibe o dicionário de dados disponibilizado pelo IBGE.

## Instalação

```bash
pip install geocensobr
```

## Uso

### 1) Importe a biblioteca 
Essa etapa realiza o download das bases do IBGE (Se necessário) e o carregamento das bases. Dependendo do seu computador e conexão, pode levar alguns minutos.

```python
import geocensobr
```

### 2) Consulte um ponto por latitude e longitude

```python
resultado = geocensobr.buscar(lat=-22.951608953416375, lon=-43.21049019060587)
display(resultado)
```

- Retorna um `pandas.DataFrame` com os atributos do setor censitário quando encontra o ponto.
- Retorna `None` quando nao ha setor para o ponto informado.

### 3) Consulte o dicionário de dados do Censo

```python
df_dicionario = geocensobr.dicionario()
display(df_dicionario.head())
```

### 4) Fluxo da primeira execução

No momento do `import geocensobr` (primeiro import no ambiente):

1. O diretorio `geocensobr/data` é criado automaticamente dentro do ambiente Python.
2. Os arquivos do IBGE são baixados automaticamente, caso nao existam.
3. O arquivo `.gpkg` é carregado em memória para consultas mais rapidas.
4. Em caso de erro de download, a biblioteca levanta `DataDownloadError` com instrução para download manual.

## Solução de problemas (download manual)

Se houver falha de download automático dos arquivos do IBGE:

1. Acesse o FTP do IBGE:  
   [https://ftp.ibge.gov.br/Censos/Censo_Demografico_2022/Agregados_por_Setores_Censitarios/malha_com_atributos/](https://ftp.ibge.gov.br/Censos/Censo_Demografico_2022/Agregados_por_Setores_Censitarios/malha_com_atributos/)
2. Baixe manualmente:
   - [BR_setores_CD2022.gpkg](https://ftp.ibge.gov.br/Censos/Censo_Demografico_2022/Agregados_por_Setores_Censitarios/malha_com_atributos/setores/gpkg/BR/BR_setores_CD2022.gpkg)
   - [Dicionario_de_dados_malha_agregados.xlsx](https://ftp.ibge.gov.br/Censos/Censo_Demografico_2022/Agregados_por_Setores_Censitarios/malha_com_atributos/Dicionario_de_dados_malha_agregados.xlsx)
3. Copie os dois arquivos para o diretorio `site-packages/geocensobr/data` do ambiente onde a biblioteca foi instalada.

## Licenca

Projeto licenciado sob MIT. Veja `LICENSE`.
