Essa pequena aplicação tem como propósito mostrar a localização atual (aproximada) do usuário e, em seguida, os dados gerais climáticos baseados na geolocalização encontrada.

• Instalação
• Documentação

Para instalar e executar o projeto, existem alguns passos:

• Configurar o .env
• Instalar os pacotes
• Executar a aplicação

Existe um arquivo chamado .env.example. Você pode se basear nas informações já presentes nele. Para isso, renomeie o arquivo para .env. As principais chaves a serem alteradas são:

• REACT_APP_OPENWEATHER_API_KEY: a chave de API do OpenWeatherApi. Pode ser obtida em Open Weather Api - Api Keys
• REACT_APP_MAPQUEST_KEY: a chave de API do MapQuest. É utilizada para obter o reverse geocode, necessário para recuperar o endereço baseado nas coordenadas de geolocalização fornecidas pelo navegador.

As outras chaves podem permanecer as mesmas, visto que são as URLs oficiais das APIs utilizadas

Para instalar os pacotes, deve-se utilizar um dos comandos abaixo:

• yarn install
• npm instal

Para executar a aplicação, deve-se utilizar um dos comandos abaixo:

• yarn start
• npm run start

Após isso, uma aba será aberta no navegador (a URL padrão é http://localhost:3000)

Essa documentação será dividida em duas partes:

• Conceito
• API

A aplicação possui dois propósitos base: Buscar a geolocalização do usuário e exibir os dados climáticos baseados nos dados de geolocalização do usuário (além de permitir que o usuário recarregue os dados atuais)

Utilizando a API de geolocation do motor do navegador (navigator.geolocation), buscamos a posição geográfica atual do usuário. Para isso, o sistema utiliza um polyfill que calibra os dados recebidos. Mais em Calibração de GPS. Nesse ponto entra também a integração com o MapQuest (mais sobre isso em Integração com MapQuest).

Nota: A aplicação precisa, obrigatoriamente, da permissão de utilização da Localização do usuário para funcionar!

Utilizando os dados de geolocalização disponibilizados pelo navegador (e previamente calibrados), é feita uma requisição para buscar os dados gerais de clima da região no OpenWeatherAPI (mais sobre isso em Integração com OpenWeatherAPI).

A aplicação exibe os dados atuais de:

• Localização (endereço)
• Dados climáticos de temperatura
• Dados climáticos dos ventos
• Dados climáticos das chuvas (quando presente)

Fica disponível para o usuário uma ação para recarregar os dados atuais já exibidos na tela. Assim que a ação é ativada, o botão de recarga é desativado, com uma mensagem indicando o passo atual (ver mais em API - Mensagens)

A API será dividida em alguns tópicos:

• Integração com MapQuest
• Integração com OpenWeatherAPI
• Custom hook useWeahter
• Calibração de GPS
• Mensagens

A integração com o MapQuest utiliza o serviço de reverse geocoding gratuito da plataforma. Essa integração tem como propósito fornecer os dados de endereço do usuário atual, baseados na latitude e longitude fornecidas pela API de Geolocation (navigator.geolocation) Os dados retornados pela API de reverse geocoding estão no seguinte formato:

Esses dados estão descritos na interface MapQuestResponse (src/interfaces/index.ts)

A integração com o OpenWeatherAPI utiliza o serviço de climate forecast gratuito da plataforma. Essa integração tem como propósito fornecer os dados de clima/vento/chuvas do usuário atual, baseados na latitude e longitude fornecidas pela API de Geolocation (navigator.geolocation) Os dados retornados pela API de climate forecast estão no seguinte formato:

Esses dados estão descritos na interface OpenWeatherApiResponse (src/interfaces/index.ts)

Esse custom hook foi criado para gerenciar as chamadas e integrações entre a API de geolocation (navigator.geolocation), OpenWeather e MapQuest.

Ao montar o hook, a aplicação dispara a verificação de geolocalização (função loadLocation). Essa função tem como propósito os seguintes itens:

• Verificar existência e disponibilidade da API de geolocalização (navigator.geolocation).
• Calibrar a geolocalização provida pela API (mais em Calibração de GPS).
• Em caso de sucesso, atualiza o estado local com as coordenadas providas pela API.
• Em caso de erro, o parâmetro callback é chamado, com o primeiro parâmetro false, e o segundo parâmetro com a mensagem de erro (ver mais em Mensagens).

A implementação da API de Geolocalização (navigator.geolocation) em navegadores/plataformas desktop não é precisa. Isso é fato. A explicação para isso é longa, mas basicamente a API dá um retorno inicial (algumas vezes até mesmo resultados em cache) que em algumas situações não retorna com precisão as coordenadas do usuário. Em aparelhos eletrônicos portáteis (celulares, tablets, etc) essa localização é mais precisa, devido aos componentes eletrônicos de GPS.

Nesse sentido, foi utilizada uma implementação paralela da função navigator.geolocation.watchPosition, que verifica contra um threshold de precisão (padrão é 20 metros). Caso a primeira requisição não seja dentro desse parâmetro, ele busca a localização novamente, e assim sucessivamente até que uma das duas condições seja atendida: Localização dentro da tolerância de precisão OU timeout de tentativas;

Essa verificação foi baseada no seguinte trecho, e adaptada para funcionar com typescript: gregsramblings/getAccurateCurrentPosition

Nota: Esse polyfill está disponível e descrito dentro de src/geoLocationPolyfill.ts

Enquanto a calibração ocorre, uma mensagem é exibida informando que a calibração está em andamento (ver mais em Mensagens)

As mensagens exibidas dentro do sistema estão catalogadas dentro do arquivo src/messages/index.ts

Existem ainda duas mensagens que não estão dentro do arquivo src/messages/index.ts, mas que são mensagens relacionadas a outros erros e exceções inesperadas das APIs do OpenWeather e MapQuest. São elas: