HG Finance Documentação

API de dados financeiros

Documentação

Índice

Introdução
Autenticação e chave
Obtendo contações de moedas, índices dos mercados, criptomoedas e taxas
Obtendo o preço de ações ou FIIs listados no IBOVESPA
Obtendo as ações com as maiores altas ou baixas no IBOVESPA
Obtendo os dividendos de Ações, Fundos Imobiliários e BDRs NOVO!
Índice Bovespa daily detalhado NOVO!
Formatos de retorno
Obter todos os dados em uma só requisição
Obter somente cotações de moedas e bolsas
Obter somente taxas CDI e SELIC
Obtendo dados históricos
Obtendo dados históricos de ações e FIIs NOVO!
Personalizando a resposta
Dicas de boas práticas

Introdução

O HG Finance é uma API que fornece dados da bolsa de valores brasileira B3, preço de ações, dividendos, indices, cotação do dólar e várias outras moedas.
API fácil de implementar, desde 2009 no mercado, simples de implementar, com bibliotecas em PHP, Ruby e JavaScript. (em breve)

Mesmo que sua aplicação não seja com essas linguagens, abaixo você pode conferir como integrar a API.
Todos esses dados são retornados na mesma requisição de uma só vez, sendo esses dados:

Em uma só requisição, você pode obter:
- as posições dos principais índices como IBOVESPA, IFIX, NASDAQ, Dow Jones, CAC 40 e NIKKEI;
- a cotação de diversas moedas em relação ao real como Dólar (USD), Euro (EUR), Libra (GBP), Peso (ARS), Dólar Canadense (CAD), Dólar Australiano (AUD), Iene do Japão (JPY), Renminbi da China (CNY) e Bitcoin (BTC);
- cotação do bitcoin nas principais exchanges como Coinbase, Blockchain.info, BitStamp, FoxBit e Mercado Bitcoin;
- as principais taxas de juros do Brasil como CDI e Selic.

Tudo isso em uma só requisição.

Recomendamos que sempre use sua chave, algumas informações só estão disponíveis com o uso da chave.

Criar nova chave

Todas as requisições em como base o seguinte endpoint:

https://api.hgbrasil.com/finance

Estrutura de dados

Os dados referentes à consulta chegam no parâmetro results, você também pode conferir a autenticação de sua chave no parâmetro de retorno valid_key.

currencies - cotação das moedas
- source - moeda base de cotação
- ISO da moeda
  - name - nome da moeda
  - buy - valor para compra
  - sell - valor para venda (não disponível para algumas moedas)
  - variation - variação em percentual referente à última hora útil anterior
stocks - posições dos principais mercados
- índice
  - name - nome do índice
  - location - localização do mercado
  - points - pontos (somente IBOVESPA)
  - variation - variação em percentual referente à última hora útil anterior
bitcoin - cotação nas principais corretoras
- corretora
  - name - nome do índice
  - format - array, moeda base de câmbio
    - 0 - ISO da moeda
    - 1 - idioma da moeda
  - last - última posição
  - buy - valor para compra (pode não estar disponível)
  - sell - valor para venda (pode não estar disponível)
  - variation - variação em percentual referente à última hora útil anterior
taxes - taxas de juros do Brasil
- date - data de referência
- cdi - taxa CDI em percentual
- selic - taxa Selic em percentual
- daily_factor - fator diário
- selic_daily - taxa Selic diária em percentual
- cdi_daily - taxa CDI diária em percentual

Você pode personalizar o resultado da consulta omitindo alguns dados veja como.

Exemplo de resposta JSON

{"by":"default","valid_key":true,"results":{"currencies":{"source":"BRL","USD":{"name":"Dollar","buy":6.0621,"sell":6.0621,"variation":1.124},"EUR":{"name":"Euro","buy":6.3656,"sell":6.3654,"variation":1.512},"GBP":{"name":"Pound Sterling","buy":7.6547,"sell":null,"variation":0.689},"ARS":{"name":"Argentine Peso","buy":0.006,"sell":null,"variation":0.965},"CAD":{"name":"Canadian Dollar","buy":4.2592,"sell":null,"variation":0.948},"AUD":{"name":"Australian Dollar","buy":3.8547,"sell":null,"variation":0.938},"JPY":{"name":"Japanese Yen","buy":0.0395,"sell":null,"variation":0.415},"CNY":{"name":"Renminbi","buy":0.833,"sell":null,"variation":0.909},"BTC":{"name":"Bitcoin","buy":644529.111,"sell":644529.111,"variation":0.213}},"stocks":{"IBOVESPA":{"name":"BM\u0026F BOVESPA","location":"Sao Paulo, Brazil","points":125546.33,"variation":-0.39},"IFIX":{"name":"Índice de Fundos de Investimentos Imobiliários B3","location":"Sao Paulo, Brazil","points":2972.84,"variation":0.87},"NASDAQ":{"name":"NASDAQ Stock Market","location":"New York City, United States","points":19829.81,"variation":-0.37},"DOWJONES":{"name":"Dow Jones Industrial Average","location":"New York City, United States","points":43907.33,"variation":-0.02},"CAC":{"name":"CAC 40","location":"Paris, French","points":7390.66,"variation":-0.41},"NIKKEI":{"name":"Nikkei 225","location":"Tokyo, Japan","points":39470.44,"variation":-0.95}},"available_sources":["BRL"],"bitcoin":{"blockchain_info":{"name":"Blockchain.info","format":["USD","en_US"],"last":100302.92,"buy":100302.92,"sell":100302.92,"variation":0.213},"coinbase":{"name":"Coinbase","format":["USD","en_US"],"last":56019.33,"variation":2.506},"bitstamp":{"name":"BitStamp","format":["USD","en_US"],"last":100295.0,"buy":100375.0,"sell":100374.0,"variation":0.277},"foxbit":{"name":"FoxBit","format":["BRL","pt_BR"],"last":608429.2256,"variation":1.032},"mercadobitcoin":{"name":"Mercado Bitcoin","format":["BRL","pt_BR"],"last":608500.0,"buy":608508.03384843,"sell":609063.16192749,"variation":1.041}},"taxes":[{"date":"2024-12-11","cdi":11.25,"selic":11.25,"daily_factor":1.00041957,"selic_daily":11.15,"cdi_daily":11.15}]},"execution_time":0.0,"from_cache":true}

