HG Weather Documentação

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:

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
  • time - hora da consulta
  • 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
  • wind_speedy - velocidade do vento em km/h
  • sunrise - nascer do sol em horário local da cidade
  • sunset - pôr do sol em horário local da cidade
  • condition_slug - slug da condição de tempo atual veja a lista
  • city_name - nome 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
    • 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":11,"date":"20/04/2019","time":"06:26","condition_code":"29","description":"Parcialmente nublado","currently":"dia","cid":"","city":"Sao Paulo,","img_id":"29","humidity":100,"wind_speedy":"4 km/h","sunrise":"6:22 am","sunset":"5:49 pm","condition_slug":"cloudly_day","city_name":"Sao Paulo","forecast":[{"date":"20/04","weekday":"Sáb","max":26,"min":10,"description":"Parcialmente nublado","condition":"cloudly_day"},{"date":"21/04","weekday":"Dom","max":27,"min":15,"description":"Tempo nublado","condition":"cloud"},{"date":"22/04","weekday":"Seg","max":28,"min":16,"description":"Parcialmente nublado","condition":"cloudly_day"},{"date":"23/04","weekday":"Ter","max":25,"min":17,"description":"Tempestades","condition":"storm"},{"date":"24/04","weekday":"Qua","max":26,"min":17,"description":"Parcialmente nublado","condition":"cloudly_day"},{"date":"25/04","weekday":"Qui","max":26,"min":18,"description":"Parcialmente nublado","condition":"cloudly_day"},{"date":"26/04","weekday":"Sex","max":27,"min":18,"description":"Parcialmente nublado","condition":"cloudly_day"},{"date":"27/04","weekday":"Sáb","max":27,"min":18,"description":"Tempo nublado","condition":"cloud"},{"date":"28/04","weekday":"Dom","max":25,"min":19,"description":"Tempestades isoladas","condition":"storm"},{"date":"29/04","weekday":"Seg","max":19,"min":15,"description":"Parcialmente nublado","condition":"cloudly_day"}],"latitude":-23.5489,"longitude":-46.6388},"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.

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

 

Conheça as vantagens de ser membro da API

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

Quero conhecer

Obter 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



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.


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

Obter cidade por GeoIP

Com este método, informamos os dados de tempo baseado no Geo IP, o sistema busca uma localiçã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.

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.

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



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

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
{"temp":11,"date":"20/04/2019","city_name":"Sao Paulo","forecast":[{"date":"20/04","max":26,"min":10},{"date":"21/04","max":27,"min":15}]}

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.