HG Finance Documentação

API de dados financeiros

Índice


Introdução

O HG Finance é uma API que fornece dados dados financeiros com o foco em trazer o máximo de informações em uma só requisição.
API fácil de implementar, com respostas e parâmetros objetivos, com bibliotecas em PHP, Ruby e JavaScript. (em breve)

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

Em uma só requisição, você pode obter:
- as posições das principais bolsas de valores como IBOVESPA, NASDAQ, CAC 40 e NIKKEI;
- a cotação de diversas moedas em relação ao real como Dólar (USD), Euro (EUR), Libra (GBP), Peso (ARS) e Bitcoin (BTC);
- cotação do bitcoin nas principais exchanges como Coinbase, Blockchain.info, BitStamp, FoxBit, OmniTrade, Mercado Bitcoin e XDEX;
- as principais taxas de juros do Brasil como CDI e Selic.

Tudo isso em uma só requisição.

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

Criar nova chave

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

Estrutura de dados

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

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

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

Exemplo de resposta JSON
{"by":"default","valid_key":true,"results":{"currencies":{"source":"BRL","USD":{"name":"Dollar","buy":3.74,"sell":null,"variation":0.98},"EUR":{"name":"Euro","buy":4.2289,"sell":null,"variation":1.131},"GBP":{"name":"Pound Sterling","buy":4.8347,"sell":null,"variation":1.331},"ARS":{"name":"Argentine Peso","buy":0.0964,"sell":null,"variation":0.521},"BTC":{"name":"Bitcoin","buy":15466.988,"sell":15466.988,"variation":8.068}},"stocks":{"IBOVESPA":{"name":"BM\u0026F BOVESPA","location":"Sao Paulo, Brazil","points":96273.047,"variation":-1.28},"NASDAQ":{"name":"NASDAQ Stock Market","location":"New York City, United States","points":7472.41,"variation":0.61},"CAC":{"name":"CAC 40","location":"Paris, French","variation":0.3},"NIKKEI":{"name":"Nikkei 225","location":"Tokyo, Japan","variation":1.82}},"available_sources":["BRL"],"bitcoin":{"blockchain_info":{"name":"Blockchain.info","format":["USD","en_US"],"last":3904.43,"buy":3904.43,"sell":3904.43,"variation":8.15},"coinbase":{"name":"Coinbase","format":["USD","en_US"],"last":3865.015,"variation":8.234},"bitstamp":{"name":"BitStamp","format":["USD","en_US"],"last":3870.31,"buy":3870.18,"sell":3869.08,"variation":8.468},"foxbit":{"name":"FoxBit","format":["BRL","pt_BR"],"last":14400.0,"variation":8.652},"mercadobitcoin":{"name":"Mercado Bitcoin","format":["BRL","pt_BR"],"last":14709.0,"buy":14550.80001,"sell":14699.92,"variation":8.959},"omnitrade":{"name":"OmniTrade","format":["BRL","pt_BR"],"last":14260.1,"buy":14150.0,"sell":14260.1,"variation":7.867},"xdex":{"name":"XDEX","format":["BRL","pt_BR"],"last":14550.0,"variation":7.886}},"taxes":[{"date":"2019-02-15","cdi":6.4,"selic":6.4,"daily_factor":1.0002462}]},"execution_time":0.0,"from_cache":true}

Autenticação e chave

A API do HG Finance é de acesso aberto, os dados em si são retornados mesmo sem ter um plano contratado.
Um plano apenas é exigido para obtenção de dados históricos.

A chave serve para liberar alguns dados, como taxas de juros, cotação em corretoras de bitcoin e para liberar o acesso exposto em websites por meio de headers CORS.

Recomendamos que sempre utilize uma chave, seus limites de consulta serão maiores do que o acesso sem chave.
Você pode consultar os limites de busca com e sem chave neste link.

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


Formatos de retorno

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

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

Aumente seus limites na API ou obtenha suporte

Vantagens de ser membro

A HG Brasil sempre prezou pela qualidade das APIs fornecidas juntamente ao acesso gratuito à comunidade desde 2009.
Nossa API tem acesso gratuito e sempre terá, porém você pode se tornar um assinante para obter um serviço ainda melhor!

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

Torne-se membro

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

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

Dados retornados:

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

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




Obter somente cotações de moedas e bolsas

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

Dados retornados:

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

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




Obter somente taxas CDI e SELIC

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

Dados retornados:

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

Requer chave: sim




Obtendo dados históricos

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

Conheça nossos planos

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

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



Você pode escolher a data por 3 tipos de filtros diferentes:
Por intervalo de datas:
  • start_date - data de inicio, string yyyy-mm-dd
  • end_date - data de término, string yyyy-mm-dd

Por data única:
  • date - data de inicio, string yyyy-mm-dd

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

Somente um filtro desses 3 acima pode ser escolhido.

Juntamente com uma das datas acima, você pode:

Obter todos os dados, ou somente um usando o filtro mode:
  • mode - string, disponíveis: all, currencies, stocks, bitcoin, taxes

Somente um filtro acima pode ser utilizado.

Exemplo de resposta
{"by":"days_ago","mode":"all","valid_key":true,"results":[],"execution_time":2.64,"from_cache":false}

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




Personalizando a resposta

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

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

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

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

Exemplo de resposta
{"bitcoin":{"blockchain_info":{"name":"Blockchain.info","format":["USD","en_US"],"last":3904.43,"buy":3904.43,"sell":3904.43,"variation":8.15},"coinbase":{"name":"Coinbase","format":["USD","en_US"],"last":3865.015,"variation":8.234},"bitstamp":{"name":"BitStamp","format":["USD","en_US"],"last":3870.31,"buy":3870.18,"sell":3869.08,"variation":8.468},"foxbit":{"name":"FoxBit","format":["BRL","pt_BR"],"last":14400.0,"variation":8.652},"mercadobitcoin":{"name":"Mercado Bitcoin","format":["BRL","pt_BR"],"last":14709.0,"buy":14550.80001,"sell":14699.92,"variation":8.959},"omnitrade":{"name":"OmniTrade","format":["BRL","pt_BR"],"last":14260.1,"buy":14150.0,"sell":14260.1,"variation":7.867},"xdex":{"name":"XDEX","format":["BRL","pt_BR"],"last":14550.0,"variation":7.886}}}

Dicas de boas práticas

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

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

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

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





© HG Brasil 2009 - 2019