Autenticação e chave

A autenticação exigida para o uso da API é super simples.
Basta você fazer o registro de sua chave aqui, e informar via parâmetro em suas consultas.

Recomendamos que sempre utilize uma chave, seus limites de consulta serão maiores, e mais recursos serão habilitados.
Você pode consultar os limites neste link.

Sua chave deve ser informada em toda requisição, utilizando o parâmetro key.

https://api.hgbrasil.com/finance?key=SUA-CHAVE

Obtendo o preço de Ações, BDRs e FIIs listados no IBOVESPA

API gratuita para obter preço de ações na bolsa de valores BOVESPA!

Novidade!

Consulte também Fundos Imobiliários e BDRs!

Com esse endpoint você pode obter o preço de uma ação listada no IBOVESPA através do símbolo desse título.
Atenção! É necessário ser membro à partir do plano Member Premium para realizar essa consulta.
Planos acima oferencem um maior número de títulos ao mesmo tempo, confira aqui nossos planos.

Delay:
API para fins informativos, os dados podem estar atrasados entre 15 minutos e 1 hora.
É possível conferir o horário de atualização do dado no updated_at.

Títulos disponíveis: veja a lista.

Requer chave: sim
Requer plano: sim, plano Member Premium ou superior

Os dados são obtidos a partir do símbolo de uma empresa (veja a lista), através do parâmetro symbol.

https://api.hgbrasil.com/finance/stock_price?key=SUA-CHAVE&symbol=embr3

Nos planos Professional ou Enterprise é possível obter vários símbolos nas mesma consulta, separando por vírgula.

https://api.hgbrasil.com/finance/stock_price?key=SUA-CHAVE&symbol=embr3,hglg11,itsa4

Estrutura de dados

Os dados referentes à consulta chegam no parâmetro results, você também pode conferir a autenticação de sua chave no parâmetro de retorno valid_key.

kind - tipo do título
- stock - ação
- fii - fundo imobiliário
symbol - símbolo / ticker da ação
name - nome da empresa
company_name - razão social
document - documento / CNPJ da empresa
description - descrição da empresa
website - sita da empresa / relação com investidores
sector - setor de atuação da empresa ou fundo
financials
- equity - valor patrimonial (somente FIIs)
- quota_count - cotas emitidas (FIIs / ordinária / preferencial)
- equity_per_share - valor patrimonial por cota (somente FIIs)
- price_to_book_ratio - preço sobre valor patrimonial
- dividends - informações sobre dividendos
  - yield_12m - percentual yield últ. 12 meses
  - yield_12m_sum - soma últ. 12 meses em reais
region - região de operação da bolsa
currency - moeda base
market_time - horário de negociação
- open - horário de abertura
- close - horário de fechamento
- timezone - fuso horário
logo - logotipo da empresa
- small - URL para imagem em PNG 256 x 256
- big - URL para imagem em PNG 1.280 x 1.280
market_cap - valor de mercado (em milhões)
price - preço por ação
change_percent - percentual de mudança do dia
change_price - variação do dia em valor
updated_at - última atualização

Atenção! Exoneração de responsabilidade

Exemplo de resposta JSON

{"by":"symbol","valid_key":true,"results":{"EMBR3":{"kind":"stock","symbol":"EMBR3","name":"Embraer","company_name":"Embraer S.A.","document":"07.689.002/0001-89","description":"Projeto. Desenvolvimento. Fabricação. Comercialização de Aeronaves E Sistemas E Fornecimento de Suporte E Serviços de Pós-venda.","website":"http://www.embraer.com.br/","sector":"Bens Industriais / Material de Transporte / Material Aeronáutico e de Defesa","financials":{"quota_count":740465044,"dividends":{"yield_12m":0.0,"yield_12m_sum":0.0}},"region":"Brazil/Sao Paulo","currency":"BRL","market_time":{"open":"10:00","close":"17:30","timezone":-3},"logo":{"small":"https://assets.hgbrasil.com/finance/companies/small/embraer.png","big":"https://assets.hgbrasil.com/finance/companies/big/embraer.png"},"market_cap":6784.16,"price":55.24,"change_percent":0.0,"change_price":0.0,"updated_at":"2024-12-13 13:05:57"},"HGLG11":{"kind":"fii","symbol":"HGLG11","name":"FII HGLG Pax","company_name":"Pátria Log Fundo Investimento Imobiliário Responsabilidade Ltda","document":"11.728.688/0001-47","description":"Financeiro e Outros/Fundos/Fundos Imobiliários","website":"https://www.bancogenial.com/","sector":"Imóveis Industriais e Logísticos","financials":{"equity":5299488783,"quota_count":33787575,"equity_per_share":156.847,"price_to_book_ratio":0.953,"dividends":{"yield_12m":8.832,"yield_12m_sum":13.2}},"region":"Brazil/Sao Paulo","currency":"BRL","market_time":{"open":"10:00","close":"17:30","timezone":-3},"logo":null,"market_cap":5122.87,"price":151.62,"change_percent":1.45,"change_price":2.17,"updated_at":"2024-12-13 13:10:52"},"ITSA4":{"kind":"stock","symbol":"ITSA4","name":"Itaúsa","company_name":"ItauSA S.A.","document":"61.532.644/0001-15","description":"Gestão de Participações Societárias (holding)","website":"http://www.itausa.com.br/","sector":"Financeiro / Intermediários Financeiros / Bancos","financials":{"quota_count":7117789547,"dividends":{"yield_12m":6.685,"yield_12m_sum":0.615}},"region":"Brazil/Sao Paulo","currency":"BRL","market_time":{"open":"10:00","close":"17:30","timezone":-3},"logo":{"small":"https://assets.hgbrasil.com/finance/companies/small/itausa.png","big":"https://assets.hgbrasil.com/finance/companies/big/itausa.png"},"market_cap":101062.0,"price":9.21,"change_percent":0.11,"change_price":0.01,"updated_at":"2024-12-13 13:05:57"}},"execution_time":0.02,"from_cache":false}

