Ingestão de Cotações da B3 via API Alpha Vantage

Introdução

O presente estudo tem como objetivo explorar o uso de APIs de séries temporais diárias para a extração, organização e análise de dados históricos do mercado financeiro, com ênfase em ativos brasileiros. A pesquisa possui caráter exploratório e educacional, buscando compreender o funcionamento de requisições a APIs financeiras, bem como o tratamento e a manipulação de séries temporais, contemplando informações como preços de abertura, máxima, mínima, fechamento e volume negociado.

Além disso, o projeto propõe a utilização de ferramentas de processamento de dados em larga escala e distribuído, visando otimizar a análise de grandes volumes de informações financeiras. Nesse contexto, são consideradas tecnologias como PySpark para programação distribuída em Python, o ecossistema Apache para processamento de dados, Apache Hadoop para armazenamento e gerenciamento de grandes conjuntos de dados, e Delta Lake para garantir confiabilidade, versionamento e consistência das tabelas de dados. A integração dessas ferramentas permite não apenas o tratamento eficiente de dados financeiros em grande escala, mas também a aplicação de análises avançadas e a geração de insights consistentes sobre o comportamento histórico dos ativos estudados.

Alpha Vantage:

Tradução livre:

Alpha Vantage fornece dados históricos e em tempo real do mercado financeiro por meio de um conjunto de APIs e planilhas de dados poderosas e fáceis de usar para desenvolvedores. De classes de ativos tradicionais (por exemplo, ações, ETFs, fundos mútuos) a indicadores econômicos, de taxas de câmbio a commodities, de dados fundamentais a indicadores técnicos, Alpha Vantage é o seu balcão único para dados de mercado global de nível empresarial fornecidos por meio de APIs baseadas em nuvem, servidores MCP, planilhas e muito mais.

A Alpha Vantage é uma provedora global de dados financeiros que disponibiliza informações de ações, ETFs, indicadores econômicos, câmbio e criptomoedas por meio de APIs baseadas em nuvem. Seu uso é amplamente difundido em aplicações acadêmicas e corporativas devido à facilidade de integração e ao plano gratuito para testes e estudos.

No site da Alpha Vantage nos fornece todas as informações:

• https://www.alphavantage.co/

Na documentação, dentro do site, nos mostra as APIS disponíveis para consumo de dados.

• https://www.alphavantage.co/documentation/

O que é uma API?

Uma API (Application Programming Interface), ou Interface de Programação de Aplicações, é um conjunto de regras e protocolos que permite que diferentes sistemas de software se comuniquem entre si.

Em termos mais simples, uma API funciona como uma ponte que permite que um programa “peça” informações ou serviços de outro programa ou serviço, sem precisar saber como ele foi implementado internamente.

Dessa forma, podemos extrair os dados através dela. Seguindo as ordem de parâmetros pré-estabelecidos. Cada API possui parâmetros diferentes.

Um programa envia uma requisição para a API. Exemplo: “Me dê o preço de fechamento da ação PETR4 ontem”.  A API recebe o pedido, processa a solicitação e consulta os dados internos. E retorna os dados solicitados, geralmente em um formato estruturado como JSON ou XML.

Tickers:

Tickers são códigos padronizados que identificam ativos financeiros negociados em bolsas de valores. No Brasil, esses códigos são definidos pela B3 e seguem um padrão composto por uma abreviação da empresa e um número que indica o tipo de ação, como ações ordinárias (3) ou preferenciais (4).

Para diferenciação global, provedores de dados utilizam sufixos de mercado, como .SA, que representa ativos negociados na B3. Sem ticker, sistemas eletrônicos não conseguiriam distinguir ativos de forma confiável.

O termo “ticker” vem do século XIX, muito antes de computadores. Existiam máquinas chamadas stock tickers e elas imprimiam cotações em fitas de papel e o som da máquina era um “tick tick tick”

Exemplo visual:

PETR 32.50 ↑

VALE 68.10 ↓

Cada empresa precisava de um código curto, pois o papel era estreito, a transmissão era lenta e o espaço e tempo eram críticos. Daí nasceu o ticker symbol. Hoje eles são essenciais para todo o mercado financeiro digital. Servem para consultar preços em tempo real, identificar ativos em APIs, executar ordens  de compra e venda, indexar dados históricos e integrar sistemas de bolsas, bancos e corretoras.

Sem ticker, não existe automação. Eles são definidos oficialmente pelas bolsas de valores, não inventados por programadores. No caso do Brasil a B3 é quem define e registra os tickers. Eles constam no site oficial da B3, corretoras, documentação de APIs financeiras e relatórios regulatórios (CVM)

Exemplo: Petrobras código oficial: PETR4

Aqui entra a lógica de padronização. A estrutura do ticker na B3 é normalmente: XXXXN

