# Documentação
Bem-vindo à documentação oficial das APIs da **HG Brasil**. Aqui você encontrará todos os detalhes para integrar e utilizar nossos serviços em sua aplicação, de forma simples e objetiva.
## Produtos
As nossas APIs foram desenvolvidas **de desenvolvedor para desenvolvedor** e oferecem acesso a dados essenciais para aplicações modernas, incluindo:
::card-group{.sm:grid-cols-1}
:::card
---
icon: tabler:currency-dollar
title: Mercado Financeiro
to: https://hgbrasil.com/docs/finance
---
Cotações de ações, índices do mercado, moedas, criptomoedas e dados históricos financeiros.
:::
:::card
---
icon: tabler:haze
title: Previsão do Tempo
to: https://hgbrasil.com/docs/weather
---
Informações meteorológicas atualizadas e previsões detalhadas para diversas cidades.
:::
:::card
---
icon: tabler:map-2
title: Geolocalização
to: https://hgbrasil.com/docs/geo
---
Obtenha a localização aproximada dos seus usuários através do IPv4 ou IPv6, facilitando a personalização do conteúdo e a análise do público.
:::
::
# Chave de Integração
Uma **chave de integração** é um identificador único que permite à sua aplicação consultar as APIs da HG Brasil. Ela funciona como uma senha de acesso que autentica suas requisições, garantindo que apenas usuários autorizados possam utilizar os dados. Cada chave é associada a uma conta e possui limites de uso, que podem variar conforme o plano escolhido.
Com a chave em mãos, você poderá integrar recursos como previsão do tempo, cotações financeiras e geolocalização por IP em sua aplicação.
::tip
Guarde sua chave em segurança e nunca a divulgue publicamente.
::
::warning
Caso suspeite de uso indevido, atualize-a imediatamente através do Console.
::
::steps{level="4"}
#### Entre no Console
Acesse o Console e entre com as suas credenciais, ou faça um cadastro caso ainda não seja membro.
:::u-button
---
href: https://console.hgbrasil.com/
label: Acessar o Console
target: _blank
trailing-icon: tabler:arrow-right
---
:::
#### Acesse o menu de chaves
No menu, selecione a opção `Chaves`{color="primary"} e clique no botão `Criar nova chave`{color="primary"}.
:::u-button
---
href: https://console.hgbrasil.com/keys/new_key_plan
icon: tabler:key
label: Criar chave
target: _blank
---
:::
#### Crie uma chave
Preencha os seguintes campos:
- **Nome da sua aplicação:**:br
Informe o nome do seu projeto ou aplicação. Este nome servirá para identificar a chave no painel de controle.
- **Tipo de chave:**:br
Selecione o tipo de chave que melhor se adequa à sua necessidade:
- **Chave para uso exposto:**:br
Destinada a aplicações *client-side*, como aquelas que utilizam JavaScript diretamente no navegador. Essa chave pode ficar exposta, mas deve ser utilizada apenas em ambientes onde o domínio esteja previamente configurado.
- **Chave para uso interno:**:br
Indicada para integrações no lado do servidor ou aplicativos mobile, onde a chave permanece protegida e não é exposta publicamente. Chaves internas podem ser utilizadas para testes em ambientes locais como `localhost` ou `127.0.0.1`, não sendo necessário informar o domínio.
- **Domínio:**:br
Este campo é obrigatório para **chaves de uso exposto**. Informe o domínio do seu site. O sistema utilizará esta informação para validar as requisições, garantindo que a chave seja utilizada somente a partir do ambiente autorizado.
Ao salvar, Sua nova chave será exibida na tela. Copie-a e armazene em um local seguro.
#### Configurando sua aplicação
Vamos supor que a chave gerada seja `suachave`. Você deverá informá-la no parâmetro `key` na URL.
:endpoint{endpoint="/weather"}
::
## Validação da chave
Todas as respostas da API incluem um campo `valid_key` que indica se a chave utilizada é válida:
```json
{
"by": "default",
"valid_key": true,
"results": {
// ...
}
}
```
O campo `valid_key` retornará `true` se chave é válida e está funcionando corretamente ou `false` caso a chave seja inválida ou exista algum problema na configuração.
Se `valid_key` for `false`, verifique se:
- A chave foi informada corretamente;
- O domínio está configurado (para chaves expostas);
- A chave não foi desativada ou removida.
# CORS
Ao desenvolver aplicações JavaScript que fazem requisições diretamente do navegador para APIs externas, você precisará configurar o suporte a CORS (Cross-Origin Resource Sharing).
Isso é necessário porque os navegadores modernos implementam a política de mesma origem (*same-origin policy*), um mecanismo de segurança que bloqueia requisições entre diferentes domínios. Sem a configuração adequada de CORS, suas requisições serão bloqueadas e você encontrará erros no console do navegador.
## Sintomas
Se você tentar fazer uma requisição diretamente do navegador sem configurar CORS, encontrará um erro como este no console:
```text
Access to fetch at 'https://api.hgbrasil.com/finance?key=suachave' from origin 'http://seusite.com' has been blocked by CORS policy: No 'Access-Control-Allow-Origin' header is present on the requested resource.
```
Esse erro acontece porque o navegador está protegendo seus usuários, bloqueando requisições não autorizadas entre diferentes domínios.
## Solução
Para permitir que suas requisições funcionem no navegador, adicione o parâmetro `format=json-cors` à sua URL:
:endpoint{endpoint="/finance?format=json-cors&key=suachave"}
Esse parâmetro instrui nossa API a incluir os cabeçalhos HTTP necessários na resposta, informando ao navegador que a requisição é segura e autorizada.
::tip
O formato `json-cors` é projetado especificamente para aplicações JavaScript que rodam no navegador. Ele adiciona os cabeçalhos `Access-Control-Allow-Origin` necessários para que o navegador permita a requisição.
::
### Desenvolvimento Local
Se você está testando localmente, não precisa se preocupar! Os seguintes endereços já são permitidos automaticamente: `localhost` e `127.0.0.1`.
Isso significa que você pode começar a desenvolver imediatamente sem configuração adicional.
### Ambiente de Produção
Quando sua aplicação estiver pronta para produção, você precisará autorizar explicitamente o domínio onde ela estará hospedada. Por exemplo, se seu site for `example.com`, você deve adicionar esse domínio à lista de domínios permitidos.
**Como configurar:**
1. Acesse o painel de controle da sua conta;
2. Vá para a seção de gerenciamento de chaves de API;
3. Ao criar ou editar uma chave, procure pela opção de "chave para uso exposto";
4. Adicione os domínios que devem ter permissão para usar essa chave.
::u-button
---
href: https://console.hgbrasil.com/keys
label: Gerenciar Chaves de API
target: _blank
trailing-icon: tabler:arrow-right
variant: subtle
---
::
::warning
Lembre-se de adicionar apenas os domínios necessários. Isso ajuda a manter sua chave segura e evita uso não autorizado.
::
# Respostas Formatadas
## Formatos
Basta aplicar o parâmetro `format` em qualquer *endpoint*.
:endpoint{endpoint="/finance?format=json-cors"}
::field-group
:::field{name="format" type="string"}
Define o formato desejado de retorno.
- `json`: Formato padrão.
- `json-cors`: Para aplicações JavaScript com suporte a CORS.
- `php-serialize`: Para integração com sistemas PHP.
- `debug`: Uma visualização legível para testes (não recomendado para produção).
:::
::
## CORS (Cross-Origin Resource Sharing)
Para aplicações JavaScript que fazem requisições diretamente do navegador, é necessário configurar adequadamente o suporte a CORS. Isso evita erros relacionados à política de mesma origem dos navegadores.
::u-button
---
href: https://hgbrasil.com/docs/guide/cors
label: Saiba mais sobre CORS
trailing-icon: tabler:arrow-right
variant: subtle
---
::
## Filtrando Campos
Este recurso foi desenvolvido especialmente para otimizar o tráfego de rede e melhorar a performance em dispositivos com recursos limitados, como dispositivos IoT e aplicações móveis. Ao filtrar apenas os dados necessários, você reduz o consumo de banda e acelera o processamento.
Você pode personalizar a resposta com o parâmetro `fields` e limitar a quantidade de respostas com `array_limit`.
### Finance
:endpoint{endpoint="/finance?fields=only_results,currencies,stocks,bitcoin,taxes&array_limit=2"}
### Weather
Além dos campos básicos, você pode filtrar campos específicos como `condition_slug`, `humidity`, `wind_speedy`, `forecast` e outros dados meteorológicos:
:endpoint{endpoint="/weather?fields=only_results,temp,description,city&woeid=455827"}
:endpoint{endpoint="/weather?fields=only_results,temp,humidity,wind_speedy,condition_slug,forecast&woeid=455827&array_limit=3"}
### Geo
:endpoint{endpoint="/geoip?fields=only_results,city,region,country_name,continent&address=remote"}
---
::field-group
:::field{name="fields" type="string"}
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.
:::
:::field{name="array_limit" type="number"}
Valor inteiro limitando o número de itens na resposta.
:::
::
*Compatível apenas com o formato JSON.*
# Boas Práticas
Seguir essas orientações ajudará a reduzir a latência, otimizar o uso dos recursos e evitar problemas com limites de consulta.
## Motivação
1. Diminuir o número de requisições evita o esgotamento dos limites de consulta e minimiza a carga tanto na sua aplicação quanto no servidor.
2. Dados em cache proporcionam respostas mais rápidas, reduzindo o tempo de espera.
3. Menos tráfego de rede e processamento tornam sua aplicação mais leve e responsiva.
## Estratégias
::accordion
:::accordion-item{label="Cache no Lado do Cliente"}
Utilize soluções como LocalStorage, SessionStorage ou IndexedDB para armazenar dados que não se atualizam com frequência.
:::
:::accordion-item{label="Cache no Lado do Servidor"}
Implemente sistemas de cache (ex.: Redis ou Memcached) para armazenar respostas e servir requisições subsequentes com menor latência.
:::
:::accordion-item{label="Definição de TTL (Time-To-Live)"}
Configure um tempo de expiração para os dados em cache, garantindo que informações sensíveis sejam atualizadas regularmente.
:::
:::accordion-item{label="Validação de Dados"}
Para verificar se os dados foram atualizados, consulte os campos `updated_at` presentes no corpo da resposta JSON. Quando disponível, este campo indica a última atualização dos dados e pode ser usado para implementar estratégias de cache mais eficientes.
:::
::
## Implantando
::accordion
:::accordion-item{label="Seleção de Campos"}
Utilize o parâmetro `fields` para solicitar apenas as informações necessárias. Isso reduz o tamanho da resposta e acelera o processamento.
:::
:::accordion-item{label="Cache no Lado do Servidor"}
O parâmetro `array_limit` permite restringir o número de itens em arrays, evitando o processamento de grandes volumes de dados desnecessários.
:::
:::accordion-item{label="Definição de TTL (Time-To-Live)"}
Configure um tempo de expiração para os dados em cache, garantindo que informações sensíveis sejam atualizadas regularmente.
:::
:::accordion-item{label="Aplicação de Filtros"}
Use filtros (por exemplo, para datas, localidades ou categorias) para refinar a consulta e reduzir a quantidade de dados trafegados.
:::
::
---
Uma implementação cuidadosa e otimizada não só melhora a performance e a experiência do usuário, mas também assegura um uso sustentável dos limites de consulta, contribuindo para a escalabilidade da sua aplicação.
Caso necessite de mais informações ou suporte, nossa equipe está disponível para ajudar. Consulte também outras seções da documentação para explorar todos os recursos oferecidos.
# Erros
Quando uma requisição não pode ser processada, a API retorna um objeto `errors` contendo uma lista com os erros identificados. Cada erro possui um código, uma mensagem descritiva e um link para a documentação.
## Formato
Os erros são retornados no array `errors` da resposta. Os códigos são sempre enviados em letras maiúsculas.
```json
{
"metadata": {
"key_status": "invalid",
"cached": false,
"response_time_ms": 0.0,
"language": "pt-br"
},
"results": [],
"errors": [
{
"code": "INVALID_API_KEY",
"message": "Chave de API inválida.",
"help": "https://hgbrasil.com/docs"
},
{
"code": "UNAUTHORIZED_KEY",
"message": "Chave não possui acesso para este recurso.",
"help": "https://hgbrasil.com/docs"
}
]
}
```
::field-group
:::field{name="code" type="string"}
Código identificador do erro, sempre em letras maiúsculas.
:::
:::field{name="message" type="string"}
Mensagem descritiva explicando o motivo do erro.
:::
:::field{name="help" type="string"}
Link para a documentação com mais informações.
:::
::
## Lista de Erros
| Código | Mensagem |
| ----------------------- | ----------------------------------------------------- |
| `INVALID_API_KEY` | Chave de API inválida. |
| `UNAUTHORIZED_KEY` | Chave não possui acesso para este recurso. |
| `REQUIRED_TICKER` | Ticker é obrigatório. |
| `INVALID_TICKER` | Ticker inválido. |
| `INVALID_TIME_SERIES` | Série temporal inválida. |
| `MAX_PER_REQUEST` | Máximo de itens por requisição excedido. |
| `INVALID_RANGE` | O dado informado está fora do intervalo permitido. |
| `HISTORICAL_DATE_LIMIT` | Data máxima do histórico deve estar dentro do limite. |
| `INVALID_DATE` | Data inválida. |
| `INVALID_DATE_RANGE` | Intervalo de datas inválido. |
| `INVALID_PARAMETER` | Parâmetro inválido. |
| `REQUIRED_DATE` | Data é obrigatório. |
# Mercado Financeiro
A **HG Finance** reúne diversos conjuntos de dados essenciais para o monitoramento do mercado financeiro. Com ela, você poderá:
- Acessar **cotações de moedas e ativos** (como ações e FIIs);
- Descobrir os **tickers disponíveis** para consulta nos endpoints;
- Consultar **índices de mercado**, inclusive os que exibem altas e baixas;
- Obter informações sobre **criptomoedas** a partir de múltiplas exchanges;
- Recuperar as principais **taxas de juros** do Brasil (CDI, SELIC, etc.);
- Consultar **dados históricos** para análises e projeções.
Esta página serve como ponto de partida para entender a estrutura geral da API, como autenticar suas requisições e quais formatos de resposta estão disponíveis.
::callout
---
color: neutral
icon: tabler:key
to: https://hgbrasil.com/docs/guide/key
---
Para acessar os dados da API é necessário utilizar uma chave de integração.
::
::note{icon="tabler:clock"}
As cotações são atualizadas em intervalos de 15 a 45 minutos durante o pregão.
::
## Requisição
Todas as requisições tem como base o seguinte endpoint:
:endpoint{endpoint="/finance"}
:request-example{endpoint="/finance"}
## Resposta
Exemplo de resposta no formato `JSON`.
:response-json{endpoint="/finance"}
### Campos
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`.
::field-group
:::field{name="currencies" type="object"}
Cotação das moedas.
| Campo | Tipo | Descrição | Exemplo |
| ----------------- | ------------------------------------------------------------------------------------------------- | ------------------------------------------------------------- | ------- |
| `source` | `string`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Código ISO da moeda base da cotação. | BRL |
| `[iso]` | `object`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Código ISO da moeda destino. | USD |
| `[iso].name` | `string`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Nome da moeda. | Dollar |
| `[iso].buy` | `number`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Valor de compra. | 5.7276 |
| `[iso].sell` | `number`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Valor de venda. | 5.7274 |
| `[iso].variation` | `number`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Variação em percentual referente à última hora útil anterior. | -0.021 |
:::
:::field{name="stocks" type="object"}
Posições dos principais mercados.
| Campo | Tipo | Descrição | Exemplo |
| ------------------- | ------------------------------------------------------------------------------------------------- | ------------------------------------------------------------- | ----------------- |
| `[index]` | `object`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Dados do índice de mercado. | Ibovespa |
| `[index].name` | `string`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Nome do índice. | BM\&F BOVESPA |
| `[index].location` | `string`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Localização do mercado. | Sao Paulo, Brazil |
| `[index].points` | `number`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Pontos (somente Ibovespa). | 126571.9 |
| `[index].variation` | `number`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Variação em percentual referente à última hora útil anterior. | -0.44 |
:::
:::field{name="bitcoin" type="object"}
Cotação do Bitcoin nas principais corretoras.
| Campo | Tipo | Descrição | Exemplo |
| -------------------- | ------------------------------------------------------------------------------------------------- | ------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
| `[broker]` | `object`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Dados da corretora. | blockchain\_info |
| `[broker].name` | `string`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Nome da corretora. | Blockchain.info |
| `[broker].format` | `Array`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Array com moeda base e idioma da moeda. | `["USD", "en_US"]`{.language-json.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="json"} |
| `[broker].last` | `number`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Última posição (cotação atual). | 93989.45 |
| `[broker].buy` | `number`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Valor para compra (pode não estar disponível). | 93989.45 |
| `[broker].sell` | `number`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Valor para venda (pode não estar disponível). | 93989.45 |
| `[broker].variation` | `number`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Variação em percentual referente à última hora útil anterior. | -1.245 |
:::
:::field{name="taxes" type="array"}
Taxas de juros do Brasil.
| Campo | Tipo | Descrição | Exemplo |
| ----------------- | ------------------------------------------------------------------------------------------------- | -------------------------------- | ---------- |
| `[].date` | `string`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Data de referência. | 2025-02-27 |
| `[].cdi` | `number`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Taxa CDI em percentual. | 13.25 |
| `[].selic` | `number`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Taxa Selic em percentual. | 13.25 |
| `[].daily_factor` | `number`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Fator diário. | 1.00049037 |
| `[].selic_daily` | `number`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Taxa Selic diária em percentual. | 13.15 |
| `[].cdi_daily` | `number`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Taxa CDI diária em percentual. | 13.15 |
:::
::
# Balanço Patrimonial
Entenda a saúde financeira de uma empresa em um único endpoint. O balanço patrimonial é como uma fotografia do patrimônio de uma companhia em uma data específica — o que ela possui (ativos), o que ela deve (passivos) e o que sobra para os acionistas (patrimônio líquido).
::callout
---
color: neutral
icon: tabler:key
to: https://hgbrasil.com/docs/guide/key
---
Para acessar os dados da API é necessário utilizar uma chave de integração e um plano compatível.
::
---
## O que é o Balanço Patrimonial?
O balanço patrimonial responde a uma pergunta fundamental: **qual é a situação financeira desta empresa hoje?**
Ele é dividido em três grandes blocos:
| Bloco | O que representa | Exemplo |
| ---------------------- | ------------------------------------------------------------------------------------- | ---------------------------------- |
| **Ativos** | Tudo que a empresa possui — dinheiro em caixa, imóveis, máquinas, direitos a receber. | Caixa, estoques, imobilizado |
| **Passivos** | Tudo que a empresa deve — empréstimos, fornecedores, impostos. | Dívidas de curto e longo prazo |
| **Patrimônio Líquido** | O que sobra para os acionistas após subtrair os passivos dos ativos. | Capital social, reservas de lucros |
::callout{color="info" icon="tabler:info-circle"}
Os dados são consolidados, incluíndo a empresa e suas subsidiárias como um grupo econômico único.
::
---
## Períodos
Você pode consultar dados anuais ou trimestrais. Os nomes de campo `period_type` e `fiscal_period` indicam o tipo de período:
| `period` | Descrição | `fiscal_period` |
| ----------------- | -------------------------------------------------- | ---------------------- |
| `annual` (padrão) | Exercícios anuais completos, em ordem decrescente. | `FY` |
| `quarterly` | Trimestres, em ordem decrescente. | `Q1`, `Q2`, `Q3`, `Q4` |
---
## Requisição
Informe o ticker no formato `{fonte}:{símbolo}`.
:endpoint{endpoint="/v2/finance/balance-sheets?tickers=B3:PETR4"}
:request-example{endpoint="/v2/finance/balance-sheets?tickers=B3:PETR4"}
:stock-search
### Parâmetros
::field-group
:::field{required name="tickers" type="string"}
Ticker do ativo no formato `{fonte}:{símbolo}`. Para múltiplos ativos, separe por vírgula: `B3:PETR4,B3:VALE3`.
:::
:::field{name="period" type="string"}
Tipo de período fiscal: `annual` (padrão) ou `quarterly`.
:::
:::field{name="start_date" type="string"}
Data inicial para filtrar os dados (`yyyy-mm-dd`).
:::
:::field{name="end_date" type="string"}
Data final para filtrar os dados (`yyyy-mm-dd`).
:::
:::field{name="days_ago" type="number"}
Número de dias atrás a partir de hoje. Use `0` para dados do dia atual.
:::
::
---
## Resposta
:response-json{endpoint="/v2/finance/balance-sheets?tickers=B3:PETR4"}
### Campos
Os dados de cada ativo retornam no array `results`:
#### Ativo
| Campo | Tipo | Descrição | Exemplo |
| ----------- | ------------------------------------------------------------------------------------------------- | ----------------------------------------------- | ------------------------ |
| `ticker` | `string`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Ticker completo no formato `{fonte}:{símbolo}`. | B3\:PETR4 |
| `unit` | `string`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Unidade dos valores (`currency` para moeda). | currency |
| `currency` | `string`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Moeda dos valores. | BRL |
| `symbol` | `string`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Código de negociação do ativo. | PETR4 |
| `name` | `string`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Nome simplificado da empresa. | Petrobras |
| `full_name` | `string`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Razão social completa da empresa. | Petróleo Brasileiro S.A. |
#### Período
Cada item do array `statements` representa o balanço em uma data-base:
| Campo | Tipo | Descrição | Exemplo |
| --------------- | ------------------------------------------------------------------------------------------------- | ------------------------------------------------------- | ---------- |
| `period_type` | `string`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Tipo do período: `annual` ou `quarterly`. | annual |
| `end_date` | `string`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Data-base do balanço (ponto no tempo). | 2024-12-31 |
| `fiscal_year` | `number`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Ano fiscal. | 2024 |
| `fiscal_period` | `string`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Período fiscal: `FY` (anual) ou `Q1`–`Q4` (trimestral). | FY |
#### Assets (Ativo)
O objeto `assets` contém os bens e direitos da empresa:
| Campo | Tipo | Descrição |
| ----------------------------------- | ------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------ |
| `total` | `number`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Ativo total. |
| `current_assets` | `number`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Ativo circulante — bens e direitos realizáveis em até 12 meses. |
| `cash_and_equivalents` | `number`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Caixa e equivalentes de caixa. |
| `short_term_investments` | `number`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Aplicações financeiras de curto prazo. |
| `accounts_receivable` | `number`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Contas a receber de clientes. |
| `inventory` | `number`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Estoques de matéria-prima, produtos em elaboração e acabados. |
| `biological_assets` | `number`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Ativos biológicos circulantes (ex.: rebanho, plantações). |
| `taxes_recoverable` | `number`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Tributos a recuperar. |
| `prepaid_expenses` | `number`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Despesas antecipadas. |
| `other_current_assets` | `number`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Outros ativos circulantes. |
| `non_current_assets` | `number`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Ativo não circulante — bens e direitos realizáveis após 12 meses. |
| `non_current_receivables` | `number`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Realizável a longo prazo — total do grupo. |
| `non_current_financial_investments` | `number`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Aplicações financeiras de longo prazo. |
| `related_party_receivables` | `number`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Créditos com partes relacionadas (controladas e coligadas). |
| `non_current_trade_receivables` | `number`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Contas a receber de longo prazo oriundas das operações. |
| `deferred_tax_assets` | `number`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Tributos diferidos ativos. |
| `other_non_current_assets` | `number`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Outros ativos não circulantes. |
| `equity_method_investments` | `number`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Participações avaliadas pelo método da equivalência patrimonial. |
| `property_plant_and_equipment` | `number`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Ativo imobilizado — máquinas, imóveis, veículos e equipamentos. |
| `right_of_use_assets` | `number`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Ativos de direito de uso (arrendamentos e aluguéis capitalizados). |
| `goodwill` | `number`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Ágio por expectativa de rentabilidade futura (goodwill). |
| `intangible_assets` | `number`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Ativo intangível — marcas, patentes, software e licenças. |
::callout{color="warning" icon="tabler:alert-triangle"}
Os campos `right_of_use_assets` e `goodwill` podem retornar `null` quando não identificados com segurança para a empresa consultada. Quando `goodwill` for `null`, seu valor pode estar incluído em `intangible_assets`.
::
#### Liabilities (Passivo)
O objeto `liabilities` contém as obrigações da empresa:
| Campo | Tipo | Descrição |
| ------------------------------- | ------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------- |
| `current_liabilities` | `number`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Passivo circulante — obrigações com vencimento em até 12 meses. |
| `employee_benefits_payable` | `number`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Obrigações sociais e trabalhistas (salários, férias, encargos). |
| `accounts_payable` | `number`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Fornecedores. |
| `taxes_payable` | `number`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Obrigações fiscais. |
| `short_term_debt` | `number`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Empréstimos e financiamentos de curto prazo. |
| `other_current_liabilities` | `number`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Outras obrigações circulantes. |
| `current_provisions` | `number`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Provisões de curto prazo (contingências, garantias). |
| `non_current_liabilities` | `number`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Passivo não circulante — obrigações com vencimento após 12 meses. |
| `long_term_debt` | `number`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Empréstimos e financiamentos de longo prazo. |
| `other_non_current_liabilities` | `number`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Outras obrigações de longo prazo. |
| `deferred_tax_liabilities` | `number`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Tributos diferidos passivos. |
| `non_current_provisions` | `number`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Provisões de longo prazo. |
#### Equity (Patrimônio Líquido)
O objeto `equity` representa o valor residual dos ativos após deduzir os passivos:
| Campo | Tipo | Descrição |
| ------------------------------ | ------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
| `total` | `number`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Patrimônio líquido consolidado. |
| `share_capital` | `number`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Capital social realizado. |
| `additional_paid_in_capital` | `number`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Reservas de capital (inclui ágio na emissão de ações e ações em tesouraria). |
| `revaluation_surplus` | `number`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Reservas de reavaliação. |
| `legal_and_statutory_reserves` | `number`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Reservas de lucros (legal, estatutária, retenção de lucros e outras). |
| `retained_earnings` | `number`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Lucros ou prejuízos acumulados. |
| `accumulated_oci` | `number`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Total dos outros resultados abrangentes acumulados (OCI). |
| `valuation_adjustments` | `number`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Ajustes de avaliação patrimonial (variações de fair value). |
| `translation_adjustments` | `number`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Ajustes acumulados de conversão cambial de subsidiárias no exterior. |
| `other_accumulated_oci` | `number`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Outros resultados abrangentes (ajustes atuariais e demais itens). |
| `non_controlling_interest` | `number`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Participação dos acionistas não controladores. |
::callout{color="info" icon="tabler:info-circle"}
O campo `accumulated_oci` é a soma de `valuation_adjustments`, `translation_adjustments` e `other_accumulated_oci`.
::
#### Fonte
O objeto `source` contém informações sobre a origem dos dados:
| Campo | Tipo | Descrição | Exemplo |
| -------------------------- | ------------------------------------------------------------------------------------------------- | ----------------------- | ----------------------------------------------------- |
| `source.symbol` | `string`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Código da fonte. | CVM |
| `source.name` | `string`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Nome da fonte. | Comissão de Valores Mobiliários |
| `source.full_name` | `string`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Nome completo da fonte. | Comissão de Valores Mobiliários |
| `source.url` | `string`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Site oficial. | {rel=""nofollow""} |
| `source.location.timezone` | `string`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Fuso horário. | America/Sao\_Paulo |
# Demonstração de Resultados (DREs)
Descubra se uma empresa está dando lucro ou prejuízo — e de onde vem esse resultado. A demonstração de resultados (DRE) é como um filme do desempenho financeiro de uma companhia ao longo de um período, mostrando receitas, custos, despesas e o lucro final.
::callout
---
color: neutral
icon: tabler:key
to: https://hgbrasil.com/docs/guide/key
---
Para acessar os dados da API é necessário utilizar uma chave de integração e um plano compatível.
::
---
## O que é a Demonstração de Resultados?
Enquanto o [balanço patrimonial](https://hgbrasil.com/docs/finance/balance-sheets) mostra a situação da empresa em uma data específica, a DRE mostra **o que aconteceu ao longo de um período** — quanto a empresa vendeu, quanto gastou e quanto sobrou.
A leitura segue uma lógica "de cima para baixo":
| Etapa | O que representa |
| ----------------------------- | ------------------------------------------------------------------- |
| **Receita** | Quanto a empresa faturou com suas atividades. |
| **(-) Custos** | Quanto custou produzir ou entregar o que foi vendido. |
| **= Lucro Bruto** | O que sobrou após os custos diretos. |
| **(-) Despesas Operacionais** | Gastos com vendas, administração e outros. |
| **= EBIT** | Resultado antes do resultado financeiro e tributos. |
| **(±) Resultado Financeiro** | Receitas e despesas com juros, câmbio e investimentos. |
| **(-) Impostos** | Imposto de renda e contribuição social. |
| **= Lucro Líquido** | O resultado final — quanto a empresa ganhou (ou perdeu) no período. |
::callout{color="info" icon="tabler:info-circle"}
Os dados são consolidados e os valores de custo e despesas são **negativos** por convenção contábil. Isso facilita a soma direta dos campos para chegar ao resultado final.
::
---
## Períodos e TTM
Você pode consultar dados anuais ou trimestrais. No modo anual, a API calcula automaticamente o **TTM (Trailing Twelve Months)** — uma visão acumulada dos últimos 12 meses, combinando os trimestres mais recentes. Isso permite acompanhar o desempenho atualizado da empresa sem precisar esperar a publicação do relatório anual.
| `period` | Ordem dos `statements` |
| ----------------- | ---------------------------------------------------------------------------- |
| `annual` (padrão) | **TTM** (se disponível), seguido dos exercícios anuais em ordem decrescente. |
| `quarterly` | Trimestres em ordem decrescente, sem TTM. |
---
## Requisição
Informe o ticker no formato `{fonte}:{símbolo}`.
:endpoint{endpoint="/v2/finance/income-statements?tickers=B3:PETR4"}
:request-example{endpoint="/v2/finance/income-statements?tickers=B3:PETR4"}
:stock-search
### Parâmetros
::field-group
:::field{required name="tickers" type="string"}
Ticker do ativo no formato `{fonte}:{símbolo}`. Para múltiplos ativos, separe por vírgula: `B3:PETR4,B3:VALE3`.
:::
:::field{name="period" type="string"}
Tipo de período fiscal: `annual` (padrão) ou `quarterly`.
:::
:::field{name="start_date" type="string"}
Data inicial para filtrar os dados (`yyyy-mm-dd`).
:::
:::field{name="end_date" type="string"}
Data final para filtrar os dados (`yyyy-mm-dd`).
:::
:::field{name="days_ago" type="number"}
Número de dias atrás a partir de hoje. Use `0` para dados do dia atual.
:::
::
---
## Resposta
:response-json{endpoint="/v2/finance/income-statements?tickers=B3:PETR4"}
### Campos
Os dados de cada ativo retornam no array `results`:
#### Ativo
| Campo | Tipo | Descrição | Exemplo |
| ----------- | ------------------------------------------------------------------------------------------------- | ----------------------------------------------- | ------------------------ |
| `ticker` | `string`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Ticker completo no formato `{fonte}:{símbolo}`. | B3\:PETR4 |
| `unit` | `string`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Unidade dos valores (`currency` para moeda). | currency |
| `currency` | `string`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Moeda dos valores. | BRL |
| `symbol` | `string`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Código de negociação do ativo. | PETR4 |
| `name` | `string`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Nome simplificado da empresa. | Petrobras |
| `full_name` | `string`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Razão social completa da empresa. | Petróleo Brasileiro S.A. |
#### Período
Cada item do array `statements` representa a DRE de um período:
| Campo | Tipo | Descrição | Exemplo |
| --------------- | ------------------------------------------------------------------------------------------------- | ------------------------------------------ | ---------- |
| `period_type` | `string`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Tipo do período: `annual` ou `quarterly`. | annual |
| `start_date` | `string`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Data de início do período. | 2024-01-01 |
| `end_date` | `string`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Data de encerramento do período. | 2024-12-31 |
| `fiscal_year` | `number`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Ano fiscal. | 2024 |
| `fiscal_period` | `string`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Período fiscal: `FY`, `TTM`, ou `Q1`–`Q4`. | FY |
#### Demonstração de Resultados
Os campos seguem a ordem natural da DRE, da receita ao lucro líquido:
| Campo | Tipo | Descrição |
| ------------------------------------- | ------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- |
| `revenue` | `number`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Receita líquida de vendas de bens e/ou serviços. |
| `cost_of_sales` | `number`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Custo dos bens e/ou serviços vendidos. |
| `gross_profit` | `number`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Lucro bruto (`revenue + cost_of_sales`). |
| `operating_expenses` | `number`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Total das despesas e receitas operacionais. |
| `selling_expenses` | `number`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Despesas com vendas e distribuição. |
| `general_and_administrative_expenses` | `number`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Despesas gerais e administrativas. |
| `impairment_losses` | `number`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Perdas por desvalorização de ativos (impairment). |
| `other_operating_income` | `number`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Outras receitas operacionais. |
| `other_operating_expenses` | `number`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Outras despesas operacionais. |
| `equity_method_result` | `number`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Resultado de equivalência patrimonial (investimentos em coligadas e controladas). |
| `ebit` | `number`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Resultado antes do resultado financeiro e dos tributos (EBIT). |
| `financial_result` | `number`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Resultado financeiro líquido. |
| `financial_income` | `number`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Receitas financeiras (juros, rendimentos de aplicações). |
| `financial_expenses` | `number`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Despesas financeiras (juros de empréstimos, variação cambial). |
| `income_before_taxes` | `number`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Resultado antes dos tributos sobre o lucro. |
| `income_tax` | `number`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Imposto de renda e contribuição social sobre o lucro. |
| `current_tax` | `number`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Impostos correntes (devidos no período). |
| `deferred_tax` | `number`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Impostos diferidos (diferenças temporárias). |
| `income_from_continuing_operations` | `number`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Resultado líquido das operações continuadas. |
| `income_from_discontinued_operations` | `number`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Resultado líquido de operações descontinuadas. |
| `net_income` | `number`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Lucro (ou prejuízo) líquido consolidado do período. |
| `net_income_to_shareholders` | `number`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Lucro atribuído aos acionistas controladores. |
| `net_income_to_non_controlling` | `number`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Lucro atribuído aos acionistas não controladores. |
| `basic_eps` | `number`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Lucro básico por ação ordinária (em R$/ação). |
| `diluted_eps` | `number`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Lucro diluído por ação ordinária (em R$/ação). |
::callout{color="info" icon="tabler:info-circle"}
**Lucro por ação (EPS):** os campos `basic_eps` e `diluted_eps` referem-se sempre às ações ordinárias (ON) e são expressos em Reais por ação. O EPS diluído considera o efeito potencial de opções de ações e instrumentos conversíveis.
::
::callout{color="warning" icon="tabler:alert-triangle"}
Campos com valor `null` indicam que a empresa não reportou o item no período consultado — por exemplo, nem todas as empresas possuem operações descontinuadas.
::
#### Fonte
O objeto `source` contém informações sobre a origem dos dados:
| Campo | Tipo | Descrição | Exemplo |
| -------------------------- | ------------------------------------------------------------------------------------------------- | ----------------------- | ----------------------------------------------------- |
| `source.symbol` | `string`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Código da fonte. | CVM |
| `source.name` | `string`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Nome da fonte. | Comissão de Valores Mobiliários |
| `source.full_name` | `string`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Nome completo da fonte. | Comissão de Valores Mobiliários |
| `source.url` | `string`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Site oficial. | {rel=""nofollow""} |
| `source.location.timezone` | `string`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Fuso horário. | America/Sao\_Paulo |
# Fluxo de Caixa
Acompanhe para onde o dinheiro vai — e de onde ele vem. O fluxo de caixa revela como uma empresa gera e utiliza seus recursos financeiros, separando as movimentações em três atividades: operacional, investimento e financiamento.
::callout
---
color: neutral
icon: tabler:key
to: https://hgbrasil.com/docs/guide/key
---
Para acessar os dados da API é necessário utilizar uma chave de integração e um plano compatível.
::
---
## O que é o Fluxo de Caixa?
Enquanto a [demonstração de resultados](https://hgbrasil.com/docs/finance/income-statements) mostra o lucro contábil, o fluxo de caixa mostra **o dinheiro que efetivamente entrou e saiu do caixa**. Uma empresa pode ter lucro no papel, mas estar queimando caixa — e vice-versa.
O demonstrativo é dividido em três seções:
| Seção | O que representa | Exemplo |
| ----------------- | --------------------------------------------------------------------- | -------------------------------------------------- |
| **Operacional** | Caixa gerado (ou consumido) pelas atividades do dia a dia da empresa. | Recebimento de clientes, pagamento de fornecedores |
| **Investimento** | Caixa usado para comprar ou vender ativos de longo prazo. | Compra de máquinas, aquisição de empresas |
| **Financiamento** | Caixa obtido ou devolvido a credores e acionistas. | Empréstimos, pagamento de dividendos |
A soma das três seções (mais o efeito cambial, quando aplicável) resulta na **variação líquida do caixa** no período.
::callout{color="info" icon="tabler:info-circle"}
Os dados utilizam o **método indireto** — partem do lucro líquido e ajustam por itens não monetários (como depreciação) e variações no capital de giro. Valores de saída de caixa são **negativos** por convenção.
::
---
## Períodos e TTM
Você pode consultar dados anuais ou trimestrais. No modo anual, a API calcula automaticamente o **TTM (Trailing Twelve Months)** — uma visão acumulada dos últimos 12 meses, combinando os trimestres mais recentes. Isso permite acompanhar a geração de caixa atualizada sem esperar o relatório anual.
| `period` | Ordem dos `statements` |
| ----------------- | ---------------------------------------------------------------------------- |
| `annual` (padrão) | **TTM** (se disponível), seguido dos exercícios anuais em ordem decrescente. |
| `quarterly` | Trimestres em ordem decrescente, sem TTM. |
---
## Requisição
Informe o ticker no formato `{fonte}:{símbolo}`.
:endpoint{endpoint="/v2/finance/cash-flows?tickers=B3:PETR4"}
:request-example{endpoint="/v2/finance/cash-flows?tickers=B3:PETR4"}
:stock-search
### Parâmetros
::field-group
:::field{required name="tickers" type="string"}
Ticker do ativo no formato `{fonte}:{símbolo}`. Para múltiplos ativos, separe por vírgula: `B3:PETR4,B3:VALE3`.
:::
:::field{name="period" type="string"}
Tipo de período fiscal: `annual` (padrão) ou `quarterly`.
:::
:::field{name="start_date" type="string"}
Data inicial para filtrar os dados (`yyyy-mm-dd`).
:::
:::field{name="end_date" type="string"}
Data final para filtrar os dados (`yyyy-mm-dd`).
:::
:::field{name="days_ago" type="number"}
Número de dias atrás a partir de hoje. Use `0` para dados do dia atual.
:::
::
---
## Resposta
:response-json{endpoint="/v2/finance/cash-flows?tickers=B3:PETR4"}
### Campos
Os dados de cada ativo retornam no array `results`:
#### Ativo
| Campo | Tipo | Descrição | Exemplo |
| ----------- | ------------------------------------------------------------------------------------------------- | ----------------------------------------------- | ------------------------ |
| `ticker` | `string`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Ticker completo no formato `{fonte}:{símbolo}`. | B3\:PETR4 |
| `unit` | `string`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Unidade dos valores (`currency` para moeda). | currency |
| `currency` | `string`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Moeda dos valores. | BRL |
| `symbol` | `string`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Código de negociação do ativo. | PETR4 |
| `name` | `string`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Nome simplificado da empresa. | Petrobras |
| `full_name` | `string`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Razão social completa da empresa. | Petróleo Brasileiro S.A. |
#### Período
Cada item do array `statements` representa o fluxo de caixa de um período:
| Campo | Tipo | Descrição | Exemplo |
| --------------- | ------------------------------------------------------------------------------------------------- | ------------------------------------------ | ---------- |
| `period_type` | `string`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Tipo do período: `annual` ou `quarterly`. | annual |
| `start_date` | `string`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Data de início do período. | 2024-01-01 |
| `end_date` | `string`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Data de encerramento do período. | 2024-12-31 |
| `fiscal_year` | `number`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Ano fiscal. | 2024 |
| `fiscal_period` | `string`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Período fiscal: `FY`, `TTM`, ou `Q1`–`Q4`. | FY |
#### Operating (Atividades Operacionais)
O objeto `operating` mostra o caixa gerado pelas atividades principais da empresa:
| Campo | Tipo | Descrição |
| ------------------------------- | ------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
| `total` | `number`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Caixa líquido das atividades operacionais. |
| `cash_from_operations` | `number`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Caixa gerado nas operações (antes de variações de capital de giro). Inclui lucro líquido e ajustes não monetários. |
| `depreciation_and_amortization` | `number`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Depreciação, amortização e exaustão — despesas não monetárias adicionadas de volta ao caixa. |
| `stock_based_compensation` | `number`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Remuneração baseada em ações (planos de stock options). |
| `changes_in_working_capital` | `number`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Variações nos ativos e passivos operacionais (capital de giro). |
| `other_operating` | `number`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Outros fluxos operacionais (impostos pagos, juros pagos e demais itens). |
::callout{color="warning" icon="tabler:alert-triangle"}
Os campos `depreciation_and_amortization` e `stock_based_compensation` podem retornar `null` quando não identificados com segurança para a empresa consultada.
::
#### Investing (Atividades de Investimento)
O objeto `investing` mostra o caixa usado em aquisições e vendas de ativos de longo prazo:
| Campo | Tipo | Descrição |
| ---------------------- | ------------------------------------------------------------------------------------------------- | ----------------------------------------------------------- |
| `total` | `number`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Caixa líquido das atividades de investimento. |
| `capital_expenditures` | `number`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Investimentos em ativos imobilizados e intangíveis (CapEx). |
::callout{color="warning" icon="tabler:alert-triangle"}
O campo `capital_expenditures` pode retornar `null` quando não identificado com segurança. O campo `total` sempre estará disponível e representa o fluxo completo de investimentos (incluindo aquisições, vendas de ativos e outros).
::
#### Financing (Atividades de Financiamento)
O objeto `financing` mostra o caixa obtido ou devolvido a credores e acionistas:
| Campo | Tipo | Descrição |
| ------------------- | ------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------- |
| `total` | `number`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Caixa líquido das atividades de financiamento. |
| `dividends_paid` | `number`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Dividendos e juros sobre capital próprio pagos (valor negativo). |
| `share_repurchases` | `number`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Recompra de ações em tesouraria (valor negativo). |
::callout{color="warning" icon="tabler:alert-triangle"}
Os campos `dividends_paid` e `share_repurchases` podem retornar `null` quando não identificados com segurança. O campo `total` sempre estará disponível e representa o fluxo completo de financiamentos (incluindo empréstimos, amortizações e outros).
::
#### Reconciliação
Campos na raiz do statement que conciliam a variação do caixa no período:
| Campo | Tipo | Descrição |
| ------------------------ | ------------------------------------------------------------------------------------------------- | ----------------------------------------------- |
| `exchange_rate_effect` | `number`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Variação cambial sobre caixa e equivalentes. |
| `net_change_in_cash` | `number`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Aumento ou redução líquida de caixa no período. |
| `beginning_cash_balance` | `number`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Saldo de caixa no início do período. |
| `ending_cash_balance` | `number`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Saldo de caixa no final do período. |
::callout{color="info" icon="tabler:info-circle"}
A reconciliação permite verificar a consistência: `operating.total + investing.total + financing.total + exchange_rate_effect = net_change_in_cash`, e `beginning_cash_balance + net_change_in_cash = ending_cash_balance`.
::
#### Fonte
O objeto `source` contém informações sobre a origem dos dados:
| Campo | Tipo | Descrição | Exemplo |
| -------------------------- | ------------------------------------------------------------------------------------------------- | ----------------------- | ----------------------------------------------------- |
| `source.symbol` | `string`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Código da fonte. | CVM |
| `source.name` | `string`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Nome da fonte. | Comissão de Valores Mobiliários |
| `source.full_name` | `string`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Nome completo da fonte. | Comissão de Valores Mobiliários |
| `source.url` | `string`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Site oficial. | {rel=""nofollow""} |
| `source.location.timezone` | `string`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Fuso horário. | America/Sao\_Paulo |
# Indicadores Econômicos
Acesse os principais indicadores econômicos do Brasil em um único endpoint. Índices de inflação, taxas de juros e indicadores setoriais — todos com séries históricas e dados oficiais do **Banco Central**, **IBGE** e **FGV**.
::callout
---
color: neutral
icon: tabler:key
to: https://hgbrasil.com/docs/guide/key
---
Para acessar os dados da API é necessário utilizar uma chave de integração.
::
## Disponibilidade
Confira quais indicadores estão disponíveis em cada plano:
| Indicador | ::div
---
className:
- text-center
---
Grátis
:: | ::div
---
className:
- text-center
---
Member
:: | ::div
---
className:
- text-center
---
Pro
:: | ::div
---
className:
- text-center
---
Startup
:: | ::div
---
className:
- text-center
---
Enterprise
:: |
| -------------------------------------------------- | :------------------------------------------------: | :------------------------------------------------: | :---------------------------------------------: | :-------------------------------------------------: | :----------------------------------------------------: |
| [`IBGE:IPCA`](https://hgbrasil.com/#ipca) | | | | | |
| [`IBGE:IPCA15`](https://hgbrasil.com/#ipca) | | | | | |
| [`IBGE:INPC`](https://hgbrasil.com/#ipca) | | | | | |
| [`FGV:IGPM`](https://hgbrasil.com/#igp) | | | | | |
| [`FGV:IGPDI`](https://hgbrasil.com/#igp) | | | | | |
| [`FGV:IGP10`](https://hgbrasil.com/#igp) | | | | | |
| [`FGV:INCC`](https://hgbrasil.com/#incc) | | | | | |
| [`FGV:INCCM`](https://hgbrasil.com/#incc) | | | | | |
| [`BCB:TR`](https://hgbrasil.com/#taxa-referencial) | | | | | |
| [`BCB:SELIC`](https://hgbrasil.com/#selic) | | | | | |
| [`BCB:SELICMETA`](https://hgbrasil.com/#selic) | | | | | |
| [`BCB:CDI`](https://hgbrasil.com/#cdi) | | | | | |
Confira os [nossos planos](https://hgbrasil.com/pricing).
---
## Indicadores de Inflação
Índices que medem a variação de preços ao longo do tempo. Essenciais para reajustes contratuais, correção monetária e análise econômica.
### IPCA
O **IPCA** (Índice de Preços ao Consumidor Amplo) é o principal indicador de inflação do Brasil, medido pelo IBGE. Ele acompanha a variação de preços de uma cesta de bens e serviços consumidos por famílias com renda de 1 a 40 salários mínimos.
:endpoint{endpoint="/v2/finance/indicators?tickers=IBGE:IPCA"}
| Ticker | Nome | Periodicidade |
| ------------- | ------------------------------------------------------------------------------------------------------------------------- | ------------- |
| `IBGE:IPCA` | **Índice de Preços ao Consumidor Amplo**:br*Famílias com renda de 1 a 40 salários mínimos.* | Mensal |
| `IBGE:IPCA15` | **Prévia do Índice de Preços ao Consumidor Amplo**:br*Aferido do dia 16 do mês anterior ao 15 do mês de referência.* | Mensal |
| `IBGE:INPC` | **Índice Nacional de Preços ao Consumidor**:br*Famílias com renda de 1 a 5 salários mínimos.* | Mensal |
### IGP
Os índices **IGP** da Fundação Getulio Vargas medem a inflação em diferentes camadas da economia: atacado, varejo e construção civil.
:endpoint{endpoint="/v2/finance/indicators?tickers=FGV:IGPM;FGV:IGPDI"}
| Ticker | Nome | Periodicidade |
| ----------- | ---------------------------------------------------------------------------------------------------------------- | ------------- |
| `FGV:IGPM` | **Índice Geral de Preços do Mercado**:br*Utilizado para reajuste de aluguéis e tarifas públicas.* | Mensal |
| `FGV:IGPDI` | **Índice Geral de Preços - Disponibilidade Interna**:br*Mede preços no atacado, varejo e construção civil.* | Mensal |
| `FGV:IGP10` | **Índice Geral de Preços - 10**:br*Prévia do IGP-M, coletado do dia 11 ao 10.* | Mensal |
### INCC
O **INCC** mede a variação dos custos da construção civil, incluindo materiais, mão de obra e equipamentos.
| Ticker | Nome | Periodicidade |
| ----------- | --------------------------------------------------------------------------------------------------------- | ------------- |
| `FGV:INCC` | **Índice Nacional de Custo da Construção**:br*Mede custos de materiais, mão de obra e equipamentos.* | Mensal |
| `FGV:INCCM` | **Índice Nacional de Custo da Construção - Mercado**:br*Foco nos preços praticados no mercado.* | Mensal |
### Taxa Referencial
| Ticker | Nome | Periodicidade |
| -------- | --------------------------------------------------------------------------------------- | ------------- |
| `BCB:TR` | **Taxa Referencial**:br*Utilizada na correção da poupança, FGTS e financiamentos.* | Mensal |
---
## Indicadores de Juros
Taxas de referência do mercado financeiro brasileiro. Fundamentais para precificação de ativos, cálculos de rendimento e análise de investimentos.
### SELIC
A **SELIC** é a taxa básica de juros da economia brasileira, sua meta é definida pelo Banco Central do Brasil, através do COPOM (Comitê de Política Monetária). Ela influencia todas as demais taxas de juros do país.
:endpoint{endpoint="/v2/finance/indicators?tickers=BCB:SELICMETA"}
| Ticker | Nome | Periodicidade |
| --------------- | -------------------------------------------------------------------------------- | ------------- |
| `BCB:SELICMETA` | **Meta da Taxa SELIC**:br*Objetivo definido pelo COPOM para a taxa básica.* | Diária |
| `BCB:SELIC` | **Taxa SELIC**:br*Taxa básica de juros da economia brasileira.* | Diária |
### CDI
O **CDI** (Certificado de Depósito Interbancário) é a taxa média dos empréstimos entre bancos e serve como principal referência para investimentos de renda fixa no Brasil.
| Ticker | Nome | Periodicidade |
| --------- | ----------------------------------------------------------------- | ------------- |
| `BCB:CDI` | **Taxa CDI**:br*Benchmark para investimentos de renda fixa.* | Diária |
---
## Requisição
Informe o ticker no formato `{fonte}:{símbolo}`.
:endpoint{endpoint="/v2/finance/indicators?tickers=IBGE:IPCA"}
:request-example{endpoint="/v2/finance/indicators?tickers=IBGE:IPCA"}
### Parâmetros
::field-group
:::field{required name="tickers" type="string"}
Ticker do indicador no formato `{fonte}:{símbolo}`. Para múltiplos indicadores, separe por vírgula: `IBGE:IPCA,FGV:IGPM`.
:::
:::field{name="start_date" type="string"}
Data inicial para filtrar a série histórica (`yyyy-mm-dd`).
:::
:::field{name="end_date" type="string"}
Data final para filtrar a série histórica (`yyyy-mm-dd`).
:::
:::field{name="date" type="string"}
Data específica para consultar um único período (`yyyy-mm-dd`).
:::
:::field{name="days_ago" type="number"}
Número de dias atrás a partir de hoje. Use `0` para dados do dia atual.
:::
::
---
## Resposta
:response-json{endpoint="/v2/finance/indicators?tickers=IBGE:IPCA"}
### Campos
Os dados retornam dentro de `results` como um array de indicadores:
| Campo | Tipo | Descrição |
| ----------------------- | ------------------------------------------------------------------------------------------------- | --------------------------------------------------- |
| `ticker` | `string`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Identificador único no formato `{fonte}:{símbolo}`. |
| `unit` | `string`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Unidade de medida (`percent`, etc). |
| `periodicity` | `string`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Periodicidade da série (`monthly`, `daily`). |
| `symbol` | `string`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Código do indicador. |
| `name` | `string`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Nome curto do indicador. |
| `full_name` | `string`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Nome completo do indicador. |
| `description` | `string`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Descrição detalhada do indicador. |
| `category` | `string`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Categoria (`Inflação`, `Juros`). |
| `summary` | `object`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Resumo com valores acumulados. |
| `summary.ytd` | `number`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Acumulado no ano (Year to Date). |
| `summary.last_12m` | `number`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Acumulado nos últimos 12 meses. |
| `series` | `array`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Série histórica com os valores do indicador. |
| `series[].period` | `string`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Período de referência. |
| `series[].publish_date` | `string`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Data de publicação (ISO 8601). |
| `series[].value` | `number`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Valor do indicador no período. |
| `source` | `object`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Informações sobre a fonte dos dados. |
| `source.symbol` | `string`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Código da fonte. |
| `source.name` | `string`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Nome da instituição. |
| `source.url` | `string`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Site oficial da fonte. |
---
## Fontes
| Símbolo | Instituição | Website |
| ------- | ----------------------------------------------- | ------------------------------------------------------------------ |
| `BCB` | Banco Central do Brasil | [bcb.gov.br](https://www.bcb.gov.br){rel=""nofollow""} |
| `IBGE` | Instituto Brasileiro de Geografia e Estatística | [ibge.gov.br](https://www.ibge.gov.br){rel=""nofollow""} |
| `FGV` | Fundação Getulio Vargas | [portal.fgv.br](https://portal.fgv.br){rel=""nofollow""} |
# Cotações Históricas
Acesse o histórico completo de cotações de ativos negociados na B3. Preços de abertura, fechamento, máxima, mínima e volume — tudo em um único endpoint!
::callout
---
color: neutral
icon: tabler:key
to: https://hgbrasil.com/docs/guide/key
---
Para acessar os dados da API é necessário utilizar uma chave de integração e um plano compatível.
::
---
## Dados OHLCV
A API retorna dados no formato **OHLCV** (Open, High, Low, Close, Volume), padrão amplamente utilizado no mercado financeiro para análise técnica e construção de gráficos de candlestick:
| Campo | Título | Descrição |
| -------- | ---------- | --------------------------------------------------- |
| `open` | Abertura | Preço do ativo no momento da abertura do período. |
| `high` | Máxima | Maior preço atingido pelo ativo durante o período. |
| `low` | Mínima | Menor preço atingido pelo ativo durante o período. |
| `close` | Fechamento | Preço do ativo no momento do fechamento do período. |
| `volume` | Volume | Quantidade total de ativos negociados no período. |
---
## Requisição
Informe o ticker no formato `{fonte}:{símbolo}`.
:endpoint{endpoint="/v2/finance/history?tickers=B3:PETR4"}
:request-example{endpoint="/v2/finance/history?tickers=B3:PETR4"}
:stock-search
### Parâmetros
::field-group
:::field{required name="tickers" type="string"}
Ticker do ativo no formato `{fonte}:{símbolo}`. Para múltiplos ativos, separe por vírgula: `B3:PETR4,B3:VALE3`.
:::
:::field{name="sample_by" type="string"}
Controla a granularidade do histórico retornado. Opções disponíveis:
- `1m`: 1 minuto
- `5m`: 5 minutos
- `15m`: 15 minutos
- `30m`: 30 minutos
- `1h`: 1 hora
- `2h`: 2 horas
- `1d`: 1 dia
- `1M`: 1 mês
:::
:::field{name="start_date" type="string"}
Data inicial para filtrar o histórico (`yyyy-mm-dd`).
:::
:::field{name="end_date" type="string"}
Data final para filtrar o histórico (`yyyy-mm-dd`).
:::
:::field{name="date" type="string"}
Data específica para consultar cotações de um único dia (`yyyy-mm-dd`).
:::
:::field{name="days_ago" type="number"}
Número de dias atrás a partir de hoje. Use `0` para cotações do dia atual.
:::
::
::callout{color="warning" icon="tabler:alert-triangle"}
Somente **um** tipo de filtro de data pode ser utilizado por requisição: intervalo (`start_date`/`end_date`), data específica (`date`) ou dias atrás (`days_ago`).
::
---
## Resposta
:response-json{endpoint="/v2/finance/history?tickers=B3:PETR4&days_ago=30"}
### Campos
Os dados de cada ativo retornam no array `results`:
#### Ativo
| Campo | Tipo | Descrição | Exemplo |
| ---------- | ------------------------------------------------------------------------------------------------- | ----------------------------------------------- | --------- |
| `ticker` | `string`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Ticker completo no formato `{fonte}:{símbolo}`. | B3\:PETR4 |
| `unit` | `string`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Unidade dos valores (`currency` para moeda). | currency |
| `currency` | `string`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Moeda dos valores. | BRL |
#### Cotações
Cada item do array `samples` representa uma cotação no período:
| Campo | Tipo | Descrição | Exemplo |
| -------- | ------------------------------------------------------------------------------------------------- | ---------------------------------- | --------------------------- |
| `date` | `string`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Data e hora do período (ISO 8601). | 2026-01-16T00:00:00.000000Z |
| `open` | `number`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Preço de abertura do período. | 31.95 |
| `close` | `number`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Preço de fechamento do período. | 32.04 |
| `high` | `number`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Preço máximo atingido no período. | 32.2 |
| `low` | `number`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Preço mínimo atingido no período. | 31.88 |
| `volume` | `number`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Volume total negociado no período. | 59717700.0 |
::callout{color="info" icon="tabler:info-circle"}
**Entendendo os preços**: Os valores de `open`, `close`, `high` e `low` são expressos na moeda indicada pelo campo `currency`. Para ativos da B3, os valores são em Reais (BRL).
::
#### Fonte
O objeto `source` contém informações sobre a bolsa de valores:
| Campo | Tipo | Descrição | Exemplo |
| -------------------------- | ------------------------------------------------------------------------------------------------- | ----------------------- | --------------------------------------------------- |
| `source.symbol` | `string`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Código da bolsa. | B3 |
| `source.name` | `string`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Nome da bolsa. | B3 |
| `source.full_name` | `string`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Nome completo da bolsa. | B3 S.A. - Brasil, Bolsa, Balcão |
| `source.url` | `string`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Site oficial da bolsa. | {rel=""nofollow""} |
| `source.location.timezone` | `string`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Fuso horário da bolsa. | America/Sao\_Paulo |
# Modo Kiosque
O **Modo Kiosque** da HG Finance é uma página de dashboard pública para exibição contínua em TVs, monitores corporativos e painéis. Ela exibe cotações em tempo quase real de ações, índices, moedas e criptoativos em um layout visual otimizado para leitura à distância, com atualização automática e relógio ao vivo.
::callout{color="neutral" icon="tabler:device-tv"}
O Modo Kiosque é uma página do site, não um endpoint de API. Configure-a diretamente pela URL.
::
## Acesso
```text
https://hgbrasil.com/finance/kiosk
```
## Parâmetros
::field-group
:::field{required name="key" type="string"}
Chave de API HG Brasil. Informada diretamente na URL — utilize uma chave com permissões de leitura.
:::
:::field{name="tickers" type="string"}
Lista de tickers separados por vírgula no formato `{fonte}:{símbolo}`. Padrão: `INDEXB3:IBOV,FOREX:USDBRL,FOREX:EURBRL,B3:PETR4`.
:::
:::field{name="refresh" type="integer"}
Intervalo de atualização automática em segundos. Padrão: `300` (5 minutos).
:::
::
## Exemplo
```text
https://hgbrasil.com/finance/kiosk?key=API_KEY&tickers=INDEXB3:IBOV,FOREX:USDBRL,FOREX:EURBRL,B3:PETR4&refresh=300
```
## Formato dos tickers
Utilize o formato `{fonte}:{símbolo}` para identificar cada ativo. Exemplos:
| Ativo | Ticker |
| --------------- | -------------- |
| Ibovespa | `INDEXB3:IBOV` |
| Dólar Americano | `FOREX:USDBRL` |
| Euro | `FOREX:EURBRL` |
| Petrobras PN | `B3:PETR4` |
| Vale ON | `B3:VALE3` |
Consulte a lista completa nas seções [Moedas](https://hgbrasil.com/docs/finance/currencies), [Ações e Fundos](https://hgbrasil.com/docs/finance/stocks), [Índices](https://hgbrasil.com/docs/finance/indices) e [Criptomoedas](https://hgbrasil.com/docs/finance/crypto).
## Atualização automática
A página atualiza os dados automaticamente conforme o intervalo definido em `refresh`. O padrão é de **5 minutos** (`300` segundos).
::note{icon="tabler:clock"}
As cotações da HG Finance são atualizadas em intervalos de 15 a 45 minutos durante o pregão. Definir um `refresh` inferior a esse intervalo não traz dados mais recentes — apenas consome requisições desnecessariamente.
::
## Recomendações para TVs
::tip
Abra a URL no modo tela cheia do navegador (`F11` no Chrome/Edge) para eliminar a barra de endereços e as abas.
::
::tip
Configure o navegador ou o sistema operacional para recarregar a aba periodicamente (a cada 12 a 24 horas) como prevenção a eventuais travamentos de longa duração.
::
::warning
Utilize uma chave com permissões mínimas necessárias. Evite compartilhar a mesma chave de projetos em produção, pois a `key` fica visível na barra de endereços.
::
# Lista de Ativos
Use a lista de ativos para descobrir quais tickers estão disponíveis antes de consultar cotações, histórico, dividendos, fundamentos ou demonstrativos financeiros.
Cada item retorna o identificador no formato `{fonte}:{símbolo}`, como `B3:PETR4`, `FOREX:USDBRL` ou `BINANCE:BTCBRL`.
::callout{color="info" icon="tabler:info-circle"}
Use sempre o campo `ticker` retornado por este endpoint nos outros endpoints do Finance.
::
## Requisição
Busque ativos por símbolo, nome simplificado ou razão social.
:endpoint{endpoint="/v2/finance/tickers?query=petr&sources=B3&sort=symbol&order=asc"}
:request-example{endpoint="/v2/finance/tickers?query=petr&sources=B3&sort=symbol&order=asc"}
### Parâmetros
::field-group
:::field{name="query" type="string"}
Busca textual por símbolo, nome simplificado ou razão social.
Ex.: `petr`, `petrobras`.
:::
:::field{name="sources" type="string"}
Lista de fontes separadas por vírgula. Ex.: `B3`, `FOREX`, `BINANCE` ou `B3,FOREX`.
:::
:::field{name="page" type="integer"}
Página da lista. Começa em `1` (padrão). A quantidade de itens por página depende do limite do seu plano.
:::
:::field{name="sort" type="string"}
Campo usado na ordenação principal. Padrão: `symbol`.
Aceita: `symbol`, `name`.
:::
:::field{name="order" type="string"}
Direção da ordenação. Padrão: `asc`.
Aceita: `asc`, `desc`.
:::
::
### Fontes
| Fonte | Descrição |
| --------- | ------------------------------------ |
| `B3` | Ativos negociados na B3. |
| `FOREX` | Pares de moedas internacionais. |
| `BINANCE` | Criptomoedas disponíveis na Binance. |
## Exemplos
### Buscar por nome
:endpoint{endpoint="/v2/finance/tickers?query=petrobras"}
### Filtrar por fonte
:endpoint{endpoint="/v2/finance/tickers?sources=FOREX"}
### Combinar fontes
:endpoint{endpoint="/v2/finance/tickers?sources=B3,FOREX&sort=name"}
## Resposta
Nos `results`, a API retorna a lista de ativos encontrados.
:response-json{endpoint="/v2/finance/tickers?query=petr&sources=B3&sort=symbol&order=asc"}
### Campos
#### Metadados
O objeto `metadata` informa o estado da requisição:
| Campo | Tipo | Descrição |
| ------------------ | -------------------------------------------------------------------------------------------------- | ------------------------------------ |
| `key_status` | `string`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Situação da chave de integração. |
| `cached` | `boolean`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Indica se a resposta veio do cache. |
| `response_time_ms` | `number`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Tempo de resposta em milissegundos. |
| `language` | `string`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Idioma usado nos textos da resposta. |
#### Ativo
Cada item de `results` representa um ativo disponível:
| Campo | Tipo | Descrição | Exemplo |
| -------------------------- | ------------------------------------------------------------------------------------------------- | --------------------------------------------- | ---------------------------------- |
| `ticker` | `string`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Identificador no formato `{fonte}:{símbolo}`. | B3\:PETR4 |
| `kind` | `string`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Tipo do ativo. | stock |
| `symbol` | `string`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Código de negociação do ativo. | PETR4 |
| `name` | `string`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Nome simplificado. | Petrobras |
| `full_name` | `string`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Nome completo ou razão social. | Petróleo Brasileiro S.A. Petrobras |
| `tax_id` | `string`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Documento fiscal do emissor, como CNPJ. | 33.000.167/0001-01 |
| `isin` | `string`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Código ISIN do ativo. | BRPETRACNPR6 |
| `classification.sector` | `string`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Setor de atuação. | Petróleo, Gás e Biocombustíveis |
| `classification.subsector` | `string`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Subsetor de atuação. | Petróleo, Gás e Biocombustíveis |
| `classification.segment` | `string`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Segmento de atuação. | Exploração, Refino e Distribuição |
| `logos.square_small` | `string`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | URL do logotipo quadrado pequeno. | https\://... |
| `logos.square_large` | `string`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | URL do logotipo quadrado grande. | https\://... |
| `source.symbol` | `string`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Código da fonte do ativo. | B3 |
Valores que não se aplicam a um tipo de ativo podem retornar como `null`.
#### Tipos de ativo
O campo `kind` pode retornar:
- `stock`: ação;
- `bdr`: BDR;
- `etf`: ETF;
- `fund`: fundo;
- `index`: índice;
- `crypto`: criptomoeda;
- `forex`: par de moedas.
## Próximo passo
Depois de encontrar o ticker desejado, use o valor de `ticker` em [cotações](https://hgbrasil.com/docs/finance/stocks), [histórico](https://hgbrasil.com/docs/finance/history), [dividendos](https://hgbrasil.com/docs/finance/dividends) ou nos endpoints de demonstrativos.
# Moedas
Você pode consultar a cotação de diversas moedas internacionais em relação ao Real (BRL), além de outros pares globais.
## Ativos
Consulte as moedas disponíveis e seus respectivos tickers para utilizar na consulta abaixo.
:stock-search{kind="currency"}
## Requisição
Para consultar um ou mais pares, informe os tickers no formato `{fonte}:{símbolo}` separados por vírgula. Por exemplo, para consultar **Dólar e Euro contra o Real**:
:endpoint{endpoint="/v2/finance/quotes?tickers=FOREX:USDBRL,FOREX:EURBRL"}
:request-example{endpoint="/v2/finance/quotes?tickers=FOREX:USDBRL,FOREX:EURBRL"}
### Parâmetros
::field-group
:::field{required name="tickers" type="string"}
Lista de pares no formato `{fonte}:{símbolo}` separados por vírgula. Ex.: `FOREX:USDBRL,FOREX:EURBRL`.
:::
:::field{name="sort" type="string"}
Ordena os resultados com base em um campo de retorno. Aceita: `value:asc`, `value:desc`, `volume:asc`, `volume:desc`, `change_percent:asc`, `change_percent:desc`.
:::
:::field{name="fields" type="string"}
Filtro de campos para reduzir o payload de retorno. Ex.: `ticker,quote.value,quote.change_percent`. *Em breve.*
:::
::
## Resposta
Nos `results`, a API retorna os dados da seguinte forma:
:response-json{endpoint="/v2/finance/quotes?tickers=FOREX:USDBRL,FOREX:EURBRL"}
### Campos
Os dados do ativo retornam dentro da lista `results` com os seguintes campos:
#### Ativo
| Campo | Descrição |
| -------------------------- | ------------------------------------------------------------------------ |
| `ticker` | Identificador completo no formato `{source}:{symbol}` |
| `kind` | Tipo do ativo: `stock`, `bdr`, `etf`, `fund`, `index`, `crypto`, `forex` |
| `unit` | Unidade dos valores (`currency`, `points` etc.) |
| `currency` | Moeda principal |
| `symbol` | Código de negociação |
| `name` | Nome simplificado |
| `full_name` | Nome completo ou razão social |
| `tax_id` | Documento fiscal do emissor (ex.: CNPJ) |
| `isin` | Código ISIN do ativo |
| `shares_outstanding` | Quantidade de ações em circulação |
| `classification.sector` | Setor de atuação |
| `classification.subsector` | Subsetor de atuação |
| `classification.segment` | Segmento de atuação |
| `logos.square_small` | URL do logotipo quadrado em tamanho pequeno |
| `logos.square_large` | URL do logotipo quadrado em tamanho grande |
| `related` | Lista de tickers relacionados no formato `{source}:{symbol}` |
#### Quote
| Campo | Descrição |
| ---------------------- | ------------------------------------------- |
| `quote.value` | Último valor negociado (moeda, pontos etc.) |
| `quote.change_value` | Variação absoluta no dia |
| `quote.change_percent` | Variação percentual no dia |
| `quote.market_cap` | Valor de mercado com base na cotação atual |
| `quote.updated_at` | Timestamp da cotação (ISO 8601) |
#### Market
| Campo | Descrição |
| ----------------------- | ------------------------------------------------------- |
| `market.is_open` | Indica se o mercado está aberto |
| `market.open_time` | Horário de abertura do mercado (ISO 8601) |
| `market.close_time` | Horário de fechamento do mercado (ISO 8601) |
| `market.previous_value` | Valor de referência anterior (ex.: fechamento anterior) |
| `market.open` | Valor de abertura do dia |
| `market.high` | Máxima do dia |
| `market.low` | Mínima do dia |
| `market.close` | Valor de fechamento do dia |
| `market.volume` | Volume negociado |
| `market.updated_at` | Timestamp da sessão (ISO 8601) |
#### Dividends
| Campo | Descrição |
| ----------------------------- | ------------------------------------------------------------- |
| `dividends.yield_12m_percent` | Dividend yield dos últimos 12 meses em percentual |
| `dividends.yield_12m_cash` | Dividend yield dos últimos 12 meses em valor absoluto (moeda) |
#### Fonte
| Campo | Descrição |
| -------------------------- | ---------------------- |
| `source.symbol` | Código da fonte |
| `source.name` | Nome da fonte |
| `source.full_name` | Nome completo da fonte |
| `source.url` | Site oficial |
| `source.location.timezone` | Fuso horário |
# Criptomoedas
Obtenha as cotações das principais **criptomoedas** do mercado em diversas moedas de referência.
## Ativos
Consulte as criptomoedas disponíveis e seus respectivos tickers para utilizar na consulta abaixo.
:stock-search{kind="crypto"}
## Requisição
Para consultar um ou mais ativos, informe os tickers no formato `{fonte}:{símbolo}` separados por vírgula. Por exemplo, para consultar **Bitcoin e Ethereum em Real**:
:endpoint{endpoint="/v2/finance/quotes?tickers=CRYPTO:BTCBRL,CRYPTO:ETHBRL"}
:request-example{endpoint="/v2/finance/quotes?tickers=CRYPTO:BTCBRL,CRYPTO:ETHBRL"}
### Parâmetros
::field-group
:::field{required name="tickers" type="string"}
Lista de ativos no formato `{fonte}:{símbolo}` separados por vírgula. Ex.: `CRYPTO:BTCBRL,CRYPTO:ETHBRL`.
:::
:::field{name="sort" type="string"}
Ordena os resultados com base em um campo de retorno. Aceita: `value:asc`, `value:desc`, `volume:asc`, `volume:desc`, `change_percent:asc`, `change_percent:desc`.
:::
:::field{name="fields" type="string"}
Filtro de campos para reduzir o payload de retorno. Ex.: `ticker,quote.value,quote.change_percent`. *Em breve.*
:::
::
## Resposta
Nos `results`, a API retorna os dados da seguinte forma:
:response-json{endpoint="/v2/finance/quotes?tickers=CRYPTO:BTCBRL"}
### Campos
Os dados do ativo retornam dentro da lista `results` com os seguintes campos:
#### Ativo
| Campo | Descrição |
| -------------------------- | ------------------------------------------------------------------------ |
| `ticker` | Identificador completo no formato `{source}:{symbol}` |
| `kind` | Tipo do ativo: `stock`, `bdr`, `etf`, `fund`, `index`, `crypto`, `forex` |
| `unit` | Unidade dos valores (`currency`, `points` etc.) |
| `currency` | Moeda principal |
| `symbol` | Código de negociação |
| `name` | Nome simplificado |
| `full_name` | Nome completo ou razão social |
| `tax_id` | Documento fiscal do emissor (ex.: CNPJ) |
| `isin` | Código ISIN do ativo |
| `shares_outstanding` | Quantidade de ações em circulação |
| `classification.sector` | Setor de atuação |
| `classification.subsector` | Subsetor de atuação |
| `classification.segment` | Segmento de atuação |
| `logos.square_small` | URL do logotipo quadrado em tamanho pequeno |
| `logos.square_large` | URL do logotipo quadrado em tamanho grande |
| `related` | Lista de tickers relacionados no formato `{source}:{symbol}` |
#### Quote
| Campo | Descrição |
| ---------------------- | ------------------------------------------- |
| `quote.value` | Último valor negociado (moeda, pontos etc.) |
| `quote.change_value` | Variação absoluta no dia |
| `quote.change_percent` | Variação percentual no dia |
| `quote.market_cap` | Valor de mercado com base na cotação atual |
| `quote.updated_at` | Timestamp da cotação (ISO 8601) |
#### Market
| Campo | Descrição |
| ----------------------- | ------------------------------------------------------- |
| `market.is_open` | Indica se o mercado está aberto |
| `market.open_time` | Horário de abertura do mercado (ISO 8601) |
| `market.close_time` | Horário de fechamento do mercado (ISO 8601) |
| `market.previous_value` | Valor de referência anterior (ex.: fechamento anterior) |
| `market.open` | Valor de abertura do dia |
| `market.high` | Máxima do dia |
| `market.low` | Mínima do dia |
| `market.close` | Valor de fechamento do dia |
| `market.volume` | Volume negociado |
| `market.updated_at` | Timestamp da sessão (ISO 8601) |
#### Dividends
| Campo | Descrição |
| ----------------------------- | ------------------------------------------------------------- |
| `dividends.yield_12m_percent` | Dividend yield dos últimos 12 meses em percentual |
| `dividends.yield_12m_cash` | Dividend yield dos últimos 12 meses em valor absoluto (moeda) |
#### Fonte
| Campo | Descrição |
| -------------------------- | ---------------------- |
| `source.symbol` | Código da fonte |
| `source.name` | Nome da fonte |
| `source.full_name` | Nome completo da fonte |
| `source.url` | Site oficial |
| `source.location.timezone` | Fuso horário |
# Bolsa de Valores
Você pode obter cotações da Bolsa de Valores (B3) como ações, BDRs, ETFs e FIIs listados no Ibovespa. Este endpoint fornece informações precisas e baixa latência, ideal para atualização frequente de valores.
## Ativos
Consulte as ações, FIIs, ETFs e BDRs disponíveis e seus respectivos tickers para utilizar na consulta abaixo.
:stock-search
## Requisição
Para consultar um ou mais ativos, informe os tickers no formato `{fonte}:{símbolo}` separados por vírgula. Por exemplo, para consultar a **Petrobras PN (PETR4)**:
:endpoint{endpoint="/v2/finance/quotes?tickers=B3:PETR4"}
:request-example{endpoint="/v2/finance/quotes?tickers=B3:PETR4"}
### Parâmetros
::field-group
:::field{required name="tickers" type="string"}
Lista de ativos no formato `{fonte}:{símbolo}` separados por vírgula. Ex.: `B3:PETR4,B3:VALE3`.
:::
:::field{name="sort" type="string"}
Ordena os resultados com base em um campo de retorno. Aceita: `value:asc`, `value:desc`, `volume:asc`, `volume:desc`, `change_percent:asc`, `change_percent:desc`.
:::
:::field{name="fields" type="string"}
Filtro de campos para reduzir o payload de retorno. Ex.: `ticker,quote.value,quote.change_percent`. *Em breve.*
:::
::
## Resposta
Nos `results`, a API retorna os dados da seguinte forma:
:response-json{endpoint="/v2/finance/quotes?tickers=B3:PETR4"}
### Campos
Os dados do ativo retornam dentro da lista `results` com os seguintes campos:
#### Ativo
| Campo | Descrição |
| -------------------------- | ------------------------------------------------------------------------ |
| `ticker` | Identificador completo no formato `{source}:{symbol}` |
| `kind` | Tipo do ativo: `stock`, `bdr`, `etf`, `fund`, `index`, `crypto`, `forex` |
| `unit` | Unidade dos valores (`currency`, `points` etc.) |
| `currency` | Moeda principal |
| `symbol` | Código de negociação |
| `name` | Nome simplificado |
| `full_name` | Nome completo ou razão social |
| `tax_id` | Documento fiscal do emissor (ex.: CNPJ) |
| `isin` | Código ISIN do ativo |
| `shares_outstanding` | Quantidade de ações em circulação |
| `classification.sector` | Setor de atuação |
| `classification.subsector` | Subsetor de atuação |
| `classification.segment` | Segmento de atuação |
| `logos.square_small` | URL do logotipo quadrado em tamanho pequeno |
| `logos.square_large` | URL do logotipo quadrado em tamanho grande |
| `related` | Lista de tickers relacionados no formato `{source}:{symbol}` |
#### Quote
| Campo | Descrição |
| ---------------------- | ------------------------------------------- |
| `quote.value` | Último valor negociado (moeda, pontos etc.) |
| `quote.change_value` | Variação absoluta no dia |
| `quote.change_percent` | Variação percentual no dia |
| `quote.market_cap` | Valor de mercado com base na cotação atual |
| `quote.updated_at` | Timestamp da cotação (ISO 8601) |
#### Market
| Campo | Descrição |
| ----------------------- | ------------------------------------------------------- |
| `market.is_open` | Indica se o mercado está aberto |
| `market.open_time` | Horário de abertura do mercado (ISO 8601) |
| `market.close_time` | Horário de fechamento do mercado (ISO 8601) |
| `market.previous_value` | Valor de referência anterior (ex.: fechamento anterior) |
| `market.open` | Valor de abertura do dia |
| `market.high` | Máxima do dia |
| `market.low` | Mínima do dia |
| `market.close` | Valor de fechamento do dia |
| `market.volume` | Volume negociado |
| `market.updated_at` | Timestamp da sessão (ISO 8601) |
#### Dividends
| Campo | Descrição |
| ----------------------------- | ------------------------------------------------------------- |
| `dividends.yield_12m_percent` | Dividend yield dos últimos 12 meses em percentual |
| `dividends.yield_12m_cash` | Dividend yield dos últimos 12 meses em valor absoluto (moeda) |
#### Fonte
| Campo | Descrição |
| -------------------------- | ---------------------- |
| `source.symbol` | Código da fonte |
| `source.name` | Nome da fonte |
| `source.full_name` | Nome completo da fonte |
| `source.url` | Site oficial |
| `source.location.timezone` | Fuso horário |
# Índices
Obtenha as cotações dos principais **índices** do mercado financeiro, como o Ibovespa, IFIX, S\&P 500 e outros índices globais relevantes. Também é possível consultar os ativos que compõem um índice.
## Ativos
Consulte os índices disponíveis e seus respectivos tickers para utilizar na consulta abaixo.
:stock-search{kind="index"}
### Principais índices
Alguns exemplos dos principais índices globais e como você deve solicitar no endpoint (utilizando o formato `{fonte}:{símbolo}`):
| Fonte | Ticker | Índice (Descrição) |
| ----------------- | -------------------- | ----------------------------------------------------- |
| **INDEXB3** | `INDEXB3:IBOV` | Ibovespa (B3 - Brasil) |
| **INDEXB3** | `INDEXB3:IFIX` | Índice de Fundos de Investimentos Imobiliários (IFIX) |
| **INDEXNASDAQ** | `INDEXNASDAQ:IXIC` | NASDAQ Composite (EUA) |
| **INDEXNYSE** | `INDEXNYSE:DJI` | Dow Jones Industrial Average (EUA) |
| **INDEXNYSE** | `INDEXNYSE:SPX` | S\&P 500 (EUA) |
| **INDEXTYO** | `INDEXTYO:N225` | Nikkei 225 (Tóquio, Japão) |
| **INDEXEURONEXT** | `INDEXEURONEXT:FCHI` | CAC 40 (Euronext Paris, França) |
## Requisição
Para consultar a cotação de um ou mais índices, informe os tickers no formato `{fonte}:{símbolo}` separados por vírgula. Por exemplo, para consultar **Ibovespa e NASDAQ**:
:endpoint{endpoint="/v2/finance/quotes?tickers=INDEXB3:IBOV,INDEXNASDAQ:IXIC"}
:request-example{endpoint="/v2/finance/quotes?tickers=INDEXB3:IBOV,INDEXNASDAQ:IXIC"}
### Parâmetros
::field-group
:::field{name="tickers" type="string"}
Lista de índices no formato `{fonte}:{símbolo}` separados por vírgula. Ex.: `INDEXB3:IBOV,INDEXNASDAQ:IXIC`. Não pode ser usado em conjunto com `components`.
:::
:::field{name="components" type="string"}
Retorna os ativos que compõem um índice em vez da cotação do próprio índice. Atualmente aceita apenas `INDEXB3:BVSP` e `INDEXB3:IBOV`. Requer plano Pro, equivalente ou superior. Não pode ser usado em conjunto com `tickers`.
:::
:::field{name="sort" type="string"}
Ordena os resultados com base em um campo de retorno. Aceita: `value:asc`, `value:desc`, `volume:asc`, `volume:desc`, `change_percent:asc`, `change_percent:desc`. Quando usado com `components`, a ordenação é aplicada antes do limite da página.
:::
:::field{name="page" type="integer"}
Página da lista retornada por `components`. Começa em `1` (padrão). A quantidade de itens por página depende do limite de ativos do seu plano.
:::
:::field{name="fields" type="string"}
Filtro de campos para reduzir o payload de retorno. Ex.: `ticker,quote.value,quote.change_percent`. *Em breve.*
:::
::
::callout{color="info" icon="tabler:info-circle"}
É obrigatório informar `tickers` **ou** `components`, mas não os dois ao mesmo tempo.
::
## Altas e Baixas do Ibovespa
Com o parâmetro `components` você consulta os ativos que compõem um índice e descobre, em uma única requisição, quem está puxando o índice para cima ou para baixo no dia.
### Maiores altas do dia
Combine `components` com `sort=change_percent:desc` para listar os papéis em maior alta:
:endpoint{endpoint="/v2/finance/quotes?components=INDEXB3:BVSP&sort=change_percent:desc"}
### Maiores baixas do dia
Inverta a ordenação para `change_percent:asc` e veja os papéis em maior queda:
:endpoint{endpoint="/v2/finance/quotes?components=INDEXB3:BVSP&sort=change_percent:asc"}
### Mais negociados
Ordene por volume para identificar os ativos com maior liquidez na sessão:
:endpoint{endpoint="/v2/finance/quotes?components=INDEXB3:BVSP&sort=volume:desc"}
### Composição completa
Para percorrer todos os componentes do índice, omita o `sort` e use `page` para navegar.
:endpoint{endpoint="/v2/finance/quotes?components=INDEXB3:BVSP&page=2"}
## Resposta
Nos `results`, a API retorna os dados da seguinte forma:
:response-json{endpoint="/v2/finance/quotes?tickers=INDEXB3:IBOV"}
### Campos
Os dados do ativo retornam dentro da lista `results` com os seguintes campos:
#### Ativo
| Campo | Descrição |
| -------------------------- | ------------------------------------------------------------------------ |
| `ticker` | Identificador completo no formato `{source}:{symbol}` |
| `kind` | Tipo do ativo: `stock`, `bdr`, `etf`, `fund`, `index`, `crypto`, `forex` |
| `unit` | Unidade dos valores (`currency`, `points` etc.) |
| `currency` | Moeda principal |
| `symbol` | Código de negociação |
| `name` | Nome simplificado |
| `full_name` | Nome completo ou razão social |
| `tax_id` | Documento fiscal do emissor (ex.: CNPJ) |
| `isin` | Código ISIN do ativo |
| `shares_outstanding` | Quantidade de ações em circulação |
| `classification.sector` | Setor de atuação |
| `classification.subsector` | Subsetor de atuação |
| `classification.segment` | Segmento de atuação |
| `logos.square_small` | URL do logotipo quadrado em tamanho pequeno |
| `logos.square_large` | URL do logotipo quadrado em tamanho grande |
| `related` | Lista de tickers relacionados no formato `{source}:{symbol}` |
#### Quote
| Campo | Descrição |
| ---------------------- | ------------------------------------------- |
| `quote.value` | Último valor negociado (moeda, pontos etc.) |
| `quote.change_value` | Variação absoluta no dia |
| `quote.change_percent` | Variação percentual no dia |
| `quote.market_cap` | Valor de mercado com base na cotação atual |
| `quote.updated_at` | Timestamp da cotação (ISO 8601) |
#### Market
| Campo | Descrição |
| ----------------------- | ------------------------------------------------------- |
| `market.is_open` | Indica se o mercado está aberto |
| `market.open_time` | Horário de abertura do mercado (ISO 8601) |
| `market.close_time` | Horário de fechamento do mercado (ISO 8601) |
| `market.previous_value` | Valor de referência anterior (ex.: fechamento anterior) |
| `market.open` | Valor de abertura do dia |
| `market.high` | Máxima do dia |
| `market.low` | Mínima do dia |
| `market.close` | Valor de fechamento do dia |
| `market.volume` | Volume negociado |
| `market.updated_at` | Timestamp da sessão (ISO 8601) |
#### Dividends
| Campo | Descrição |
| ----------------------------- | ------------------------------------------------------------- |
| `dividends.yield_12m_percent` | Dividend yield dos últimos 12 meses em percentual |
| `dividends.yield_12m_cash` | Dividend yield dos últimos 12 meses em valor absoluto (moeda) |
#### Fonte
| Campo | Descrição |
| -------------------------- | ---------------------- |
| `source.symbol` | Código da fonte |
| `source.name` | Nome da fonte |
| `source.full_name` | Nome completo da fonte |
| `source.url` | Site oficial |
| `source.location.timezone` | Fuso horário |
# Dividendos e Proventos
Acesse o histórico completo de proventos de ativos negociados na B3. Dividendos, JCP, bonificações, desdobramentos e outros eventos corporativos — tudo em um único endpoint!
::callout
---
color: neutral
icon: tabler:key
to: https://hgbrasil.com/docs/guide/key
---
Para acessar os dados da API é necessário utilizar uma chave de integração e um plano compatível.
::
---
## Tipos de Proventos
Diversos tipos de eventos corporativos são suportados. Cada tipo possui características específicas:
| Tipo | Título | Descrição |
| ----------------------------- | ---------------------------------- | ------------------------------------------------------------------- |
| `amortization` | Amortização | Devolução de parte do capital investido ao cotista. |
| `bonus_issue` | Bonificação | Distribuição de novos ativos sem custo ao acionista. |
| `dividend` | Dividendo | Parcela do lucro distribuída aos acionistas. |
| `full_share_redemption` | Resgate Total | Resgate completo dos ativos em renda variável. |
| `income` | Rendimento | Distribuição de rendimentos de fundos imobiliários e outros ativos. |
| `interest_on_equity` | Juros sobre Capital Próprio (JCP) | Remuneração ao acionista com benefício fiscal para a empresa. |
| `return_of_capital_in_cash` | Restituição de Capital em Dinheiro | Devolução de capital aos acionistas. |
| `return_of_capital_in_shares` | Restituição de Capital em Ativos | Devolução de capital em forma de ativos. |
---
## Requisição
Informe o ticker no formato `{fonte}:{símbolo}`.
:endpoint{endpoint="/v2/finance/dividends?tickers=B3:PETR4"}
:request-example{endpoint="/v2/finance/dividends?tickers=B3:PETR4"}
:stock-search
### Parâmetros
::field-group
:::field{required name="tickers" type="string"}
Ticker do ativo no formato `{fonte}:{símbolo}`. Para múltiplos ativos, separe por vírgula: `B3:PETR4,B3:VALE3`.
:::
:::field{name="start_date" type="string"}
Data inicial para filtrar proventos (`yyyy-mm-dd`). Filtra pelo campo `com_date`.
:::
:::field{name="end_date" type="string"}
Data final para filtrar proventos (`yyyy-mm-dd`). Filtra pelo campo `com_date`.
:::
:::field{name="date" type="string"}
Data específica para consultar proventos de um único dia (`yyyy-mm-dd`).
:::
:::field{name="days_ago" type="number"}
Número de dias atrás a partir de hoje. Use `0` para proventos do dia atual.
:::
::
---
## Resposta
:response-json{endpoint="/v2/finance/dividends?tickers=B3:PETR4"}
### Campos
Os dados de cada ativo retornam no array `results`:
#### Ativo
| Campo | Tipo | Descrição | Exemplo |
| ----------- | ------------------------------------------------------------------------------------------------- | ----------------------------------------------- | ------------------------ |
| `ticker` | `string`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Ticker completo no formato `{fonte}:{símbolo}`. | B3\:PETR4 |
| `unit` | `string`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Unidade dos valores (`currency` para moeda). | currency |
| `currency` | `string`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Moeda dos valores. | BRL |
| `symbol` | `string`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Código de negociação do ativo. | PETR4 |
| `name` | `string`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Nome simplificado da empresa. | Petrobras |
| `full_name` | `string`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Razão social completa da empresa. | Petróleo Brasileiro S.A. |
#### Consolidado
O objeto `summary` traz métricas consolidadas dos últimos 12 meses:
| Campo | Tipo | Descrição | Exemplo |
| ------------------- | ------------------------------------------------------------------------------------------------- | ------------------------------------------------------ | ------- |
| `yield_12m_percent` | `number`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Dividend Yield dos últimos 12 meses (%). | 1.12 |
| `yield_12m_cash` | `number`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Valor total distribuído por ação nos últimos 12 meses. | 1.38 |
#### Eventos
Cada item do array `events` representa um provento:
| Campo | Tipo | Descrição | Exemplo |
| --------------- | ------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ | ---------- |
| `type` | `string`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Tipo do provento (veja os [tipos de proventos](https://hgbrasil.com/#tipos-de-proventos)). | dividend |
| `category` | `string`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Categoria: `cash` (dinheiro) ou `stock` (ativos). | cash |
| `amount` | `number`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Valor por ação / cota após ajustes de grupamento e desdobramento. | 0.15 |
| `approval_date` | `string`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Data de aprovação do provento. | 2025-08-07 |
| `com_date` | `string`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Data de corte (data "com" direito ao provento). | 2025-08-14 |
| `payment_date` | `string`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Data de pagamento (pode ser `null` se não definida). | 2025-10-05 |
| `status` | `string`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Status: `not_approved` (não aprovado), `approved` (aprovado) ou `paid` (pago). | approved |
::callout{color="warning" icon="tabler:alert-triangle"}
Datas que com valor `null` indicam que a data ainda não foi definida pela empresa emissora.
::
#### Fonte
O objeto `source` contém informações sobre a bolsa de valores:
| Campo | Tipo | Descrição | Exemplo |
| -------------------------- | ------------------------------------------------------------------------------------------------- | ----------------------- | ---------------------------------------------------- |
| `source.symbol` | `string`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Código da bolsa. | B3 |
| `source.name` | `string`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Nome da bolsa. | B3 - Brasil, Bolsa, Balcão |
| `source.full_name` | `string`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Nome completo da bolsa. | B3 S.A. - Brasil, Bolsa, Balcão |
| `source.url` | `string`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Site oficial da bolsa. | {rel=""nofollow""} |
| `source.location.timezone` | `string`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Fuso horário da bolsa. | America/Sao\_Paulo |
# Grupamentos e Desdobramentos
Acesse o histórico completo de grupamentos e desdobramentos de ativos negociados na B3. Eventos corporativos que alteram a quantidade de ações em circulação — tudo em um único endpoint!
::callout
---
color: neutral
icon: tabler:key
to: https://hgbrasil.com/docs/guide/key
---
Para acessar os dados da API é necessário utilizar uma chave de integração e um plano compatível.
::
---
## Tipos de Eventos
A API retorna dois tipos de eventos corporativos:
| Tipo | Título | Descrição |
| --------------- | ------------- | ------------------------------------ |
| `split` | Desdobramento | Divisão de ações (ex.: 1 → 4). |
| `reverse_split` | Grupamento | Consolidação de ações (ex.: 10 → 1). |
---
## Requisição
Informe o ticker no formato `{fonte}:{símbolo}`.
:endpoint{endpoint="/v2/finance/splits?tickers=B3:TIMS3"}
:request-example{endpoint="/v2/finance/splits?tickers=B3:TIMS3"}
:stock-search
### Parâmetros
::field-group
:::field{required name="tickers" type="string"}
Ticker do ativo no formato `{fonte}:{símbolo}`. Para múltiplos ativos, separe por vírgula: `B3:TIMS3,B3:VALE3`.
:::
:::field{name="start_date" type="string"}
Data inicial para filtrar eventos (`yyyy-mm-dd`). Filtra pelo campo `ex_date`.
:::
:::field{name="end_date" type="string"}
Data final para filtrar eventos (`yyyy-mm-dd`). Filtra pelo campo `ex_date`.
:::
:::field{name="date" type="string"}
Data específica para consultar eventos de um único dia (`yyyy-mm-dd`).
:::
:::field{name="days_ago" type="number"}
Número de dias atrás a partir de hoje. Use `0` para eventos do dia atual.
:::
::
---
## Resposta
:response-json{endpoint="/v2/finance/splits?tickers=B3:TIMS3"}
### Campos
Os dados de cada ativo retornam no array `results`:
#### Ativo
| Campo | Tipo | Descrição | Exemplo |
| ----------- | ------------------------------------------------------------------------------------------------- | ----------------------------------------------- | --------- |
| `ticker` | `string`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Ticker completo no formato `{fonte}:{símbolo}`. | B3\:TIMS3 |
| `symbol` | `string`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Código de negociação do ativo. | TIMS3 |
| `name` | `string`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Nome simplificado da empresa. | TIM |
| `full_name` | `string`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Razão social completa da empresa. | TIM S.A. |
#### Eventos
Cada item do array `events` representa um evento de grupamento ou desdobramento:
| Campo | Tipo | Descrição | Exemplo |
| ---------------- | ------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------ | ------------------------- |
| `type` | `string`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Tipo do evento: `split` (desdobramento) ou `reverse_split` (grupamento). | split |
| `factor_from` | `number`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Quantidade de ações antes do evento. | 1 |
| `factor_to` | `number`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Quantidade de ações após o evento. | 4 |
| `ratio` | `number`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Fator multiplicador do evento (`factor_to / factor_from`). | 4.0 |
| `com_date` | `string`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Data de corte (última data em que o ativo será negociado com o preço vigente). | 2025-06-20T00:00:00-03:00 |
| `effective_date` | `string`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Data efetiva do evento (quando as ações são efetivamente convertidas). | 2025-06-10T00:00:00-03:00 |
| `status` | `string`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Status: `pending` (pendente) ou `confirmed` (confirmado). | confirmed |
::callout{color="info" icon="tabler:info-circle"}
**Entendendo o ratio**: Para desdobramentos (`split`), o `ratio` será maior que 1 (ex: 4.0 significa que cada ação virou 4). Para grupamentos (`reverse_split`), o `ratio` será menor que 1 (ex: 0.1 significa que cada 10 ações viraram 1).
::
::callout{color="warning" icon="tabler:alert-triangle"}
Datas com valor `null` indicam que a data ainda não foi definida.
::
#### Fonte
O objeto `source` contém informações sobre a bolsa de valores:
| Campo | Tipo | Descrição | Exemplo |
| -------------------------- | ------------------------------------------------------------------------------------------------- | ----------------------- | ---------------------------------------------------- |
| `source.symbol` | `string`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Código da bolsa. | B3 |
| `source.name` | `string`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Nome da bolsa. | B3 - Brasil, Bolsa, Balcão |
| `source.full_name` | `string`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Nome completo da bolsa. | B3 S.A. - Brasil, Bolsa, Balcão |
| `source.url` | `string`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Site oficial da bolsa. | {rel=""nofollow""} |
| `source.location.timezone` | `string`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Fuso horário da bolsa. | America/Sao\_Paulo |
# Dados Fundamentalistas
Tenha em um único endpoint uma visão completa de um ativo: cotação em tempo real, múltiplos de valuation, indicadores de endividamento, margens, rentabilidade e dividendos. É o ponto de partida ideal para análises fundamentalistas e triagem de ações.
::callout
---
color: neutral
icon: tabler:key
to: https://hgbrasil.com/docs/guide/key
---
Para acessar os dados da API é necessário utilizar uma chave de integração e um plano compatível.
::
---
## O que são Dados Fundamentalistas?
A análise fundamentalista busca responder a uma pergunta central: **quanto vale esta empresa e o preço atual faz sentido?**
Para responder, é preciso combinar informações de diversas fontes: cotação, balanço, resultados, fluxo de caixa e proventos, e transformá-las em indicadores comparáveis. Esse endpoint faz esse trabalho pesado por você, entregando um conjunto padronizado de métricas agrupadas por tema:
| Grupo | O que mede |
| ----------------- | --------------------------------------------------------------------------- |
| **Valuation** | Se o ativo está barato ou caro em relação aos seus resultados e patrimônio. |
| **Endividamento** | O nível de alavancagem e a capacidade de honrar obrigações. |
| **Margens** | A eficiência em transformar receita em lucro. |
| **Rentabilidade** | O retorno gerado sobre ativos, patrimônio e capital investido. |
| **Dividendos** | O retorno em proventos distribuídos nos últimos 12 meses. |
::callout{color="info" icon="tabler:info-circle"}
Os indicadores são calculados a partir dos dados consolidados de [balanço patrimonial](https://hgbrasil.com/docs/finance/balance-sheets), [demonstração de resultados](https://hgbrasil.com/docs/finance/income-statements), [fluxo de caixa](https://hgbrasil.com/docs/finance/cash-flows), [dividendos](https://hgbrasil.com/docs/finance/dividends) e da cotação mais recente.
::
---
## Períodos e TTM
Você pode consultar indicadores calculados com base em períodos anuais ou trimestrais. No modo anual, a API calcula automaticamente o **TTM (Trailing Twelve Months)** — uma visão acumulada dos últimos 12 meses — para refletir a situação mais atualizada da empresa sem esperar o fechamento do exercício anual.
| `period` | Ordem dos `statements` |
| ----------------- | ---------------------------------------------------------------------------- |
| `annual` (padrão) | **TTM** (se disponível), seguido dos exercícios anuais em ordem decrescente. |
| `quarterly` | Trimestres em ordem decrescente, sem TTM. |
---
## Requisição
Informe o ticker no formato `{fonte}:{símbolo}`.
:endpoint{endpoint="/v2/finance/fundamentals?tickers=B3:PETR4"}
:request-example{endpoint="/v2/finance/fundamentals?tickers=B3:PETR4"}
:stock-search
### Parâmetros
::field-group
:::field{required name="tickers" type="string"}
Ticker do ativo no formato `{fonte}:{símbolo}`. Para múltiplos ativos, separe por vírgula: `B3:PETR4,B3:VALE3`.
:::
:::field{name="fields" type="string"}
Filtro de campos de retorno para obter apenas o que precisa. Separe os caminhos por vírgula: `market.value,valuation.price_to_earnings_ratio`.
:::
:::field{name="period" type="string"}
Tipo de período fiscal: `annual` (padrão) ou `quarterly`.
:::
:::field{name="start_date" type="string"}
Data inicial para filtrar os dados (`yyyy-mm-dd`).
:::
:::field{name="end_date" type="string"}
Data final para filtrar os dados (`yyyy-mm-dd`).
:::
:::field{name="days_ago" type="number"}
Número de dias atrás a partir de hoje. Use `0` para dados do dia atual.
:::
::
---
## Resposta
:response-json{endpoint="/v2/finance/fundamentals?tickers=B3:PETR4"}
### Campos
Os dados de cada ativo retornam no array `results`:
#### Ativo
| Campo | Tipo | Descrição | Exemplo |
| -------------------- | ------------------------------------------------------------------------------------------------- | ---------------------------------------------------------- | ---------------------------------- |
| `ticker` | `string`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Ticker completo no formato `{fonte}:{símbolo}`. | B3\:PETR4 |
| `kind` | `string`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Tipo do ativo: `stock`, `bdr`, `etf`, `fund`, `index` etc. | stock |
| `unit` | `string`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Unidade dos valores (`currency`, `points` etc.). | currency |
| `currency` | `string`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Moeda dos valores. | BRL |
| `symbol` | `string`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Código de negociação do ativo. | PETR4 |
| `name` | `string`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Nome simplificado da empresa. | Petrobras |
| `full_name` | `string`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Razão social completa ou nome completo. | Petróleo Brasileiro S.A. Petrobras |
| `tax_id` | `string`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Documento fiscal do emissor (ex.: CNPJ). | 33.000.167/0001-01 |
| `isin` | `string`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Código ISIN do ativo. | BRPETRACNPR6 |
| `shares_outstanding` | `number`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Quantidade de ações em circulação. | 13044496930 |
#### Cotação
O objeto `quote` traz a cotação base para os cálculos e métricas de mercado:
| Campo | Tipo | Descrição | Exemplo |
| ---------------- | ------------------------------------------------------------------------------------------------- | ----------------------------------------------- | ------------------------- |
| `value` | `number`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Último valor negociado. | 47.90 |
| `change_value` | `number`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Variação absoluta no dia. | 1.29 |
| `change_percent` | `number`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Variação percentual no dia. | 2.77 |
| `market_cap` | `number`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Valor de mercado com base na cotação atual. | 624800000000 |
| `updated_at` | `string`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Timestamp de atualização da cotação (ISO 8601). | 2026-04-09T15:45:00-03:00 |
::callout{color="info" icon="tabler:info-circle"}
Devido ao grande volume de dados e complexidade dos cálculos, os resultados deste endpoint são cacheados por um período de até 30 minutos. Para utilizar a cotação com dados mais atualizados ou em tempo real, utilize o endpoint [`/v2/finance/quotes`](https://hgbrasil.com/docs/finance/stocks) e combine as informações conforme necessário.
::
#### Período
Cada item do array `statements` representa os dados de um período:
| Campo | Tipo | Descrição | Exemplo |
| --------------- | ------------------------------------------------------------------------------------------------- | ------------------------------------------------ | ---------- |
| `period_type` | `string`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Tipo do período: `annual`, `quarterly` ou `ttm`. | ttm |
| `start_date` | `string`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Data de início do período. | 2025-01-01 |
| `end_date` | `string`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Data de encerramento do período. | 2025-12-31 |
| `fiscal_year` | `number`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Ano fiscal. | 2025 |
| `fiscal_period` | `string`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Período fiscal: `FY`, `TTM` ou `Q1`–`Q4`. | TTM |
#### Dividendos
O objeto `dividends` traz o retorno em proventos do período:
| Campo | Tipo | Descrição | Exemplo |
| ---------------- | ------------------------------------------------------------------------------------------------- | -------------------------------------------- | ------- |
| `yield_percent` | `number`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Dividend Yield acumulado no período (%). | 13.28 |
| `yield_currency` | `number`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Valor total distribuído por ação no período. | 6.36 |
#### Indicadores
Os campos dos grupos `valuation`, `leverage`, `margins` e `profitability` detalham a saúde financeira da empresa:
##### Valuation
| Campo | Tipo | Descrição | Exemplo |
| ----------------------------------------- | ------------------------------------------------------------------------------------------------- | ---------------------------------------- | ------- |
| `valuation.price_to_earnings_ratio` | `number`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Múltiplo Preço/Lucro (P/L). | 5.65 |
| `valuation.peg_ratio` | `number`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | PEG Ratio. | 0.74 |
| `valuation.price_to_book_ratio` | `number`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Múltiplo Preço/Valor Patrimonial (P/VP). | 1.50 |
| `valuation.price_to_sales_ratio` | `number`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Múltiplo Preço/Receita. | 1.26 |
| `valuation.price_to_ebitda` | `number`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Múltiplo Preço/EBITDA. | 3.74 |
| `valuation.price_to_ebit` | `number`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Múltiplo Preço/EBIT. | 4.35 |
| `valuation.price_to_asset_ratio` | `number`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Múltiplo Preço/Ativos. | 0.56 |
| `valuation.price_to_current_assets_ratio` | `number`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Múltiplo Preço/Ativo Circulante. | 4.47 |
| `valuation.price_to_free_cash_flow_ratio` | `number`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Múltiplo Preço/Fluxo de Caixa Livre. | 6.02 |
| `valuation.ev_to_ebitda` | `number`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Múltiplo EV/EBITDA. | 3.98 |
| `valuation.ev_to_ebit` | `number`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Múltiplo EV/EBIT. | 4.62 |
##### Endividamento
| Campo | Tipo | Descrição | Exemplo |
| ----------------------------------- | ------------------------------------------------------------------------------------------------- | ------------------------------------------ | ------- |
| `leverage.current_ratio` | `number`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Índice de Liquidez Corrente. | 1.18 |
| `leverage.equity_to_asset_ratio` | `number`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Relação Patrimônio Líquido/Ativos. | 0.33 |
| `leverage.debt_to_equity_ratio` | `number`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Relação Dívida Líquida/Patrimônio Líquido. | 0.34 |
| `leverage.net_debt_to_ebitda_ratio` | `number`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Relação Dívida Líquida/EBITDA. | 0.24 |
| `leverage.net_debt_to_ebit_ratio` | `number`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Relação Dívida Líquida/EBIT. | 0.28 |
##### Margens
| Campo | Tipo | Descrição | Exemplo |
| ----------------------------- | ------------------------------------------------------------------------------------------------- | ------------------- | ------- |
| `margins.gross_profit_margin` | `number`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Margem bruta (%). | 50.62 |
| `margins.ebitda_margin` | `number`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Margem EBITDA (%). | 40.53 |
| `margins.ebit_margin` | `number`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Margem EBIT (%). | 35.27 |
| `margins.net_profit_margin` | `number`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Margem líquida (%). | 22.25 |
##### Rentabilidade e Eficiência
| Campo | Tipo | Descrição | Exemplo |
| ------------------------------------------ | ------------------------------------------------------------------------------------------------- | ------------------------------------------- | ------- |
| `profitability.asset_turnover_ratio` | `number`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Giro de ativos. | 0.70 |
| `profitability.return_on_assets` | `number`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Retorno sobre ativos (ROA) (%). | 8.73 |
| `profitability.return_on_equity` | `number`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Retorno sobre patrimônio líquido (ROE) (%). | 26.47 |
| `profitability.return_on_invested_capital` | `number`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Retorno sobre capital investido (ROIC) (%). | 18.92 |
| `profitability.return_on_capital_employed` | `number`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Retorno sobre capital empregado (ROCE) (%). | 22.47 |
#### Agentes
O array `agents` traz informações sobre os agentes relacionados ao ativo, como o agente de transferência (escriturador):
| Campo | Tipo | Descrição | Exemplo |
| ----------- | ------------------------------------------------------------------------------------------------- | ---------------------------------------- | ---------------------------------------------------------- |
| `role` | `string`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Papel do agente (ex.: `transfer_agent`). | transfer\_agent |
| `name` | `string`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Nome simplificado do agente. | Bradesco |
| `full_name` | `string`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Razão social do agente. | Banco Bradesco S.A. |
| `url` | `string`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | URL oficial do agente. | {rel=""nofollow""} |
#### Fonte
O objeto `source` contém informações sobre a bolsa de valores onde o ativo é negociado:
| Campo | Tipo | Descrição | Exemplo |
| -------------------------- | ------------------------------------------------------------------------------------------------- | ----------------------- | ---------------------------------------------------- |
| `source.symbol` | `string`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Código da bolsa. | B3 |
| `source.name` | `string`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Nome da bolsa. | B3 - Brasil, Bolsa, Balcão |
| `source.full_name` | `string`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Nome completo da bolsa. | B3 S.A. - Brasil, Bolsa, Balcão |
| `source.url` | `string`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Site oficial da bolsa. | {rel=""nofollow""} |
| `source.location.timezone` | `string`{.language-ts-type.shiki.shiki-themes.one-light.one-dark-pro.one-dark-pro lang="ts-type"} | Fuso horário da bolsa. | America/Sao\_Paulo |
# Previsão do Tempo
O **HG Weather** é uma API que fornece dados de previsão do tempo e condições climáticas atuais para uma cidade. É possível obter a cidade desejada de várias formas diferentes, como geolocalização, IP do usuário, busca por nome ou código.
::callout
---
color: neutral
icon: tabler:key
to: https://hgbrasil.com/docs/guide/key
---
Para acessar os dados da API é necessário utilizar uma chave de integração.
::
::note{icon="tabler:clock"}
Os dados meteorológicos são atualizados em intervalos de até 1 hora.
::
::tip
É possível indicar o idioma de retorno da API através do parâmetro `locale`. Estão disponíveis: `pt` (português, por padrão) e `en` (inglês).
::
## Requisição
Todas as requisições tem como base o seguinte endpoint:
:endpoint{endpoint="/weather"}
:request-example{endpoint="/weather"}
Veja como é fácil obter dados de previsão do tempo para uma cidade ou região específica. Você pode fazer isso de várias maneiras, como:
- [Obter pelo nome da cidade](https://hgbrasil.com/docs/weather/finding#obter-pelo-nome-da-cidade);
- [Obter pelo código WOEID da cidade](https://hgbrasil.com/docs/weather/finding#obter-pelo-c%C3%B3digo-woeid-da-cidade);
- [Obter por coordenadas de latitude e longitude](https://hgbrasil.com/docs/weather/finding#obter-por-coordenadas-de-latitude-e-longitude);
- [Obter por geolocalização IP](https://hgbrasil.com/docs/weather/finding#obter-por-geolocaliza%C3%A7%C3%A3o-ip).
## Resposta
Exemplo de resposta no formato `JSON`.
:response-json{endpoint="/weather"}
### Campos
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`.
# Localização
## Obter pelo nome da cidade
Você pode obter dados de previsão do tempo para uma cidade ou região específica utilizando o parâmetro `city_name` e com o nome da cidade desejada, por exemplo `city_name=Curitiba,PR`.
::warning
Quando possível, opte por utilizar o [método de busca por WOEID](https://hgbrasil.com/#obter-pelo-c%C3%B3digo-woeid-da-cidade), que é mais rápido e eficiente.
::
:endpoint{endpoint="/weather?city_name=Curitiba,PR"}
:request-example{endpoint="/weather?city_name=Curitiba,PR"}
## Obter pelo código WOEID da cidade
O **WOEID** (Where On Earth IDentifier) é um identificador único atribuído a cada localidade. Você pode obter dados de previsão do tempo para uma cidade ou região específica utilizando o parâmetro `woeid`.
:endpoint{endpoint="/weather?woeid=455827"}
:request-example{endpoint="/weather?woeid=455827"}
## Obter por coordenadas de latitude e longitude
Através dos parâmetros `lat` e `lon`, você pode obter dados de previsão do tempo para uma cidade ou região específica utilizando as coordenadas de latitude e longitude. Por exemplo, para São Paulo - SP, você pode utilizar `lat=-23.5505&lon=-46.6333`.
:endpoint{endpoint="/weather?lat=-23.5505&lon=-46.6333"}
:request-example{endpoint="/weather?lat=-23.5505&lon=-46.6333"}
## Obter por geolocalização IP
Alterativamente, você pode obter dados de previsão do tempo utilizando o parâmetro `user_ip`, onde é possível informar um endereço IP no formato `0.0.0.0` ou `remote` para que o sistema busque automaticamente a localização aproximada do usuário através do IP de quem está acessando a API.
:endpoint{endpoint="/weather?user_ip=remote"}
:request-example{endpoint="/weather?user_ip=remote"}
# Histórico
Você pode obter dados históricos de previsão do tempo utilizando parâmetros que filtram por data.
::tip
Esse método necessita de um plano que tenha suporte à dados históricos.
::
## Requisição
As requisições tem como base o seguinte endpoint:
:endpoint{endpoint="/weather/historical"}
Você pode obter dados históricos de previsão do tempo para uma localizadade através de um dos seguintes métodos:
- [Obter pelo nome da cidade](https://hgbrasil.com/docs/weather/finding#obter-pelo-nome-da-cidade);
- [Obter pelo código WOEID da cidade](https://hgbrasil.com/docs/weather/finding#obter-pelo-c%C3%B3digo-woeid-da-cidade);
- [Obter por coordenadas de latitude e longitude](https://hgbrasil.com/docs/weather/finding#obter-por-coordenadas-de-latitude-e-longitude);
- [Obter por geolocalização IP](https://hgbrasil.com/docs/weather/finding#obter-por-geolocaliza%C3%A7%C3%A3o-ip).
Para definir o intervalo de dados a serem consultados, você pode utilizar um dos seguintes métodos:
### Por intervalo de datas
::field-group
:::field{name="start_date" type="string"}
Data de inicio no formato `yyyy-mm-dd`.
:::
:::field{name="end_date" type="string"}
Data de término no formato `yyyy-mm-dd`.
:::
::
### Por uma data específica
::field-group
:::field{name="date" type="string"}
Data no formato `yyyy-mm-dd`.
:::
::
### Por número de dias atrás
::field-group
:::field{name="days_ago" type="number"}
Número de dias atrás.
:::
::
### Modos
Juntamente com uma das datas, é possível definir o modo de retorno dos dados:
::field-group
:::field{name="mode" type="string"}
As opções são `all`, `hourly` (apenas os registros por hora) ou `summary` (apenas o resumo).
:::
::
### Exemplo
Logo, você provavelmente irá utilizar um endpoint como o seguinte:
:endpoint{endpoint="/weather/historical?woeid=455903&days_ago=3&mode=all"}
:request-example{endpoint="/weather/historical?woeid=455903&days_ago=3&mode=all"}
## Resposta
:response-json{endpoint="/weather/historical?woeid=455903&days_ago=3&mode=all"}
# Ícones
Os ícones da **HG Weather** representam visualmente as condições climáticas retornadas pela API. Cada condição possui um código numérico (`condition_code`) e um identificador textual (`condition_slug`) que corresponde ao nome do arquivo de ícone.
## Como usar os ícones
Para exibir o ícone correspondente à condição climática, utilize o valor do campo `condition_slug` retornado pela API:
```text
https://assets.hgbrasil.com/weather/icons/conditions/{condition_slug}.svg
```
### Exemplo de uso
Se a API retornar `"condition_slug": "rain"`, você utilizaria o seguinte link para acessar o ícone:
```text
https://assets.hgbrasil.com/weather/icons/conditions/rain.svg
```
### Download dos ícones
Você também pode baixar todos os ícones das condições climáticas.
::u-button
---
href: https://assets.hgbrasil.com/weather/icons/hg-brasil-conditions-slugs.zip
icon: tabler:download
label: Fazer download
target: _blank
---
::
## Condições climáticas e seus ícones
Os ícones disponíveis representam uma variedade de condições climáticas, desde sol e chuva até tempestades e neve. Abaixo está uma tabela com os códigos, slugs, ícones e descrições correspondentes.
| `condition_code` | `condition_slug` | Ícone | Descrição |
| ---------------- | ---------------- | ----------------------------------------------------------------------------------------- | ---------------------------- |
| 0 | `storm` |  | Tempestade forte |
| 1 | `storm` |  | Tempestade tropical |
| 2 | `storm` |  | Furacão |
| 3 | `storm` |  | Tempestades severas |
| 4 | `storm` |  | Tempestades |
| 5 | `snow` |  | Misto de neve e chuva |
| 6 | `rain` |  | Misto chuva e gelo |
| 7 | `snow` |  | Misto neve e gelo |
| 8 | `fog` |  | Geada fina |
| 9 | `rain` |  | Chuviscos |
| 10 | `rain` |  | Congelamento chuva |
| 11 | `rain` |  | Alguns chuviscos |
| 12 | `rain` |  | Alguns chuviscos |
| 13 | `snow` |  | Neve baixa |
| 14 | `snow` |  | Tempestade com neve |
| 15 | `snow` |  | Ventania com neve |
| 16 | `snow` |  | Neve |
| 17 | `hail` |  | Granizo |
| 18 | `snow` |  | Gelo |
| 19 | `fog` |  | Poeira |
| 20 | `fog` |  | Neblina |
| 21 | `fog` |  | Tempestade de areia |
| 22 | `fog` |  | Fumacento |
| 23 | `cloud` |  | Vento acentuado |
| 24 | `cloud` |  | Ventania |
| 25 | `cloud` |  | Tempo frio |
| 26 | `cloud` |  | Tempo nublado |
| 27 | `clear_night` |  | Tempo limpo |
| 28 | `cloudly_day` |  | Tempo nublado |
| 29 | `cloudly_night` |  | Parcialmente nublado |
| 30 | `cloudly_day` |  | Parcialmente nublado |
| 31 | `clear_night` |  | Tempo limpo |
| 32 | `clear_day` |  | Ensolarado |
| 33 | `clear_night` |  | Estrelado |
| 34 | `cloudly_day` |  | Ensolarado com muitas nuvens |
| 35 | `hail` |  | Misto chuva e granizo |
| 36 | `clear_day` |  | Ar quente |
| 37 | `storm` |  | Tempestades isoladas |
| 38 | `storm` |  | Trovoadas dispersas |
| 39 | `storm` |  | Trovoadas dispersas |
| 40 | `rain` |  | Chuvas esparsas |
| 41 | `snow` |  | Pesados neve |
| 42 | `snow` |  | Chuviscos com neve |
| 43 | `snow` |  | Neve pesada |
| 44 | `cloudly_day` |  | Sol com poucas nuvens |
| 45 | `rain` |  | Chuva |
| 46 | `snow` |  | Queda de neve |
| 47 | `storm` |  | Tempestades isoladas |
| 48 | – | – | Serviço não disponível |
## Fases da Lua
A API do **HG Weather** também retorna informações sobre as fases da lua através do campo `moon_phase`. Assim como as condições climáticas, cada fase da lua possui um identificador textual que corresponde ao nome do arquivo de ícone.
### Fases disponíveis
| `moon_phase` | Ícone | Descrição |
| :---------------: | :------------------------------------------------------------------------------------: | :--------------- |
| `new` |  | Lua nova |
| `waxing_crescent` |  | Lua crescente |
| `first_quarter` |  | Quarto crescente |
| `waxing_gibbous` |  | Gibosa crescente |
| `full` |  | Lua cheia |
| `waning_gibbous` |  | Gibosa minguante |
| `last_quarter` |  | Quarto minguante |
| `waning_crescent` |  | Lua minguante |
### Como usar os ícones das fases da lua
Para exibir o ícone correspondente à fase da lua, utilize o valor do campo `moon_phase` retornado pela API:
```text
https://assets.hgbrasil.com/weather/icons/moon/{moon_phase}.png
```
### Exemplo de uso
Se a API retornar `"moon_phase": "full"`, você pode acessar o ícone através da URL:
```text
https://assets.hgbrasil.com/weather/icons/moon/full.png
```
### Download dos ícones das fases da lua
Você também pode baixar todos os ícones das fases da lua.
::u-button
---
href: https://assets.hgbrasil.com/weather/icons/hg-brasil-moon-phases.zip
icon: tabler:download
label: Fazer download
target: _blank
---
::
# Modo Kiosque
O **Modo Kiosque** da HG Weather é uma página de dashboard pública para exibição contínua em TVs, monitores corporativos e painéis. Ela exibe temperatura atual, condição climática, mínima e máxima do dia, detalhes meteorológicos e previsão dos próximos dias em um layout visual otimizado para leitura à distância, com atualização automática e relógio ao vivo.
::callout{color="neutral" icon="tabler:device-tv"}
O Modo Kiosque é uma página do site, não um endpoint de API. Configure-a diretamente pela URL.
::
## Acesso
```text
https://hgbrasil.com/weather/kiosk
```
## Parâmetros
::field-group
:::field{required name="key" type="string"}
Chave de API HG Brasil. Informada diretamente na URL — utilize uma chave com permissões de leitura.
:::
:::field{name="cities" type="string"}
Lista de cidades separadas por vírgula. Padrão: `São Paulo`.
:::
:::field{name="refresh" type="integer"}
Intervalo de atualização automática em segundos. Padrão: `3600` (1 hora).
:::
::
## Exemplo
```text
https://hgbrasil.com/weather/kiosk?key=API_KEY&cities=São Paulo,Ribeirão Preto,Curitiba&refresh=3600
```
## Formato das cidades
Utilize o parâmetro `cities` para informar uma ou mais cidades. Para múltiplas cidades, separe os nomes por vírgula. Exemplos:
| Exibição | Valor |
| ------------ | ----------------------------------- |
| Uma cidade | `São Paulo` |
| Duas cidades | `São Paulo,Curitiba` |
| Três cidades | `São Paulo,Ribeirão Preto,Curitiba` |
Tanto o nome acentuado quanto a versão sem acento são aceitos. `São Paulo` e `Sao Paulo` funcionam da mesma forma.
::note{icon="tabler:layout-grid"}
Com uma única cidade, o layout exibe a previsão em tela cheia com temperatura em destaque. Com duas ou mais cidades, o layout se organiza em grade responsiva, com cada cidade em um card independente.
::
## Atualização automática
A página atualiza os dados automaticamente conforme o intervalo definido em `refresh`. O padrão é de **1 hora** (`3600` segundos).
::note{icon="tabler:clock"}
Os dados meteorológicos são atualizados em intervalos de até 1 hora. Definir um `refresh` inferior a esse valor não traz dados mais recentes — apenas consome requisições desnecessariamente.
::
## Recomendações para TVs
::tip
Abra a URL no modo tela cheia do navegador (`F11` no Chrome/Edge) para eliminar a barra de endereços e as abas.
::
::tip
Para TVs em orientação horizontal, recomendamos até 3 cidades. Em orientação vertical, até 2 cidades, para manter boa legibilidade à distância.
::
::tip
Configure o navegador ou o sistema operacional para recarregar a aba periodicamente (a cada 12 a 24 horas) como prevenção a eventuais travamentos de longa duração.
::
::warning
Utilize uma chave com permissões mínimas necessárias. Evite compartilhar a mesma chave de projetos em produção, pois a `key` fica visível na barra de endereços.
::
# Localização por IP
A **HG IP Lookup** é uma API simples e objetiva que retorna, em uma única requisição, diversos dados acerca da localização do usuário. Esta informação é crucial para diversas aplicações – desde personalização de conteúdo até estratégias de marketing e segurança antifraude.
::card{title="IPv4 / IPv6" to="https://hgbrasil.com/docs/geo/ip"}
Localize geograficamente um endereço de IP.
::
::callout
---
color: neutral
icon: tabler:key
to: https://hgbrasil.com/docs/guide/key
---
Para acessar os dados da API é necessário utilizar uma chave de integração.
::
## Vantagens
Em uma só requisição, você pode obter:
- cidade, estado e país;
- informações detalhadas sobre o país como imagens da bandeira, capital e DDI;
- latitude e longitude da cidade encontrada;
- código WOEID para que seja simples uma consulta posterior de previsão do tempo usando o [HG Weather](https://hgbrasil.com/docs/weather).
# IPv4 / IPv6
## Requisição
Todas as requisições tem como base o seguinte endpoint:
:endpoint{endpoint="/geoip?address=8.8.8.8"}
:request-example{endpoint="/geoip?address=8.8.8.8"}
::field-group
:::field{name="address" type="string"}
Endereço do IP a ser localizado.
::::tip
Use `remote` ao invés do IP em requisições realizadas no lado cliente para buscar pelo IP do usuário.
::::
:::
::
::field{name="precision" type="boolean"}
Ativa o modo de alta precisão.
::
\::
::note{icon="tabler:clock"}
As informações de geolocalização são atualizadas em intervalos de até 1 dia.
::
## Resposta
:response-json{endpoint="/geoip?address=8.8.8.8"}