Obtendo as ações com as maiores altas ou baixas no IBOVESPA

Com esse endpoint você pode obter a lista de títulos que estão em maiores altas ou baixas.
Atenção! É necessário ser membro à partir do plano Professional para realizar essa consulta.
Planos acima oferencem um maior número de títulos ao mesmo tempo, confira aqui nossos planos.

Conheça nossos planos

Delay:
API para fins informativos, os dados podem estar atrasados entre 15 minutos e 1 hora.
É possível conferir o horário de atualização do dado no updated_at.

Títulos disponíveis: veja a lista.

Requer chave: sim
Requer plano: sim, plano Professional ou superior

A lista é gerada apenas com os símbolo que fazem estão em nossa plataforma, veja a lista aqui.

Para obter as maiores altas, informe no parâmetro symbol a opção get-high, exemplo:

https://api.hgbrasil.com/finance/stock_price?key=SUA-CHAVE&symbol=get-high

E para obter as maiores baixas, informe no parâmetro symbol a opção get-low, exemplo:

https://api.hgbrasil.com/finance/stock_price?key=SUA-CHAVE&symbol=get-low

A estrutura de dados é a mesma para o retorno de títulos do IBOVESPA.

Atenção! Exoneração de responsabilidade

Exemplo de resposta JSON

