Um tutorial de primeiros passos para acessar a execução orçamentária do município usando Python e a biblioteca de análise de dados Pandas *
A API Console é uma interface que permite testar as diferentes consultas e obter a URL com os parâmetros desejados. Por exemplo, se deseja obter todos os contratos da Secretaria de Educação em 2017, basta entrar no item /consultaContrato e informar "2017" no campo anoContrato e "16" (código da Educação) no campo codOrgao. A URL resultante dessa consulta é https://gatewayapi.prodam.sp.gov.br:443/financas/orcamento/sof/v2.1.0/consultaContrato?anoContrato=2017&codOrgao=16
Este é o script que consulta a API (para qualquer URL gerada acima) e transforma o arquivo obtido em formato json para um Data Frame do Pandas, a partir do qual será possível fazer as análises. Substitua a constante TOKEN pelo seu código de assinatura!
In [168]:
import pandas as pd
import requests
import json
import numpy as np
In [169]:
TOKEN = '198f959a5f39a1c441c7c863423264'
base_url = "https://gatewayapi.prodam.sp.gov.br:443/financas/orcamento/sof/v2.1.0"
headers={'Authorization' : str('Bearer ' + TOKEN)}
In [170]:
url_orcado = '{base_url}/consultarDespesas?anoDotacao=2017&mesDotacao=08&codOrgao=84'.format(base_url=base_url)
In [171]:
request_orcado = requests.get(url_orcado,
headers=headers,
verify=True).json()
In [172]:
df_orcado = pd.DataFrame(request_orcado['lstDespesas'])
In [173]:
df_resumo_orcado = df_orcado[['valOrcadoInicial', 'valOrcadoAtualizado', 'valCongelado', 'valDisponivel', 'valEmpenhadoLiquido', 'valLiquidado']]
In [174]:
df_resumo_orcado
Out[174]:
Empenho é o ato em que autoridade verifica a existência do crédito orçamentário e autoriza a execução da despesa (por exemplo, para realizar uma licitação). A partir daí, os valores vão sendo liquidados e pagos conforme a execução de um contrato. Vamos ver quanto a Secretaria Municipal de Saúde empenhou de seu orçamento em 2017.
In [175]:
url_empenho = '{base_url}/consultaEmpenhos?anoEmpenho=2017&mesEmpenho=08&codOrgao=84'.format(base_url=base_url)
pagination = '&numPagina={PAGE}'
In [176]:
request_empenhos = requests.get(url_empenho,
headers=headers,
verify=True).json()
A API fornece apenas uma página na consulta. O script abaixo checa a quantidade de páginas nos metadados da consulta e itera o número de vezes necessário para obter todas as páginas:
In [177]:
number_of_pages = request_empenhos['metadados']['qtdPaginas']
todos_empenhos = []
todos_empenhos = todos_empenhos + request_empenhos['lstEmpenhos']
if number_of_pages>1:
for p in range(2, number_of_pages+1):
request_empenhos = requests.get(url_empenho + pagination.format(PAGE=p), headers=headers, verify=True).json()
todos_empenhos = todos_empenhos + request_empenhos['lstEmpenhos']
In [178]:
df_empenhos = pd.DataFrame(todos_empenhos)
Com os passos acima, fizemos a requisição de todas as páginas e convertemos o arquivo formato json em um DataFrame. Agora podemos trabalhar com a análise desses dado no Pandas. Para checar quantos registros existentes, vamos ver o final da lista:
In [179]:
df_empenhos.tail()
Out[179]:
In [181]:
modalidades = df_empenhos.groupby('txtModalidadeAplicacao')['valTotalEmpenhado', 'valLiquidado'].sum()
In [182]:
modalidades
Out[182]:
In [183]:
# Outra maneira de fazer a mesma operação:
#pd.pivot_table(df_empenhos, values='valTotalEmpenhado', index=['txtModalidadeAplicacao'], aggfunc=np.sum)
In [184]:
despesas = pd.pivot_table(df_empenhos,
values=['valLiquidado', 'valPagoExercicio'],
index=['numCpfCnpj', 'txtRazaoSocial', 'txtDescricaoPrograma'],
aggfunc=np.sum).sort_values('valPagoExercicio', axis=0, ascending=False, inplace=False, kind='quicksort', na_position='last')
In [185]:
despesas.head(15)
Out[185]:
In [186]:
fonte = pd.pivot_table(df_empenhos,
values=['valLiquidado', 'valPagoExercicio'],
index=['txtDescricaoFonteRecurso'],
aggfunc=np.sum).sort_values('valPagoExercicio', axis=0, ascending=False, inplace=False, kind='quicksort', na_position='last')
In [187]:
fonte
Out[187]:
O objetivo deste tutorial não era fazer uma análise exaustiva da base, mas apenas mostrar o que é possível a partir do consumo da API. Você também pode salvar toda a base de empenhos num arquivo .csv e trabalhar no seu Excel (super te entendo). O Pandas também ajuda nisso! Assim:
In [167]:
df_empenhos.to_csv('empenhos.csv')
Pronto, seu arquivo está lá salvo no mesmo diretório deste jupyter notebook!
Esse foi um panorama. Aos poucos -- e à medida que eu for aprendendo e o tempo permitir, também -- vou explorando outras formas de consulta, análise e visualização.
*Escrito por Fernanda Campagnucci. Agradecimentos especiais ao Fernando Paiva, pelas dicas de código para consumo da API, e aos colegas Eduardo Paiva e Marcelo Cabral, também gestores públicos entusiastas dos dados e do software livre, com quem venho aprendendo bastante