XXXX - Abreviação da empresa //  N-Tipo de ação

Exemplos:

VALE3    →  Vale ON

PETR4    →  Petrobras PN

BOVA11  →  ETF (Unit)

O .SA no final é do Alpha Vantage. Esse não é da B3, é do provedor de dados.

APIs globais precisam diferenciar VALE dos EUA, VALE do Brasil e VALE de outros mercados. Então usam sufixos de mercado:

Sufixo     Mercado

.SA             Brasil (São Paulo / B3)

.NY              NYSE

.L             Londres

.TO             Toronto

Portanto: PETR4.SA = Petrobras PN negociada na B3

Descoberta Automática de Tickers

O endpoint LISTING_STATUS da Alpha Vantage, poderia retornar a listagem global de ativos em formato CSV que seria ideal para extrair os tickers. A partir dessa listagem, os tickers da B3 poderiam ser filtrados pelo sufixo .SA e pelo status ativo, criando uma tabela de referência reutilizável. Mas a Alpha Vantage retorna apenas o cadastro oficial de ativos do mercado dos EUA, basicamente: NYSE, NASDAQ, AMEX.  Esse endpoint NÃO é um catálogo global. A Alpha Vantage usa provedores terceiros para dados internacionais. O cadastro oficial (LISTING_STATUS) é americano. E por que a Alpha Vantage faz assim? Por motivos de licenciamento, custos de cadastro global (eles evitam expor isso publicamente). Além disso, o cadastro oficial implica responsabilidade e a Time Series “sob demanda” é mais flexível.

Dessa forma, o LISTING_STATUS é para os EUA. Se o Time Series responde, o ativo “existe” independentemente do LISTING_STATUS. Por isso, em pipelines reais o LISTING_STATUS ,só para EUA e Internacional é uma lista externa controlada: B3, Yahoo Finance, B3 CSV e manutenção manual.

Os tickers oficiais (símbolos de negociação) de ações e outros ativos financeiros podem ser encontrados em fontes confiáveis e oficiais do mercado. Para ativos brasileiros, os principais lugares são:

B3 (Brasil, Bolsa, Balcão)

• Site oficial: https://www.b3.com.br

• A B3 fornece a lista completa de ativos negociados no mercado brasileiro, incluindo ações, ETFs, opções, fundos imobiliários e outros.

• Você pode consultar:

  • Ticker (código do ativo)

  • Nome da empresa

  • Segmento (Novo Mercado, Nível 1, Nível 2)

  • Categoria do ativo (ação ordinária, preferencial, etc.)

Exemplo: PETR4 → Petrobras PN, VALE3 → Vale ON

2. CVM (Comissão de Valores Mobiliários)

• Site oficial: https://www.gov.br/cvm/pt-br

• A CVM regula o mercado de capitais brasileiro e disponibiliza informações sobre companhias abertas e seus ativos negociados.

• Bom para validar a existência oficial de um ticker e dados regulatórios da empresa.

3. Plataformas financeiras e APIs

• Yahoo Finance Brasil: https://finance.yahoo.com/

  • Permite pesquisar por tickers de ações brasileiras e históricos de preços.

• Investing.com Brasil: https://br.investing.com/

  • Também fornece tickers oficiais e dados históricos.

• APIs financeiras (ex.: Alpha Vantage, Quandl, Yahoo Finance API, B3 API)

  • Algumas APIs exigem que você tenha os tickers corretos para obter os dados históricos.

Ambientes distribuidos:

O que é o Apache Hadoop? O Apache Hadoop é um framework para processamento distribuído de dados grandes. Seus componentes principais são:

HDFS (Hadoop Distributed File System) → sistema de arquivos distribuído, para armazenar dados em múltiplos nós.

YARN (Yet Another Resource Negotiator) → gerenciador de recursos do cluster.

MapReduce → modelo antigo de processamento distribuído (menos usado hoje).

Hoje o mais relevante para o Spark é o HDFS, porque o Spark lê/escreve dados em clusters distribuídos.

O que é o Apache Spark?

Apache Spark é um engine de processamento distribuído de dados projetado para alta velocidade e escalabilidade. É mais moderno e rápido que o Hadoop MapReduce, usando processamento em memória (in-memory) quando possível. Funciona em clusters distribuídos ou localmente (como você está usando). 

Dessa forma os dados são divididos em partições e processa em paralelo. Suportando vários formatos de dados. Possui uma API que aceita Python e SQL. Uma das características principais é a execução de dados apenas quando necessário, otimizando pipelines.

O uso do Spark no projeto:

O projeto envolve pipeline de dados financeiros:

1. Bronze: ingestão de dados JSON da API Alpha Vantage

2. Silver: transformação, limpeza e tipagem, escrita em Delta Lake