{"by":"get_high_symbols","valid_key":true,"results":{"MRFG3":{"kind":"stock","symbol":"MRFG3","name":"Marfrig","company_name":"Marfrig Global Foods S.A.","document":"03.853.896/0001-40","description":"Produção E Distribuição de Alimentos à Base de Carne Bovina. Suína. Ovina E Avícola. In Natura. Elaborados E Processados. Couros Semi-terminados E Terminados. Além de Outros Produtos Alimentícios.","website":"http://www.marfrig.com.br/","sector":"Consumo não Cíclico / Alimentos Processados / Carnes e Derivados","financials":{"quota_count":886000000,"dividends":{"yield_12m":0.0,"yield_12m_sum":0.0}},"region":"Brazil/Sao Paulo","currency":"BRL","market_time":{"open":"10:00","close":"17:30","timezone":-3},"logo":{"small":"https://assets.hgbrasil.com/finance/companies/small/marfrig.png","big":"https://assets.hgbrasil.com/finance/companies/big/marfrig.png"},"market_cap":15310.1,"price":17.28,"change_percent":22.19,"change_price":3.14,"updated_at":"2024-12-13 13:05:57"},"PCAR3":{"kind":"stock","symbol":"PCAR3","name":"GPA","company_name":"Cia Brasileira De Distribuicao","document":"47.508.411/0001-56","description":"Comércio Varejista","website":"http://www.gpari.com.br/","sector":"Consumo não Cíclico / Comércio e Distribuição / Alimentos","financials":{"quota_count":490197963,"dividends":{"yield_12m":0.0,"yield_12m_sum":0.0}},"region":"Brazil/Sao Paulo","currency":"BRL","market_time":{"open":"10:00","close":"17:30","timezone":-3},"logo":{"small":"https://assets.hgbrasil.com/finance/companies/small/p-acucar-cbd.png","big":"https://assets.hgbrasil.com/finance/companies/big/p-acucar-cbd.png"},"market_cap":1205.89,"price":2.46,"change_percent":8.85,"change_price":0.2,"updated_at":"2024-12-13 13:05:57"},"JBSS3":{"kind":"stock","symbol":"JBSS3","name":"JBS","company_name":"Jbs S.A.","document":"02.916.265/0001-60","description":"","website":"http://www.jbs.com.br/","sector":"Consumo não Cíclico / Alimentos Processados / Carnes e Derivados","financials":{"quota_count":2218116370,"dividends":{"yield_12m":5.115,"yield_12m_sum":2.0}},"region":"Brazil/Sao Paulo","currency":"BRL","market_time":{"open":"10:00","close":"17:30","timezone":-3},"logo":{"small":"https://assets.hgbrasil.com/finance/companies/small/jbs.png","big":"https://assets.hgbrasil.com/finance/companies/big/jbs.png"},"market_cap":87393.8,"price":39.4,"change_percent":3.66,"change_price":1.39,"updated_at":"2024-12-13 13:05:57"},"BEEF3":{"kind":"stock","symbol":"BEEF3","name":"Minerva","company_name":"Minerva S.A.","document":"67.620.377/0001-14","description":"Líder Na América Do Sul Na Exportação de Carne Bovina In Natura E Seus Derivados. E Que Atua Também No Segmento de Processados.","website":"http://www.minervafoods.com/ri/","sector":"Consumo não Cíclico / Alimentos Processados / Carnes e Derivados","financials":{"quota_count":607283407,"dividends":{"yield_12m":0.0,"yield_12m_sum":0.0}},"region":"Brazil/Sao Paulo","currency":"BRL","market_time":{"open":"10:00","close":"17:30","timezone":-3},"logo":{"small":"https://assets.hgbrasil.com/finance/companies/small/minerva.png","big":"https://assets.hgbrasil.com/finance/companies/big/minerva.png"},"market_cap":3497.95,"price":5.76,"change_percent":2.13,"change_price":0.12,"updated_at":"2024-12-13 13:05:57"},"LREN3":{"kind":"stock","symbol":"LREN3","name":"Lojas Renner","company_name":"Lojas Renner S.A.","document":"92.754.738/0001-62","description":"Loja de Departamentos (comércio Varejista)","website":"http://www.lojasrenner.com.br/","sector":"Consumo Cíclico / Comércio / Tecidos. Vestuário e Calçados","financials":{"quota_count":1059549692,"dividends":{"yield_12m":4.73,"yield_12m_sum":0.647}},"region":"Brazil/Sao Paulo","currency":"BRL","market_time":{"open":"10:00","close":"17:30","timezone":-3},"logo":{"small":"https://assets.hgbrasil.com/finance/companies/small/lojas-renner.png","big":"https://assets.hgbrasil.com/finance/companies/big/lojas-renner.png"},"market_cap":14738.3,"price":13.91,"change_percent":1.68,"change_price":0.23,"updated_at":"2024-12-13 13:05:57"},"B3SA3":{"kind":"stock","symbol":"B3SA3","name":"B3","company_name":"B3 S.A. - Brasil. Bolsa. Balcão.","document":"09.346.601/0001-25","description":"Principais Atividades: Administrar Mercados Organizados de Títulos E Valores Mobiliários; Prestar Serviços de Registro. Compensação E Liquidação E de Suporte à Operações de Financiamento","website":"http://www.b3.com.br/","sector":"Financeiro / Serviços Financeiros Diversos / Serviços Financeiros Diversos","financials":{"quota_count":0,"dividends":{"yield_12m":0.0,"yield_12m_sum":0.0}},"region":"Brazil/Sao Paulo","currency":"BRL","market_time":{"open":"10:00","close":"17:30","timezone":-3},"logo":{"small":"https://assets.hgbrasil.com/finance/companies/small/b3.png","big":"https://assets.hgbrasil.com/finance/companies/big/b3.png"},"market_cap":56652.7,"price":10.44,"change_percent":1.56,"change_price":0.16,"updated_at":"2024-12-13 13:05:57"},"SLCE3":{"kind":"stock","symbol":"SLCE3","name":"SLC Agrícola","company_name":"Slc Agricola S.A.","document":"89.096.457/0001-55","description":"Produção E Comercialização de Algodão. Soja. Milho. Entre Outros.","website":"http://www.slcagricola.com.br/","sector":"Consumo não Cíclico / Agropecuária / Agricultura","financials":{"quota_count":443329716,"dividends":{"yield_12m":4.289,"yield_12m_sum":0.83}},"region":"Brazil/Sao Paulo","currency":"BRL","market_time":{"open":"10:00","close":"17:30","timezone":-3},"logo":{"small":"https://assets.hgbrasil.com/finance/companies/small/slc-agricola.png","big":"https://assets.hgbrasil.com/finance/companies/big/slc-agricola.png"},"market_cap":8565.13,"price":19.3,"change_percent":1.53,"change_price":0.29,"updated_at":"2024-12-13 13:05:57"},"PETZ3":{"kind":"stock","symbol":"PETZ3","name":"Petz","company_name":"Pet Center Comercio E Participacoes S.A.","document":"18.328.118/0001-09","description":"Importação. Exportação E Comércio (inclusive Via Internet E-commerce) de Artigos Para Animais. Plantas. Flores. Sementes; Hospital Veterinário. Consultório. Clínica Veterinária. Banho/tosa E Hotel.","website":"http://www.petz.com.br/","sector":"Consumo Cíclico / Comércio / Produtos Diversos","financials":{"quota_count":462523502,"dividends":{"yield_12m":7.544,"yield_12m_sum":0.298}},"region":"Brazil/Sao Paulo","currency":"BRL","market_time":{"open":"10:00","close":"17:30","timezone":-3},"logo":{"small":"https://assets.hgbrasil.com/finance/companies/small/petz.png","big":"https://assets.hgbrasil.com/finance/companies/big/petz.png"},"market_cap":1831.59,"price":3.95,"change_percent":1.28,"change_price":0.05,"updated_at":"2024-12-13 13:05:57"},"CXSE3":{"kind":"stock","symbol":"CXSE3","name":"Caixa Seguridade","company_name":"Caixa Seguridade Participações S.A.","document":"22.543.331/0001-00","description":"Participar. Direta Ou Indiretamente. Do Capital de Outras Sociedades Relacionadas A Seguridade E Corretagem de Seguros.","website":null,"sector":"Financeiro / Previdência e Seguros / Seguradoras","financials":{"quota_count":3000000000,"dividends":{"yield_12m":6.762,"yield_12m_sum":1.065}},"region":"Brazil/Sao Paulo","currency":"BRL","market_time":{"open":"10:00","close":"17:30","timezone":-3},"logo":{"small":"https://assets.hgbrasil.com/finance/companies/small/caixa-seguridade.png","big":"https://assets.hgbrasil.com/finance/companies/big/caixa-seguridade.png"},"market_cap":47760.0,"price":15.92,"change_percent":1.08,"change_price":0.17,"updated_at":"2024-12-13 13:05:57"},"ABEV3":{"kind":"stock","symbol":"ABEV3","name":"Ambev","company_name":"Ambev S.A.","document":"07.526.557/0001-00","description":"Fabricação E Distribuição de Cervejas. Refrigerantes E Bebidas Não Carbonatadas E Não Alcoólicas.","website":"http://ri.ambev.com.br","sector":"Consumo não Cíclico / Bebidas / Cervejas e Refrigerantes","financials":{"quota_count":15757657336,"dividends":{"yield_12m":5.573,"yield_12m_sum":0.73}},"region":"Brazil/Sao Paulo","currency":"BRL","market_time":{"open":"10:00","close":"17:30","timezone":-3},"logo":{"small":"https://assets.hgbrasil.com/finance/companies/small/ambev-s-a.png","big":"https://assets.hgbrasil.com/finance/companies/big/ambev-s-a.png"},"market_cap":34374.0,"price":13.23,"change_percent":0.99,"change_price":0.13,"updated_at":"2024-12-13 13:05:57"},"WEGE3":{"kind":"stock","symbol":"WEGE3","name":"WEG","company_name":"Weg S.A.","document":"84.429.695/0001-11","description":"A Weg Sa É Uma Sociedade de Participação Não Operacional (holding) E\ntambém Sociedade de Comando Do Grupo Weg.","website":"http://www.weg.net/br/","sector":"Bens Industriais / Máquinas e Equipamentos / Motores . Compressores e Outros","financials":{"quota_count":4197317998,"dividends":{"yield_12m":1.173,"yield_12m_sum":0.678}},"region":"Brazil/Sao Paulo","currency":"BRL","market_time":{"open":"10:00","close":"17:30","timezone":-3},"logo":{"small":"https://assets.hgbrasil.com/finance/companies/small/weg.png","big":"https://assets.hgbrasil.com/finance/companies/big/weg.png"},"market_cap":244788.0,"price":58.32,"change_percent":0.9,"change_price":0.52,"updated_at":"2024-12-13 13:05:57"},"BRFS3":{"kind":"stock","symbol":"BRFS3","name":"BRF","company_name":"Brf S.A.","document":"01.838.723/0001-27","description":"Holding Operacional","website":"http://www.brf-br.com/","sector":"Consumo não Cíclico / Alimentos Processados / Carnes e Derivados","financials":{"quota_count":1682473246,"dividends":{"yield_12m":2.085,"yield_12m_sum":0.582}},"region":"Brazil/Sao Paulo","currency":"BRL","market_time":{"open":"10:00","close":"17:30","timezone":-3},"logo":{"small":"https://assets.hgbrasil.com/finance/companies/small/brf-sa.png","big":"https://assets.hgbrasil.com/finance/companies/big/brf-sa.png"},"market_cap":7820.54,"price":28.06,"change_percent":0.86,"change_price":0.24,"updated_at":"2024-12-13 13:05:57"},"PRIO3":{"kind":"stock","symbol":"PRIO3","name":"Petrorio","company_name":"Petro Rio S.A.","document":"10.629.105/0001-68","description":"Constitui Objeto Da Companhia A Participação em Outras Sociedades Como Sócia. Acionista Ou Quotista. Independentemente de Sua Atividade.","website":"http://www.petroriosa.com.br/","sector":"Petróleo. Gás e Biocombustíveis / Petróleo. Gás e Biocombustíveis / Exploração. Refino e Distribuição","financials":{"quota_count":892059934,"dividends":{"yield_12m":0.178,"yield_12m_sum":0.073}},"region":"Brazil/Sao Paulo","currency":"BRL","market_time":{"open":"10:00","close":"17:30","timezone":-3},"logo":{"small":"https://assets.hgbrasil.com/finance/companies/small/petrorio.png","big":"https://assets.hgbrasil.com/finance/companies/big/petrorio.png"},"market_cap":36913.4,"price":41.37,"change_percent":0.8,"change_price":0.33,"updated_at":"2024-12-13 13:05:57"},"ELET6":{"kind":"stock","symbol":"ELET6","name":"Eletrobras","company_name":"Centrais Elet Bras S.A. Eletrobras","document":"00.001.180/0001-26","description":"Empresa Holding de Geração. Transmissão E Distribuição de Energia","website":"http://www.eletrobras.com/","sector":"Utilidade Pública / Energia Elétrica / Energia Elétrica","financials":{"quota_count":0,"dividends":{"yield_12m":4.591,"yield_12m_sum":1.823}},"region":"Brazil/Sao Paulo","currency":"BRL","market_time":{"open":"10:00","close":"17:30","timezone":-3},"logo":{"small":"https://assets.hgbrasil.com/finance/companies/small/eletrobras.png","big":"https://assets.hgbrasil.com/finance/companies/big/eletrobras.png"},"market_cap":13885.0,"price":39.98,"change_percent":0.68,"change_price":0.27,"updated_at":"2024-12-13 13:05:57"},"SMTO3":{"kind":"stock","symbol":"SMTO3","name":"São Martinho","company_name":"Sao Martinho S.A.","document":"51.466.860/0001-56","description":"Fabricação E Comércio de Açúcar. álcool E Derivados.","website":"http://www.saomartinho.com.br/","sector":"Consumo não Cíclico / Alimentos Processados / Açucar e Alcool","financials":{"quota_count":332435391,"dividends":{"yield_12m":3.597,"yield_12m_sum":0.896}},"region":"Brazil/Sao Paulo","currency":"BRL","market_time":{"open":"10:00","close":"17:30","timezone":-3},"logo":{"small":"https://assets.hgbrasil.com/finance/companies/small/sao-martinho.png","big":"https://assets.hgbrasil.com/finance/companies/big/sao-martinho.png"},"market_cap":8207.83,"price":24.69,"change_percent":0.67,"change_price":0.16,"updated_at":"2024-12-13 13:05:57"},"CPLE6":{"kind":"stock","symbol":"CPLE6","name":"Copel","company_name":"Cia Paranaense De Energia Copel","document":"76.483.817/0001-20","description":"Geração. Transmissão. Comercialização E Distribuição de Energia Elétrica","website":"http://ri.copel.com","sector":"Utilidade Pública / Energia Elétrica / Energia Elétrica","financials":{"quota_count":0,"dividends":{"yield_12m":1.261,"yield_12m_sum":0.116}},"region":"Brazil/Sao Paulo","currency":"BRL","market_time":{"open":"10:00","close":"17:30","timezone":-3},"logo":{"small":"https://assets.hgbrasil.com/finance/companies/small/copel.png","big":"https://assets.hgbrasil.com/finance/companies/big/copel.png"},"market_cap":4383.71,"price":9.26,"change_percent":0.65,"change_price":0.06,"updated_at":"2024-12-13 13:05:57"},"BBSE3":{"kind":"stock","symbol":"BBSE3","name":"BB Seguridade","company_name":"Bb Seguridade Participações S.A.","document":"17.344.597/0001-94","description":"Participação No Capital Social de Outras Sociedades. Que Tenham Por Atividade Operações de Seguros. Resseguros. Previdências Complementar Ou Capitalização.","website":"http://www.bbseguridaderi.com.br/","sector":"Financeiro / Previdência e Seguros / Seguradoras","financials":{"quota_count":2000000000,"dividends":{"yield_12m":7.202,"yield_12m_sum":2.633}},"region":"Brazil/Sao Paulo","currency":"BRL","market_time":{"open":"10:00","close":"17:30","timezone":-3},"logo":{"small":"https://assets.hgbrasil.com/finance/companies/small/bbseguridade.png","big":"https://assets.hgbrasil.com/finance/companies/big/bbseguridade.png"},"market_cap":73480.0,"price":36.79,"change_percent":0.63,"change_price":0.23,"updated_at":"2024-12-13 13:05:57"},"EGIE3":{"kind":"stock","symbol":"EGIE3","name":"Engie Brasil","company_name":"Engie Brasil Energia S.A.","document":"02.474.103/0001-19","description":"Geração E Comercialização de Energia Elétrica","website":"http://www.engie.com.br/","sector":"Utilidade Pública / Energia Elétrica / Energia Elétrica","financials":{"quota_count":815927740,"dividends":{"yield_12m":3.75,"yield_12m_sum":1.397}},"region":"Brazil/Sao Paulo","currency":"BRL","market_time":{"open":"10:00","close":"17:30","timezone":-3},"logo":{"small":"https://assets.hgbrasil.com/finance/companies/small/engie-brasil.png","big":"https://assets.hgbrasil.com/finance/companies/big/engie-brasil.png"},"market_cap":30499.4,"price":37.39,"change_percent":0.38,"change_price":0.14,"updated_at":"2024-12-13 13:05:57"},"USIM5":{"kind":"stock","symbol":"USIM5","name":"Usiminas","company_name":"Usinas Sid De Minas Gerais S.A. Usiminas","document":"60.894.730/0001-05","description":"Venda de Produtos Siderúrgicos. Como Chapas Grossas. Laminados A Quente. A Frio. Placas. Galvanizados. Entre Outros.","website":"http://www.usiminas.com/","sector":"Materiais Básicos / Siderurgia e Metalurgia / Siderurgia","financials":{"quota_count":0,"dividends":{"yield_12m":4.748,"yield_12m_sum":0.283}},"region":"Brazil/Sao Paulo","currency":"BRL","market_time":{"open":"10:00","close":"17:30","timezone":-3},"logo":{"small":"https://assets.hgbrasil.com/finance/companies/small/usiminas.png","big":"https://assets.hgbrasil.com/finance/companies/big/usiminas.png"},"market_cap":7474.33,"price":5.97,"change_percent":0.17,"change_price":0.01,"updated_at":"2024-12-13 13:05:57"},"STBP3":{"kind":"stock","symbol":"STBP3","name":"Santos Brasil","company_name":"Santos Brasil Participacoes S.A.","document":"02.762.121/0001-04","description":"A Companhia Tem Por Objeto A Exploração Comercial de Instalação Portuária Através de Operações Com Contêineres. Carga Geral Ou Afins E A Participação em Outras Sociedades.","website":"http://www.santosbrasil.com.br/","sector":"Bens Industriais / Transporte / Serviços de Apoio e Armazenagem","financials":{"quota_count":864170369,"dividends":{"yield_12m":19.149,"yield_12m_sum":2.474}},"region":"Brazil/Sao Paulo","currency":"BRL","market_time":{"open":"10:00","close":"17:30","timezone":-3},"logo":{"small":"https://assets.hgbrasil.com/finance/companies/small/santos-brp.png","big":"https://assets.hgbrasil.com/finance/companies/big/santos-brp.png"},"market_cap":11182.4,"price":12.94,"change_percent":0.15,"change_price":0.02,"updated_at":"2024-12-13 13:05:57"}},"execution_time":0.1,"from_cache":false}

