1. HG Console
  2. HG Weather
  3. Documentação

HG Weather Documentação

API de previsão do tempo e dados climáticos

Documentação

Índice

Introdução

O HG Weather é uma API que fornece dados de previsão do tempo e condições climáticas atuais para uma cidade.
API fácil de implementar, com respostas e parâmetros objetivos, com bibliotecas em PHP, Ruby e JavaScript.

Você pode obter a cidade desejada de várias formas diferentes, como geolocalização, IP do usuário, busca por nome ou código.
Recomendamos que sempre use sua chave em todas as requisições.

Criar nova chave

O idioma de resposta da API pode ser configurado através do parâmetro locale.
Estão disponíveis: pt, en. (pt é o padrão)

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:

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

https://api.hgbrasil.com/weather

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.

  • temp - temperatura atual em ºC
  • date - data da consulta, em fuso horário do local
  • time - hora da consulta, em fuso horário do local
  • condition_code - código da condição de tempo atual veja a lista
  • description - descrição da condição de tempo atual no idioma escolhido
  • currently - retorna se está de dia ou de noite no idioma escolhido
  • cid - antigo identificador da cidade, pode não estar presente em alguns casos
  • city - nome da cidade seguido por uma vírgula (mantido para as libs antigas)
  • humidity - umidade atual em percentual
  • cloudiness - nebulosidade em percentual, de 0 a 100 NOVO
  • rain - volume de chuva em mm na última hora NOVO
  • wind_speedy - velocidade do vento em km/h
  • wind_direction - direção do vento em grau NOVO
  • wind_cardinal - direção do vento em ponto cardeal NOVO
  • sunrise - nascer do Sol em horário local da cidade
  • sunset - pôr do Sol em horário local da cidade
  • moon_phase - fase da Lua veja a lista NOVO
  • condition_slug - slug da condição de tempo atual veja a lista
  • city_name - nome da cidade
  • timezone - fuso horário da cidade
  • forecast - array com a previsão do tempo para outros dias
    • date - data da previsão dd/mm
    • weekday - dia da semana abreviado
    • cloudiness - nebulosidade em percentual, de 0 a 100 NOVO
    • rain - volume de chuva esperado NOVO
    • rain_probability - probabilidade de chuva em percentual, de 0 a 100 NOVO
    • wind_speedy - velocidade do vento em km/h NOVO
    • max - temperatura máxima em ºC
    • min - temperatura mínima em ºC
    • description - descrição da previsão
    • condition - slug da condição veja a lista

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

Exemplo de resposta JSON
{"by":"woeid","valid_key":true,"results":{"temp":20,"date":"26/04/2024","time":"21:07","condition_code":"29","description":"Parcialmente nublado","currently":"noite","cid":"","city":"São Paulo, SP","img_id":"29n","humidity":91,"cloudiness":20.0,"rain":0.0,"wind_speedy":"3.09 km/h","wind_direction":130,"wind_cardinal":"SE","sunrise":"06:24 am","sunset":"05:43 pm","moon_phase":"waning_gibbous","condition_slug":"cloudly_night","city_name":"São Paulo","timezone":"-03:00","forecast":[{"date":"26/04","weekday":"Sex","max":28,"min":20,"cloudiness":10.0,"rain":0.0,"rain_probability":0,"wind_speedy":"3.68 km/h","description":"Tempo limpo","condition":"clear_day"},{"date":"27/04","weekday":"Sáb","max":31,"min":20,"cloudiness":40.0,"rain":0.0,"rain_probability":0,"wind_speedy":"5.2 km/h","description":"Parcialmente nublado","condition":"cloud"},{"date":"28/04","weekday":"Dom","max":32,"min":23,"cloudiness":1.0,"rain":0.0,"rain_probability":0,"wind_speedy":"5.2 km/h","description":"Tempo limpo","condition":"clear_day"},{"date":"29/04","weekday":"Seg","max":31,"min":21,"cloudiness":1.0,"rain":0.38,"rain_probability":42,"wind_speedy":"4.66 km/h","description":"Chuvas esparsas","condition":"rain"},{"date":"30/04","weekday":"Ter","max":32,"min":21,"cloudiness":0.0,"rain":0.0,"rain_probability":0,"wind_speedy":"3.6 km/h","description":"Tempo limpo","condition":"clear_day"},{"date":"01/05","weekday":"Qua","max":31,"min":21,"cloudiness":0.0,"rain":0.0,"rain_probability":0,"wind_speedy":"4.74 km/h","description":"Tempo limpo","condition":"clear_day"},{"date":"02/05","weekday":"Qui","max":32,"min":22,"cloudiness":0.0,"rain":0.0,"rain_probability":0,"wind_speedy":"6.24 km/h","description":"Tempo limpo","condition":"clear_day"},{"date":"03/05","weekday":"Sex","max":27,"min":20,"cloudiness":62.0,"rain":0.48,"rain_probability":24,"wind_speedy":"6.78 km/h","description":"Chuvas esparsas","condition":"rain"},{"date":"04/05","weekday":"Sáb","max":32,"min":19,"cloudiness":0.0,"rain":0.0,"rain_probability":0,"wind_speedy":"4.73 km/h","description":"Tempo limpo","condition":"clear_day"},{"date":"05/05","weekday":"Dom","max":32,"min":21,"cloudiness":1.0,"rain":0.0,"rain_probability":0,"wind_speedy":"5.41 km/h","description":"Tempo limpo","condition":"clear_day"}],"cref":"7685af","latitude":-23.5329,"longitude":-46.6395},"execution_time":0.0,"from_cache":true}