3. Gold: Aplica regras de negócio e cálculos financeiros avançados e gera tabelas derivadas, agregações e indicadores

O Spark é essencial porque:

• Permite processar grandes volumes de dados de forma eficiente.

• Com DataFrames, você pode fazer transformações como:

  • .withColumn() → adicionar ou converter colunas

  • .dropDuplicates() → remover duplicatas

  • .cast() → ajustar tipos de dados

• Suporta Delta Lake, permitindo merge incremental e versionamento.

• Trabalha em paralelo, mesmo em máquinas locais, otimizando performance.

O Apache Spark é o motor de processamento de qualquer pipeline. Ele lê, transforma e escreve dados de forma escalável, paralela e eficiente. Com o PySpark e Delta Lake, você consegue manter consistência, auditoria e performance, mesmo em datasets grandes, sem depender de loops em Python ou processamento manual.

Mesmo que você não rode MapReduce, o Apache Spark depende de bibliotecas do Hadoop para acessar sistemas de arquivos distribuídos. Assim, o Apache Spark usa o Hadoop FileSystem API internamente para a leitura e escrita de arquivos como csv,json,parquet e delta.

No ambiente local, o Spark pode trazer um “Hadoop local” embutido, que permite você rodar pipelines em Windows/Linux sem instalar Hadoop completo. Se você quiser rodar Spark em cluster real (YARN, HDFS) precisa do Hadoop instalado. Mas é necessário configuar as variáveis do ambiente dependendo do sistema operacional (SO). No Windows por exemplo, é necessário adicionar PATHS e instalar alguns arquivos necessários para utilização além do ambiente local. Para rodar um pipeline localmente não precisa instalar Hadoop mas para utilizar CLUSTERS para um projeto escalável. Quando pensar em Hadoop. Se o projeto crescer com milhões de 'tickers' por dia, arquivos enormes, é recomendasdo rodar Spark distribuído. Assim como 10 anos de dados históricos, o Delta Lake no HDFS + cluster Spark seria perfeito. Integrar com pipelines de dados corporativos é usar HDFS.

O que é PySpark:

PySpark é a API do Apache Spark para Python. Permite rodar processamento distribuído e paralelo usando Python, sem escrever Java/Scala. Internamente, PySpark usa Spark (JVM), mas você escreve código em Python. O PySpark faz todo o trabalho pesado de processamento.

Por que usar PySpark no seu projeto

1. Leitura e escrita eficiente de grandes dados

   • .read.parquet(), .write.format("delta")

   • Mesmo que hoje você tenha apenas alguns tickers, PySpark escala para milhões de linhas sem mudar o código.

2. Transformações distribuídas

   • .withColumn(), .dropDuplicates(), .cast() → são aplicadas paralelamente em todas as partições do DataFrame.

   • Sem PySpark, você precisaria iterar em Pandas, o que não escala.

3. Integração nativa com Delta Lake

   • Merge incremental, time travel, versionamento, userMetadata → tudo funciona através do PySpark.

   • PySpark fornece a API para manipular Delta Tables (DeltaTable.forPath, .merge(), .history()).

4. Particionamento e otimização de I/O

   • .partitionBy("ticker") → PySpark escreve arquivos separados para cada ticker, facilitando queries rápidas e atualização parcial.

   • Isso é crítico para pipelines financeiros com histórico grande.

5. Auditoria e rastreabilidade

• withColumn("ingestion_silver_ts", current_timestamp())

• PySpark permite adicionar colunas de auditoria de forma paralela e eficiente

Benefícios do PySpark para o seu projeto

Com o processamento distribuido com PySpark, podemos escalar de 5 tickers para 500 ou  milhões. O PySpark é a espinha dorsal do pipeline Silver. Ele faz o trabalho pesado de: ler, transformar, particionar e escrever os dados em Delta Lake, garantindo performance, escalabilidade e rastreabilidade, sem você precisar mudar código quando os dados crescerem.

O que é o Delta Lake?

Delta Lake é uma camada de armazenamento open-source construída sobre o Apache Spark e Parquet. Ele transforma arquivos Parquet “simples” em uma tabela transacional confiável.

Os principais recursos que podemos considearar são:

ACID Transactions : garante qge suas operações de leitura e escrita são consistentes.

Time Travel : você pode consultar versões antigas da tabela.

Schema Enforcement : impede que dados inválidos ou fora do padrão sejam gravados.

Merge / Upsert :permite atualizar linhas existentes e inserir novas (MERGE INTO).

Auditabilidade : cada operação deixa um registro no transaction log.

Transaction Log (_delta_log) : histórico de operações, versionamento e metadata.

Por que usar Delta Lake no projeto?

O pipeline da camada Bronze para a camada Silver envolve:

1. Dados brutos da API da Alpha Vantage → JSON (Bronze)

