base-contratos

Obtém contratos públicos do conjunto de dados BASE/IMPIC 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

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:

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:

Licença

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