Autenticação e chave

A API do HG Weather é de acesso aberto, os dados em si são retornados sem utilizar uma chave ou mesmo ter um plano contratado.

A chave serve para liberar recursos de busca mais avançados, como busca por geolocalização ou nome da cidade, aumentar os limites de consulta 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.

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

Galeria de Imagens

Fornecemos imagens que podem ser utilizadas para representar os dados que são retornados na API.

Ícones de Condição Climática

tempestade neve granizo chuva neblina dia limpo noite limpa nublado nublado de dia nublado de noite

Basta você substituir o retorno do condition_slug no nome da imagem.
Exemplo:

https://assets.hgbrasil.com/weather/icons/conditions/rain.svg
  ou   Fazer download das imagens

Fases da Lua

Lua nova Lua crescente Quarto crescente Gibosa crescente Lua cheia Gibosa minguante Quarto minguante Lua minguante

Basta você substituir o retorno do moon_phase no nome da imagem.
Exemplo:

https://assets.hgbrasil.com/weather/icons/moon/full.png
  ou   Fazer download das imagens

Formatos de retorno

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

https://api.hgbrasil.com/weather?format=json-cors&key=SUA-CHAVE
Formatos disponíveis
  • json - retorno em JSON, padrão
  • json-cors - retorno em JSON com headers CORS, chave exposta requerida
  • php-serialize - serialização do PHP (antigo formato da API)
  • debug - JSON visual para humanos, apenas para testes, não utilizar em produção

Aumente seus limites na API ou obtenha suporte

 

Conheça as vantagens de ser membro da API

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

Quero conhecer
Chamada para API

Obter cidade por código WOEID ou CID

Com este método, informamos os dados de tempo no código WOEID (Where On Earth IDentifier, identificador onde na terra em inglês) de cidade. CID ainda funciona porém foi descontinuado.

Parâmetro de consulta: woeid
Requer chave: não

https://api.hgbrasil.com/weather?woeid=455827


Você pode buscar o código de sua cidade nas ferramentas do HG Weather.

Buscar cidade

Obter cidade por geolocalização

Com este método, retornamos a cidade baseada nas coordenadas de seu usuário, o próprio sistema se encarrega de salvar os dados associando a geolocalização com o IP do usuário, tornando possível novas consultas no futuro, sem informar as coordenadas. Não se preocupe, esses dados nunca são exibidos no retorno da API.

Requer chave: sim

Parâmetros
  • lat - float com a latitude
  • lon - float com a longitude
  • user_ip - IP de seu usuário exemplo 000.000.000.000 ou envie remote para o sistema obter o IP com base no cliente.
https://api.hgbrasil.com/weather?key=SUA-CHAVE&lat=-23.682&lon=-46.875&user_ip=remote


IP do usuário é necessário para cache do sistema, em uma consulta de localicação de IP, a cidade será salva automáticamente com os dados de geocoordenadas.

Obter cidade por localicação de IP

Com este método, informamos os dados de tempo baseado na localização por IP, o sistema busca uma localização aproximada do seu usuário pelo endereço IP.