2. Transformação, limpeza e tipagem → DataFrame Silver

3. Escrita particionada por ticker → Delta Lake

Dessa forma, os recursos que o Delta Lake possui são:

Recurso Delta Lake	Por que importa no seu projeto
ACID Transactions	Garante que merges incrementais não corrompam a tabela Silver
Merge / Upsert	Atualiza apenas os tickers que mudaram, sem reescrever tudo
Versionamento / Time Travel	Permite auditar alterações ou voltar a uma versão antiga
Particionamento	Facilita leitura e escrita rápida de tickers individuais
User Metadata (userMetadata)	Permite registrar cada execução do pipeline (timestamp, merge, run_id opcional)

 Delta Lake é de grande importância na camada Silver, garantindo consistência, rastreabilidade e performance do pipeline, sem precisar reescrever arquivos manualmente.

Stack usada no projeto

Componente	Função no projeto
VSCode	IDE para escrever, testar e debugar Python + PySpark
Conda environment	Gerenciamento de pacotes, dependências isoladas, múltiplos ambientes
PySpark	Executa Spark em máquina local, processa dados Bronze → Silver
Delta Lake	Armazena Silver com versionamento, Merge, ACID, time travel
Arquivos locais	JSON da Bronze, Delta Lake na pasta delta/silver/

 Databricks

Databricks é uma plataforma de dados na nuvem criada pelos desenvolvedores do Apache Spark.

É projetada para processamento distribuído, análise e pipelines de dados, integrando Spark, Delta Lake e Machine Learning. O Databricks é um ambiente cloud gerenciado para Spark + Delta Lake, que facilita análise de dados em grande escala, colaboração e pipelines distribuídos, sem se preocupar com configuração de clusters.

O uso do ambiente local x Databricks Free Edition

Databricks Free Edition possui vantangens como cluster spark pré-configurado, com Delta Lake nativo, interface web, notebooks integrados. mas escalabilidade limitada (cluster pequeno, poucos nós). Além disso, não permite criar múltiplos workers / recursos grandes. A memória limitada dificil processar datasets grandes ou históricos longos. E principalmente não dá total controle sobre arquivos locais sendo necessário subir tudo para DBFS. De maneira resumida , alguns recursos de administração, como instalação de pacotes custom, podem ser restritos, as sessões expiram, trabalhos longos podem ser interrompidos, e o free edition possui as limitações de escalabilidade, armazenamento e execução

VSCode + PySpark

Com o ambiente local temos c

ontrole total sobre ambiente Python, pacotes e versões. Podemmos usar arquivos locais, Delta Lake local, JSONs brutos sem subir nada para cloud. Debugs completos no VSCode como breakpoints, inspeção de DataFrames. O Pipeline pode ser versionado via Git normalmente e a escala até a capacidade da sua máquina (memória, CPU). Possui flexível para testar scripts, funções e merges. Mas o processamento pode ser limitado pela máquina local sendo suficiente para testes e dados de cotação (~milhares de tickers).

Por que o ambiente local é melhor para esse projeto

1. Controle completo sobre os arquivos Delta

   • Você escreve diretamente em delta/silver/...

   • Pode inspecionar _delta_log, rodar history(), ver particionamento

   • No Databricks Community, você precisaria subir tudo para DBFS → mais burocracia

2. Flexibilidade para depuração

   • No VSCode, pode rodar células, testar funções transform, verificar tipos de colunas

   • Databricks Free tem interface limitada e não permite debug avançado

3. Não depende de limitações de conta gratuita

   • Sem limite de sessão ou cluster expirando

   • Pode usar pacotes custom (python-dotenv, PyYAML, etc.) livremente

4. Controle sobre versões

   • Pode definir versões exatas de PySpark, Delta Lake, Pandas, etc.

   • No Databricks Free, você depende do runtime que eles oferecem → menos controle sobre compatibilidade

5. Auditabilidade local

   • Pode salvar logs, merges, snapshots, Delta History localmente

   • Mantém controle completo do seu pipeline Silver, sem depender de cloud

Quando ainda faria sentido usar Databricks

• Se você precisar processar milhões de tickers ou anos de histórico, e sua máquina local não aguentar

• Se quiser integração cloud, colaboração em notebooks, com clusters de verdade

• Para projetos corporativos ou produção em escala, onde clusters Spark são necessários

Para esse projeto (dados financeiros da Alpha Vantage, pipeline Bronze - Silver), o setup local é mais rápido, flexível e auditável, sem as limitações do Databricks Free Edition.

O projeto segue essa estrutura de acordo com o diagrama:

O link para acessar o projeto está logo abaixo. Lembrando que as consultas, dataframes e outros arquivos somente poderão ser acessados e visualizados após a execução dos pipelines.

https://github.com/userdanixdev/project_cotacoes_sa