Obtendo os dividendos de Ações, Fundos Imobiliários e BDRs

Novidade!

Este endpoint acabou de sair do forno!

Com esse endpoint você pode obter os dividendos de Ações, Fundos Imobiliários e BDRs listados no IBOVESPA através do símbolo desse título.
Atenção! É necessário ser membro à partir do plano Professional para realizar essa consulta.
Planos acima do Professional oferencem um maior número de títulos ao mesmo tempo, confira aqui nossos planos.

Conheça nossos planos

Títulos disponíveis: veja a lista.

Requer chave: sim
Requer plano: sim, plano Professional ou superior

Os dados são obtidos a partir do símbolo, através do parâmetro symbol.

É possível obter vários símbolos nas mesma consulta, separando por vírgula.

https://api.hgbrasil.com/finance/stock_dividends?key=SUA-CHAVE&symbol=alup4,alzr11,tgar11,visc11

Estrutura de dados

Os dados referentes à consulta chegam no parâmetro results, você também pode conferir a autenticação de sua chave no parâmetro de retorno valid_key.

kind - tipo do título
- cash - pagamento em dinheiro
- stock - pagamento em cotas
currency - moeda
isin_code - padronização internacional na codificação de títulos financeiros
label - referência
amount - valor
approved_in - aprovado em
traded_until - para negócios até
payment_date - data do pagamento (pode ser uma data futura)