Caso o mesmo IP tenha feito uma consulta via geolocalização, o sistema utilizará esse dado salvo anteriormente.
A busca pode não ser exata, podendo variar de acordo com a região.

Requer chave: sim

Parâmetros
  • user_ip - IP de seu usuário exemplo 000.000.000.000 ou envie remote para o sistema obter o IP com base no cliente.
https://api.hgbrasil.com/weather?key=SUA-CHAVE&user_ip=remote

Obter cidade por nome

Com este método, informamos os dados de tempo baseado no nome da cidade. Quando for sempre a mesma cidade, considere utilizar a busca por WOEID.

Parâmetro de consulta: city_name
Requer chave: sim

https://api.hgbrasil.com/weather?key=SUA-CHAVE&city_name=Campinas,SP


Recomentamos que o nome da cidade seja codificado usando URL encode.

Obtendo histórico de dados meteorológicos

Novidade!

Este endpoint acabou de sair do forno!

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 HG Weather.

Conheça nossos planos

Requer chave: sim
Cidades disponíveis: somente cidades brasileiras
Requer plano: sim (com suporte à dados históricos HG Weather)

Para buscar por uma cidade, você pode utilizar as mesmas formas de busca para cidades da API de dados atuais:

Somente um é necessário.

  • woeid - código da cidade, encontrar código
  • city_name - string com o nome da cidade
  • lat / lon - float com a latitude e longitude da cidade
  • user_ip - IP de seu usuário exemplo 000.000.000.000 ou envie remote para o sistema obter o IP com base no cliente

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

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


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

Por data única:
  • date - data de inicio, string yyyy-mm-dd ou yesterday para obter o dia anterior

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

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

Juntamente com uma das datas acima, você pode:

Obter todos os dados, ou somente um usando o filtro mode:
  • mode - string
    - all: retorna todos os dados históricos
    - hourly: retorna somente os registros por hora
    - summary: retorna somente o resumo

Somente um filtro acima pode ser utilizado.

