Metadata-Version: 2.4
Name: base-contratos
Version: 0.1.1
Summary: Obtém contratos públicos do conjunto de dados BASE/IMPIC em dados.gov.pt
Project-URL: Homepage, https://github.com/openlousada/base-contratos
Project-URL: Repository, https://github.com/openlousada/base-contratos
Project-URL: Issues, https://github.com/openlousada/base-contratos/issues
License: MIT
Keywords: civic-tech,open-data,portugal,procurement,public-contracts
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Requires-Python: >=3.11
Requires-Dist: httpx>=0.27
Requires-Dist: openpyxl>=3.1
Requires-Dist: pandas>=2.0
Requires-Dist: rich>=13.0
Description-Content-Type: text/markdown

<img src="https://raw.githubusercontent.com/openlousada/base-contratos/main/banner.png" alt="base-contratos — Contratos públicos do BASE/IMPIC, em acesso aberto." width="100%" />

# base-contratos

Obtém contratos públicos do [conjunto de dados BASE/IMPIC](https://dados.gov.pt/pt/datasets/contratos-publicos-portal-base-impic-contratos-de-2012-a-2026/) em dados.gov.pt.

O conjunto de dados cobre todos os contratos públicos adjudicados em Portugal desde 2012, com atualização quinzenal. Esta biblioteca filtra por uma ou mais entidades adjudicantes (NIF) e devolve registos estruturados.

## Instalação

```
pip install base-contratos
```

## Utilização

### Como biblioteca

```python
from base_contratos import fetch_all, fetch_year

# Todos os contratos de uma entidade em todos os anos disponíveis
records = fetch_all("505279460")

# Um único ano
records = fetch_year("505279460", 2024)

# Múltiplas entidades
records = fetch_all(["505279460", "500754011"])

# Com cache local para evitar re-descarregamentos
records = fetch_all("505279460", cache_dir="~/.cache/base-contratos")

# Anos disponíveis no conjunto de dados
from base_contratos import list_available_years
print(list_available_years())  # [2012, 2013, ..., 2025]
```

Cada registo é um dict com os seguintes campos:

| Campo | Descrição |
|---|---|
| `year` | Ano do contrato |
| `contracting_entity_nif` | NIF da entidade adjudicante |
| `contractor_name` | Nome da entidade adjudicatária |
| `contractor_nif` | NIF da entidade adjudicatária (se disponível) |
| `contract_type` | `works`, `services` ou `goods` |
| `description` | Objeto do contrato |
| `amount` | Preço contratual (€) |
| `awarded_date` | Data de celebração do contrato (ISO 8601) |
| `external_id` | ID do contrato no BASE |
| `procedure_type` | Tipo de procedimento |
| `cpv` | Código CPV |
| `base_price` | Preço base do procedimento (€) |
| `effective_price` | Preço total efetivo (€) |
| `execution_days` | Prazo de execução em dias |
| `direct_award_justification` | Fundamentação do ajuste direto (se aplicável) |
| `competitors` | Concorrentes (se disponível) |

### Como ferramenta de linha de comandos

```
# Listar anos disponíveis
base-contratos --list-years

# Imprimir contratos como JSON (stdout)
base-contratos --nif 505279460

# Guardar em CSV
base-contratos --nif 505279460 --output contratos.csv

# Anos específicos, com cache local
base-contratos --nif 505279460 --year 2023 --year 2024 --cache-dir ~/.cache/base-contratos

# Múltiplas entidades, formato JSONL
base-contratos --nif 505279460 --nif 500754011 --format jsonl
```

## Como funciona

O conjunto de dados é publicado como um ficheiro XLSX por ano com todos os contratos do país. Esta biblioteca:

1. Obtém os metadados do conjunto de dados via API do dados.gov.pt para descobrir os URLs dos XLSX
2. Descarrega o XLSX de cada ano pretendido
3. Filtra as linhas em que o campo `adjudicante` contém o(s) NIF(s) pedido(s)
4. Devolve registos estruturados

Os ficheiros XLSX são grandes (dezenas de MB por ano). Use `cache_dir` para evitar re-descarregamentos em execuções repetidas.

## Como encontrar o NIF da sua entidade

Os NIFs dos municípios portugueses são públicos. Alguns exemplos:

| Município | NIF |
|---|---|
| Lousada | 505279460 |
| Porto | 500754011 |
| Lisboa | 500731076 |
| Braga | 500726760 |

## Licença

MIT. Os dados do dados.gov.pt são de domínio público.