Atenção! Exoneração de responsabilidade

Exemplo de resposta JSON

Índice Bovespa daily detalhado

Novidade!

Este endpoint acabou de sair do forno!

Com este método, você pode acessar o índice Bovespa diário detalhado em pontos.

Requer chave: sim
Requer plano: sim (plano Member - R$ 12,90 / mês)

Por padrão, a API retorna os dados do pregão atual (se estiver acontecendo no momento), ou do último pregão.

https://api.hgbrasil.com/finance/ibovespa?key=SUA-CHAVE

Estrutura de dados

data - array com o retorno por minuto
- points - índice em pontos
- change - variação comparado ao fechamento anterior
- date - data no formato YYYYMMDDHHMMSS00

Você também pode obter dados históricos do índice Bovespa com 3 filtros diferentes:

https://api.hgbrasil.com/finance/ibovespa?key=SUA-CHAVE&days_ago=3

Requer plano: sim (com acesso à dados históricos financeiros)

Por intervalo de datas:

start_date - data de inicio, string yyyy-mm-dd
end_date - data de término, string yyyy-mm-dd

Por data única:

date - data de inicio, string yyyy-mm-dd

Por número de dias atrás:

days_ago - número de dias atrás, inteiro

Somente um filtro desses 3 acima pode ser escolhido.
Lembre-se que a data consultada deve estar dentro dos limites de dados históricos de finanças para seu plano.