Exemplo de resposta
{"by":"days_ago","mode":"all","valid_key":true,"city_woeid":455827,"results":{"2024-04-25":{"city":"São Paulo, SP","sunrise":"06:24 am","sunset":"05:44 pm","temp":{"max":26.0,"min":20.0,"avg":21.8},"humidity":{"max":92.0,"min":70.0,"avg":82.7},"cloudiness":{"max":100.0,"min":0.0,"avg":72.1},"rain":{"max":0.3,"min":0.0,"avg":0.0},"wind_speedy":{"max":5.7,"min":2.1,"avg":4.1},"hourly":{"00:16":{"temp":20,"humidity":92,"cloudiness":100.0,"rain":0.0,"wind_speedy":"4.63 km/h","wind_direction":160,"condition_code":"28","condition_slug":"cloudly_night"},"01:06":{"temp":21,"humidity":88,"cloudiness":100.0,"rain":0.0,"wind_speedy":"4.02 km/h","wind_direction":147,"condition_code":"28","condition_slug":"cloudly_night"},"02:07":{"temp":21,"humidity":86,"cloudiness":100.0,"rain":0.0,"wind_speedy":"5.14 km/h","wind_direction":150,"condition_code":"28","condition_slug":"cloudly_night"},"03:07":{"temp":21,"humidity":88,"cloudiness":75.0,"rain":0.0,"wind_speedy":"3.6 km/h","wind_direction":140,"condition_code":"28","condition_slug":"cloudly_night"},"04:07":{"temp":20,"humidity":89,"cloudiness":75.0,"rain":0.0,"wind_speedy":"3.6 km/h","wind_direction":140,"condition_code":"28","condition_slug":"cloudly_night"},"05:07":{"temp":21,"humidity":87,"cloudiness":100.0,"rain":0.0,"wind_speedy":"2.57 km/h","wind_direction":80,"condition_code":"28","condition_slug":"cloudly_night"},"06:08":{"temp":21,"humidity":87,"cloudiness":100.0,"rain":0.0,"wind_speedy":"2.06 km/h","wind_direction":100,"condition_code":"28","condition_slug":"cloudly_night"},"07:08":{"temp":20,"humidity":83,"cloudiness":75.0,"rain":0.0,"wind_speedy":"3.09 km/h","wind_direction":110,"condition_code":"28","condition_slug":"cloudly_day"},"08:09":{"temp":21,"humidity":79,"cloudiness":0.0,"rain":0.0,"wind_speedy":"3.09 km/h","wind_direction":80,"condition_code":"27","condition_slug":"clear_day"},"09:13":{"temp":22,"humidity":75,"cloudiness":40.0,"rain":0.0,"wind_speedy":"3.6 km/h","wind_direction":80,"condition_code":"29","condition_slug":"cloud"},"10:14":{"temp":23,"humidity":75,"cloudiness":0.0,"rain":0.0,"wind_speedy":"4.02 km/h","wind_direction":126,"condition_code":"27","condition_slug":"clear_day"},"11:16":{"temp":25,"humidity":70,"cloudiness":75.0,"rain":0.0,"wind_speedy":"3.6 km/h","wind_direction":140,"condition_code":"28","condition_slug":"cloudly_day"},"12:10":{"temp":24,"humidity":75,"cloudiness":75.0,"rain":0.0,"wind_speedy":"4.63 km/h","wind_direction":100,"condition_code":"28","condition_slug":"cloudly_day"},"13:06":{"temp":25,"humidity":70,"cloudiness":40.0,"rain":0.0,"wind_speedy":"4.02 km/h","wind_direction":183,"condition_code":"29","condition_slug":"cloud"},"14:06":{"temp":26,"humidity":71,"cloudiness":75.0,"rain":0.0,"wind_speedy":"5.14 km/h","wind_direction":150,"condition_code":"28","condition_slug":"cloudly_day"},"15:07":{"temp":25,"humidity":72,"cloudiness":75.0,"rain":0.0,"wind_speedy":"5.66 km/h","wind_direction":160,"condition_code":"28","condition_slug":"cloudly_day"},"16:07":{"temp":23,"humidity":78,"cloudiness":75.0,"rain":0.13,"wind_speedy":"5.66 km/h","wind_direction":180,"condition_code":"40","condition_slug":"rain"},"17:06":{"temp":22,"humidity":83,"cloudiness":75.0,"rain":0.28,"wind_speedy":"5.14 km/h","wind_direction":160,"condition_code":"40","condition_slug":"rain"},"18:06":{"temp":21,"humidity":85,"cloudiness":75.0,"rain":0.0,"wind_speedy":"4.63 km/h","wind_direction":160,"condition_code":"28","condition_slug":"cloudly_night"},"19:07":{"temp":21,"humidity":88,"cloudiness":100.0,"rain":0.0,"wind_speedy":"4.63 km/h","wind_direction":150,"condition_code":"28","condition_slug":"cloudly_night"},"20:06":{"temp":20,"humidity":90,"cloudiness":75.0,"rain":0.0,"wind_speedy":"4.63 km/h","wind_direction":150,"condition_code":"28","condition_slug":"cloudly_night"},"21:06":{"temp":20,"humidity":91,"cloudiness":75.0,"rain":0.0,"wind_speedy":"4.63 km/h","wind_direction":160,"condition_code":"28","condition_slug":"cloudly_night"},"22:07":{"temp":20,"humidity":92,"cloudiness":75.0,"rain":0.0,"wind_speedy":"3.6 km/h","wind_direction":150,"condition_code":"28","condition_slug":"cloudly_night"},"23:06":{"temp":20,"humidity":91,"cloudiness":75.0,"rain":0.0,"wind_speedy":"3.6 km/h","wind_direction":150,"condition_code":"28","condition_slug":"cloudly_night"}}}},"execution_time":0.72,"from_cache":false}

O sistema obtem os dados e faz o cálculo diário para cada retorno, a fim de obter o máxima, média e mínima para cada dado.

Personalizando a resposta

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

https://api.hgbrasil.com/weather?array_limit=2&fields=only_results,temp,city_name,forecast,max,min,date&key=SUA-CHAVE

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

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

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

Exemplo de resposta
{"temp":30,"date":"27/04/2024","city_name":"São Paulo","forecast":[{"date":"27/04","max":30,"min":20},{"date":"28/04","max":31,"min":22}]}

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 Weather.

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.

Observe as cidades consultadas
Um dos limites mais curtos, é o número de cidades que você consulta. Deixar este campo aberto ao seu usuário pode significar bater este limite.

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

Exoneração de responsabilidade

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

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