base-contratos 0.1.1

Obtém contratos públicos do conjunto de dados BASE/IMPIC em dados.gov.pt

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:

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.