Exemplo de resposta

Formatos de retorno

Você pode escolher o formato de resposta da API através do parâmetro format na sua requisição.

https://api.hgbrasil.com/finance?format=json-cors&key=SUA-CHAVE

Formatos disponíveis

json - retorno em JSON, padrão
json-cors - retorno em JSON com headers CORS, chave exposta requerida
php-serialize - serialização do PHP (antigo formato da API)
debug - JSON visual para humanos, apenas para testes, não utilizar em produção

Atenção! Lembre-se que para usar a API no JavaScript cliente do seu site, o formato deve ser o JSON-CORS, para que os headers de autorização sejam enviados.

Esse formato requer uma chave válida e seu domínio, exatamente igual ao utilizado no site, deve ser cadastrado no momento da criação da chave.

Aumente seus limites na API ou obtenha suporte

Conheça as vantagens de ser membro da API

Sendo assinante, além de ajudar a manter o serviço para a comunidade, você terá acesso ao nosso suporte, maiores limites de consulta e recursos exclusivos.

Quero conhecer

Obter todos os dados em uma só requisição

Com este método, todos os dados são retornados em uma só requisição.

Dados retornados:

Câmbio das moedas: Dólar USD, Euro EUR, Libra (GBP), Peso (ARS) e Bitcoin (BTC) para Real (BRL);
Valores de exchanges de Bitcoin (BTC) como Coinbase, Blockchain.info, BitStamp, FoxBit e Mercado Bitcoin;
Variação dos índices: IBOVESPA, IFIX, NASDAQ, Dow Jones, CAC 40 e NIKKEI;
Taxas brasileiras: CDI, SELIC e fator diário.

Requer chave: sim, para que todos os dados sejam exibidos

https://api.hgbrasil.com/finance?key=SUA-CHAVE

Obter somente cotações de moedas e bolsas

Com este método, apenas as cotações de moedas e bolsa de valores são retornados.

Dados retornados:

Câmbio das moedas: Dólar (USD), Euro (EUR), Libra (GBP), Peso (ARS) e Bitcoin (BTC) para Real (BRL);
Valores de exchanges de Bitcoin (BTC) como Coinbase, Blockchain.info, BitStamp, FoxBit e Mercado Bitcoin;
Variação das bolsas de valores: IBOVESPA, NASDAQ, CAC 40 e NIKKEI.

Requer chave: sim, para que todos os dados sejam exibidos

https://api.hgbrasil.com/finance/quotations?key=SUA-CHAVE

Obter somente taxas CDI e SELIC

Com este método, apenas as taxas de juros, CDI e Selic são retornadas.

Dados retornados:

Taxas brasileiras: CDI, SELIC e fator diário.

Requer chave: sim

https://api.hgbrasil.com/finance/taxes?key=SUA-CHAVE

Obtendo dados históricos

Com este método, você pode acessar dados históricos registrados pela API.
Esse método necessita da contratação de um plano que tenha suporte à dados históricos.

Conheça nossos planos

Requer chave: sim
Requer plano: sim (com suporte à dados históricos)

Os dados históricos são obtidos a partir de uma data passada.

https://api.hgbrasil.com/finance/historical?key=SUA-CHAVE&days_ago=3&mode=all

Você pode escolher a data por 3 tipos de filtros diferentes:

Por intervalo de datas:

start_date - data de inicio, string yyyy-mm-dd
end_date - data de término, string yyyy-mm-dd

Por data única:

date - data de inicio, string yyyy-mm-dd

Por número de dias atrás:

days_ago - número de dias atrás, inteiro

Somente um filtro desses 3 acima pode ser escolhido.
Lembre-se que a data consultada deve estar dentro dos limites de dados históricos de finanças para seu plano.

Juntamente com uma das datas acima, você pode:

Obter todos os dados, ou somente um usando o filtro mode:

mode - string, disponíveis: all, currencies, stocks, bitcoin, taxes

Somente um filtro acima pode ser utilizado.

Exemplo de resposta

O sistema obtem os dados e faz o cálculo diário para cada retorno, a fim de obter o primeiro valor, último, maior, menor e média.

Obtendo dados históricos de Ações e Fundos Imobiliários

Novidade!

Este endpoint acabou de sair do forno!

Com este método, você pode acessar dados históricos registrados pela API de Ações e Fundos Imobiliários.
Esse método necessita da contratação de um plano que tenha suporte à dados históricos de finanças.

Conheça nossos planos

Requer chave: sim
Requer plano: sim (com suporte à dados históricos)

Os dados históricos são obtidos a partir de uma data passada.

https://api.hgbrasil.com/finance/historical/stocks?key=SUA-CHAVE&days_ago=3&symbols=embr3,itsa4,hglg11

Para buscar por ações ou fundos imobiliários, você pode utilizar as mesmas formas de busca da API:

Somente um é necessário.

symbols - um ou mais ticker de empresa ou FII * - veja a lista de tickers disponíveis

* o número máximo de tickers em uma mesma consulta varia de acordo com o plano contratado

Você pode escolher a data por 3 tipos de filtros diferentes:

Por intervalo de datas:

start_date - data de inicio, string yyyy-mm-dd
end_date - data de término, string yyyy-mm-dd

Por data única:

date - data de inicio, string yyyy-mm-dd

Por número de dias atrás:

days_ago - número de dias atrás, inteiro

Somente um filtro desses 3 acima pode ser escolhido.
Lembre-se que a data consultada deve estar dentro dos limites de dados históricos de finanças para seu plano.

Exemplo de resposta

Personalizando a resposta

Algumas aplicações, como IoT, tem menos poder em processar e parsear dados. Por isso você pode em sua requisição, solicitar que alguns dados sejam omitidos, para que apenas os dados que você necessite sejam exibidos.

https://api.hgbrasil.com/finance?array_limit=1&fields=only_results,bitcoin&key=SUA-CHAVE

Você pode escolher quais campos são retornados, limitar arrays ou ignorar os retornos de status e chave. Este recurso é compatível apenas com o formato JSON e requer o uso de sua chave de API.

fields - neste parâmetro você configura o recurso e escolhe quais campos manter, dados válidos abaixo, você pode colocar mais de um, separados por vírgula
- only_results - remove os dados de status, cache e chave, enviando apenas os resultados
- nome-do-campo - nome do campo desejado
array_limit - inteiro limitando o número de itens em arrays do retorno

Qualquer forma de busca pode ser utilizada junto a este método.

Exemplo de resposta

{"bitcoin":{"blockchain_info":{"name":"Blockchain.info","format":["USD","en_US"],"last":100302.92,"buy":100302.92,"sell":100302.92,"variation":0.213},"coinbase":{"name":"Coinbase","format":["USD","en_US"],"last":56019.33,"variation":2.506},"bitstamp":{"name":"BitStamp","format":["USD","en_US"],"last":100295.0,"buy":100375.0,"sell":100374.0,"variation":0.277},"foxbit":{"name":"FoxBit","format":["BRL","pt_BR"],"last":608429.2256,"variation":1.032},"mercadobitcoin":{"name":"Mercado Bitcoin","format":["BRL","pt_BR"],"last":608500.0,"buy":608508.03384843,"sell":609063.16192749,"variation":1.041}}}

Dicas de boas práticas

Faça cache
Para que seus limites de consulta sejam utilizados da melhor forma possível, faça cache de suas requisições.

Cada pageview do seu site ou aplicação, não necessita necessáriamente de uma nova consulta ao HG Finance.

Por exemplo, se seu usuário acabou de entrar, faça uma consulta (mesmo que seja no lado do cliente), mas assim que o dado for obtido, salve em um armazenamento local ou temporário para que na próxima página que seu usuário entrar, essa consulta não seja necessária.

Utilize rotinas
Se sua aplicação permitir, utilize rotinas ou threads para obter os dados. Isso pode melhorar o tempo final de resposta do seu serviço que utiliza a API.

Exoneração de responsabilidade

API para fins informativos. Não garantimos a precisão dos dados fornecidos pela API ou contidos nesta página, uma vez que devem ser utilizados apenas para efeitos informativos. Trabalhamos pela estabilidade e precisão dos dados, porém, os dados podem estar atrasados ou errados "no estado em que se encontram", confirme todos os dados antes de efetuar qualquer ação que possa ser afetada por estes valores, assim como demais endpoints da API.

Qualquer dúvida verifique nossos termos de uso ou entre em contato.

Seja membro

Em breve

HG Finance Documentação

API de dados financeiros

Documentação

Índice

Introdução

Estrutura de dados

Autenticação e chave

Obtendo o preço de Ações, BDRs e FIIs listados no IBOVESPA

Novidade!

Estrutura de dados

Obtendo as ações com as maiores altas ou baixas no IBOVESPA

Obtendo os dividendos de Ações, Fundos Imobiliários e BDRs

Novidade!

Estrutura de dados

Índice Bovespa daily detalhado

Novidade!

Você também pode obter dados históricos do índice Bovespa com 3 filtros diferentes:

Por intervalo de datas:

Por data única:

Por número de dias atrás:

Formatos de retorno

Formatos disponíveis

Aumente seus limites na API ou obtenha suporte

Conheça as vantagens de ser membro da API

Obter todos os dados em uma só requisição

Obter somente cotações de moedas e bolsas

Obter somente taxas CDI e SELIC

Obtendo dados históricos

Você pode escolher a data por 3 tipos de filtros diferentes:

Por intervalo de datas:

Por data única:

Por número de dias atrás:

Obter todos os dados, ou somente um usando o filtro mode:

Obtendo dados históricos de Ações e Fundos Imobiliários

Novidade!

Para buscar por ações ou fundos imobiliários, você pode utilizar as mesmas formas de busca da API:

Você pode escolher a data por 3 tipos de filtros diferentes:

Por intervalo de datas:

Por data única:

Por número de dias atrás:

Personalizando a resposta

Dicas de boas práticas

Exoneração de responsabilidade